> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Provider (genai.model)

> One provider for every model vendor: the model, a credential per vendor, and the settings vendors share.

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:

```mermaid theme={null}
flowchart LR
    alias["A run's entry for its alias"] -->|first| id
    star["A run's entry for *"] -->|then| id
    port["The model port"] -->|otherwise| id
    id["Model id #lt;vendor#gt;/#lt;model#gt;"] --> entry["Its vendor's entry in vendors: credential, endpoint"]
    entry --> openai["OpenAI API"]
    entry --> anthropic["Anthropic API"]
    entry --> gemini["Gemini 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.

| Route | Group | Value | Notes |
| - | - | - | - |
| `alias` | Model | `text` | Names the component for a run's input. Unique among the definition's `genai.model` and `data` components, because a run's inputs address both by alias. |
| `model` | Model | `text` | The model the component runs when a run names none, as `<vendor>/<model>`. Required. |
| `allowed_models` | Model | `list` of `text` | The models a run may name: exact ids or `<vendor>/*`. Empty allows every model. |
| `vendors` | Vendors | `list` of `object`, keyed by `vendor` | One entry per vendor the component may call, with the fields below. Required. |
| `max_output_tokens` | Settings | `integer`, from 1 | |
| `temperature` | Settings | `float`, from 0 to 2 | 2 is the widest any of the three vendors accepts. |
| `top_p` | Settings | `float`, from 0 to 1 | |
| `top_k` | Settings | `integer`, from 1 | |
| `stop_sequences` | Settings | `list` of `text` | |
| `seed` | Settings | `integer` | |
| `frequency_penalty`, `presence_penalty` | Settings | `float`, from -2 to 2 | |
| `reasoning_effort` | Settings | `choice`: `low`, `medium`, `high` | |
| `vendor_settings` | Settings | `object` of any shape | `{"<vendor>": {…}}`: extra request fields for one vendor. |

`vendors` is keyed by `vendor`, so no two entries name the same vendor. Each entry's fields, by their labels in the
editor:

| Field | Label | Value | Notes |
| - | - | - | - |
| `vendor` | Vendor | `choice`: `openai`, `anthropic`, `gemini` | Required. |
| `credential` | Credential | the alias of an `api_key` credential | Required. |
| `base_url` | Endpoint | `text` | Another server speaking the vendor's API. Optional. |

Stored in a definition, the port holds a `list` value whose items are plain data, a credential by its alias:

```json theme={null}
{"type": "list", "list": [
  {"vendor": "anthropic", "credential": "anthropic-key"},
  {"vendor": "openai", "credential": "openai-key", "base_url": "https://llm.example.com/v1"}
]}
```

## 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.

| Model | Label | Capabilities | Settings accepted | Context window | Max output tokens |
| - | - | - | - | - | - |
| `anthropic/claude-fable-5-2` | Claude Fable 5.2 | `chat` | `max_output_tokens`, `stop_sequences`, `reasoning_effort` | 1,000,000 | 128,000 |
| `anthropic/claude-opus-5-5` | Claude Opus 5.5 | `chat` | `max_output_tokens`, `stop_sequences`, `reasoning_effort` | 1,000,000 | 128,000 |
| `anthropic/claude-sonnet-5-5` | Claude Sonnet 5.5 | `chat` | `max_output_tokens`, `stop_sequences`, `reasoning_effort` | 1,000,000 | 128,000 |
| `anthropic/claude-haiku-5-5` | Claude Haiku 5.5 | `chat` | `max_output_tokens`, `stop_sequences`, `reasoning_effort` | 1,000,000 | 128,000 |
| `openai/gpt-6-astra` | GPT-6 Astra | `chat` | `max_output_tokens`, `temperature`, `top_p`, `stop_sequences`, `seed`, `frequency_penalty`, `presence_penalty`, `reasoning_effort` | 1,000,000 | 128,000 |
| `openai/gpt-6-luna` | GPT-6 Luna | `chat` | `max_output_tokens`, `temperature`, `top_p`, `stop_sequences`, `seed`, `frequency_penalty`, `presence_penalty`, `reasoning_effort` | 400,000 | 128,000 |
| `gemini/gemini-3.1-pro-preview` | Gemini 3.1 Pro (preview) | `chat` | `max_output_tokens`, `temperature`, `top_p`, `top_k`, `stop_sequences`, `seed`, `reasoning_effort` | 1,048,576 | 65,536 |
| `gemini/gemini-3-flash-preview` | Gemini 3 Flash (preview) | `chat` | `max_output_tokens`, `temperature`, `top_p`, `top_k`, `stop_sequences`, `seed`, `reasoning_effort` | 1,048,576 | 65,536 |
| `gemini/gemini-3.1-flash-lite` | Gemini 3.1 Flash-Lite | `chat` | `max_output_tokens`, `temperature`, `top_p`, `top_k`, `stop_sequences`, `seed`, `reasoning_effort` | 1,048,576 | 65,536 |

* **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:

| Setting | OpenAI (Chat Completions) | Anthropic (Messages) | Gemini (`generate_content`) |
| - | - | - | - |
| `max_output_tokens` | `max_completion_tokens` | `max_tokens`; unset sends 16,000 | `max_output_tokens` |
| `temperature`, `top_p` | `temperature`, `top_p` | `temperature`, `top_p` | `temperature`, `top_p` |
| `top_k` | — | `top_k` | `top_k` |
| `stop_sequences` | `stop` | `stop_sequences` | `stop_sequences` |
| `seed` | `seed` | — | `seed` |
| `frequency_penalty`, `presence_penalty` | `frequency_penalty`, `presence_penalty` | — | `frequency_penalty`, `presence_penalty` |
| `reasoning_effort` | `reasoning_effort` | `output_config={"effort": v}` | `thinking_config.thinking_level = v` |

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:

```text theme={null}
Settings left out: temperature (anthropic/claude-opus-5-5 does not accept it), seed (anthropic has no such setting)
```

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](https://docs.blobhub.io/general/credentials.md#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`](https://docs.blobhub.io/blob-types/workflow/workflows/component-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](https://docs.blobhub.io/blob-types/workflow/workflows/choosing-a-model.md) 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](https://docs.blobhub.io/blob-types/workflow/workflows/choosing-a-model.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.