Skip to main content
A provider for every model vendor. One component names a default model (<vendor>/<model>), a vendors list holding one credential per vendor, and the sampling settings shared by every vendor. genai.chat and genai.agent.basic reach it through their model ports. The vendors are openai, anthropic and gemini. A call picks its model first, then takes the credential and endpoint from that model’s vendor entry, and calls that vendor’s API:

Ports

The ports below are data inputs, which the editor shows in three groups, Model, Vendors and Settings. A genai.model has no flow ports: it is connected to the model port of each component it serves. vendors is keyed by vendor, so no two entries name the same vendor. Each entry’s fields, by their labels in the editor: Stored in a definition, the port holds a list value whose items are plain data, a credential by its alias:

Model ids

A model id is <vendor>/<model>, split at the first /: anthropic/claude-sonnet-5-5 is the model claude-sonnet-5-5 of the vendor anthropic. The vendor names the API that is called, not the model’s maker, so a model on a server speaking OpenAI’s API is an openai id however it was made. The vendors are openai, anthropic and gemini. An id without a vendor and a model, or with another vendor, is an error in the model port, and a run naming one is refused.

The catalog

The catalog lists the models BlobHub knows, with what each can do, the settings it accepts, its context window and its maximum output, in tokens. It is served with the workflow manifest, so the editor’s model picker offers the same models.
  • A model the catalog does not list is accepted. check_definition warns about one in the model port, and a run naming one posts a warning on the provider’s node, anthropic/x is not in the catalog: its capabilities were not checked and every setting is sent. Its capabilities are not checked, and every setting its vendor has is sent.
  • A component’s model port names the capability its model needs: chat, for genai.chat and for each of the basic agent’s five model ports. A catalog model without it is an error in the model port, and a run naming one for that provider by its alias is refused; through * that provider keeps its own model, with a warning, unless no provider left to * can run it, which refuses the run.
  • The catalog changes only with a platform release.

Settings

The nine settings are max_output_tokens, temperature, top_p, top_k, stop_sequences, seed, frequency_penalty, presence_penalty and reasoning_effort. A value goes to the vendor unchanged, and a setting left unset is not sent, so the vendor’s own default applies, except that an Anthropic call with no max_output_tokens sends 16,000, the API requiring a value. The editor seeds a setting with a default, but only a value the definition stores is sent. Each setting a run gives replaces the provider’s for that run; the others stay. A run’s settings are checked against the same ranges, so an out-of-range value refuses the run (invalid_input_data). Each setting becomes a field of the vendor’s own API: A setting the vendor has no field for, or that the catalog model does not accept, is left out of the call, and the provider posts one warning naming each setting left out and why:
For a model the catalog does not know, only a setting its vendor has no field for is left out. vendor_settings holds extra request fields per vendor. Only the selected vendor’s block is sent, as the SDK’s extra body (extra_body for OpenAI and Anthropic, http_options.extra_body in Gemini’s config), so a field the SDK does not know still reaches the API.

Vendors and credentials

vendors holds one entry per vendor the provider may call. An entry’s credential is the alias of an api_key credential, resolved against whoever started the run, as every credential is (How a run uses one). The provider loads only the credential of the selected model’s vendor, so a vendor it does not call needs no credential where it runs: a provider listing three vendors runs where only one of those credentials exists, as long as the model it runs is that vendor’s. A credential’s type says how a service authenticates, not which service it is, so any api_key credential fits any entry. A key in the wrong entry fails at the first call with the vendor’s own error. base_url, the Endpoint, points that vendor’s calls at another server speaking the same API, such as an OpenAI-compatible one. A model served there is usually not in the catalog, and is treated as any unknown model. allowed_models holds the models a run may name: exact ids, or <vendor>/* for every model of a vendor. Empty allows every model.

Checks

check_definition reports these on the component. Prepare runs it before every run, and a definition that fails it ends the run with flow.error Workflow definition check failed. Errors:
  • model is not <vendor>/<model>, or names an unknown vendor.
  • vendors has no entry for the vendor of the model port’s model.
  • A vendors entry without a vendor or a credential, an unknown vendor, or two entries for one vendor: a list or object port whose value does not fit its shape is an error, as on every component.
  • A base_url that does not start with http:// or https://.
  • An allowed_models entry that is neither an id nor <vendor>/*.
  • An alias that another genai.model or a data component of the definition also holds.
  • A catalog model in the model port that lacks a capability a consuming port declares.
Warnings:
  • The model port’s model is not in the catalog.
  • An exact id in allowed_models lacks a capability the consumers need.
  • vendor_settings names an unknown vendor.
  • A setting port holds a value that the model port’s catalog model does not accept: <setting> is not sent to <id>: it does not accept it.
  • An allowed_models entry’s vendor has no vendors entry: Allowed model <entry> has no vendors entry for <vendor>: a run naming it is refused with invalid_model.

When the call fails

A failed call posts a processor.error event, and the component the provider serves takes its failure route. A call fails when:
  • the vendor’s credential alias names no credential where the run runs: "<alias>" credential alias not found;
  • the vendor answers with an error, such as for an unknown model or a value it refuses: its own text reaches the event unchanged;
  • the call times out, or cannot connect after its one retry;
  • Anthropic stops the answer as a refusal: refusal: <category>, or refusal alone when the vendor gives no category;
  • Gemini blocks the prompt: refusal: <reason>, or no_candidates when the reply has no candidate and no reason.
Other refusals do not fail the call: an OpenAI answer with no text or stopped by its content filter, and a Gemini answer stopped for SAFETY, arrive as an empty or partial message on success. A call is retried once, on a 502 or 503, or on a connection refused before the request was sent. It is never retried on a timeout or on a connection broken after the request was sent, which could bill the call twice.

With logic.code

A genai.model has no credential port: its credentials sit inside its vendors list. Wired to a logic.code, it hands the code no credential, and get_provider_credential finds none on it. Code that calls a vendor itself gets the key from a logic.generic_provider holding the credential.

Choosing the model per run

A run can name the model each genai.model calls, and replace the settings it gives for that run (the others stay), with an input_data entry of type genai.model that addresses one provider by its alias, or every provider no entry names by alias, by *. Choosing a Model per Run covers the entry, what refuses it, and the SDK’s and the CLI’s options for it.

Moving from the per-vendor chat providers

genai.model replaced the three per-vendor chat providers, genai.chat.openai, genai.chat.anthropic and genai.chat.gemini, and the platform’s migration rewrote the stored definitions and credentials that used them:
  • Each per-vendor provider became a genai.model with the model <vendor>/<model>, a vendors entry holding its credential alias and, when it was not the vendor’s own, its endpoint, and its stored settings. A migrated flow sends what it sent before: Anthropic’s implicit max_tokens of 1024 was written out, and an Anthropic provider’s temperature was halved, as the old provider did on every call.
  • A setting stored on a chat component overrode its provider’s for that component alone, so a provider shared by chat components that overrode different settings was copied, one per component.
  • response_format and response_schema held on an OpenAI or Gemini provider moved to the chat components it served.
  • genai.chat’s chat route became model, and the basic agent’s generic_chat, planning_chat, tool_use_chat, tool_response_chat and response_chat routes became generic_model, planning_model, tool_use_model, tool_response_model and response_model.
  • providers, the per-message override, was removed from every message a definition holds. Messages stored in session objects and thread items keep it, and nothing reads it.
  • Credentials of the types openai, anthropic, gemini, pinecone, firecrawl and tavily became api_key.
A definition the migration could not rewrite, such as one in which a logic.code read a per-vendor provider’s credential, was left unchanged for a person to fix; such code is rewired to a logic.generic_provider. Execution snapshots are history and keep the retired types, so the debugger still draws an old run’s provider under its old name. A local copy pulled before the migration still holds the retired types: pull it again before the next deploy. blobhub workflow deploy uploads a changed definition before it checks it, so deploying an old copy writes the retired types back to the revision. The check then fails with Component type `genai.chat.openai` is not supported, and every run of the definition ends with flow.error Workflow definition check failed. A per-message override has no successor: name the model per run instead (Choosing a Model per Run).