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

# Choosing a Model per Run

> Name the model a run's providers call, without changing the flow.

Each [`genai.model`](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model) of a flow runs the model its `model` port
names. A run can name another for that run alone, with an entry in its `input_data`: an entry addresses one provider
by its alias, and an entry with the alias `*` addresses every provider no entry names. The flow stays as it is, and a
run that names no model runs the models the flow names.

Which model one provider runs:

```mermaid theme={null}
flowchart TD
    named{"Does an entry name the provider's alias?"}
    named -->|yes| canNamed{"Can the provider run that model?"}
    canNamed -->|yes| runNamed["Runs it, chosen_by alias"]
    canNamed -->|no| refused["The run is refused when it is created"]
    named -->|no| star{"Is there a * entry?"}
    star -->|yes| canStar{"Can the provider run that model?"}
    canStar -->|yes| runStar["Runs it, chosen_by *"]
    canStar -->|no| other{"Can another provider left to * run it?"}
    other -->|yes| warned["Keeps its own model, with a warning"]
    other -->|no| refusedStar["The run is refused when it is created"]
    star -->|no| port["Runs its own model, chosen_by flow"]
```

## The entry

A run's `input_data` entry is `{"alias", "type", "value"}`, `type` being optional. For a `genai.model`, the value is
an `object` holding the model's `id`, as `<vendor>/<model>`, and optional `settings`, any of the provider's setting
ports:

```json theme={null}
[{"alias": "writer", "type": "genai.model",
  "value": {"type": "object", "object": {"id": "anthropic/claude-sonnet-5-5", "settings": {"max_output_tokens": 800}}}},
 {"alias": "*", "type": "genai.model",
  "value": {"type": "object", "object": {"id": "gemini/gemini-3.1-flash-lite"}}}]
```

* **`type`** is optional on any entry and names the component type the entry is for. Given, the entry reaches only
  components of that type, and its alias must name one. Left out, the entry reaches the data component or the
  `genai.model` holding its alias, since the two share one alias namespace. The types that take a run's input are
  `data.message`, `data.messages` and `genai.model`.
* **`*`** needs a `type`, is accepted only for `genai.model`, once per run, and reaches every `genai.model` that no
  entry names by its alias.

The first entry above runs `anthropic/claude-sonnet-5-5` on the provider whose alias is `writer`, with its output
capped at 800 tokens; the second runs `gemini/gemini-3.1-flash-lite` on every other provider of the flow that
can run it.

## Which model a provider runs

A `genai.model` runs the model of the entry naming its alias, else the model of the `*` entry, else the model of its
own `model` port. It can run a model when:

* its `vendors` has an entry for the model's vendor;
* its `allowed_models` is empty or matches the model;
* the catalog does not show the model lacking a capability the provider's components need, such as `chat` for
  `genai.chat` ([The catalog](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#the-catalog)). A model the catalog
  does not list is not checked for capabilities.

A model named by alias that its provider cannot run is refused when the run is created, with `invalid_model`: the run
never starts. A `*` model that a provider cannot run passes that provider by: that provider keeps its own model, with a
warning, and the providers that can run the `*` model run it. The run is refused for a `*` model only when no provider
left to it can run that model, or for the model's own problems, below.

A model id that is not `<vendor>/<model>`, or whose vendor is not `openai`, `anthropic` or `gemini`, is refused
whether an entry names it by alias or through `*`.

## Settings for one run

An entry's `settings` holds any of the provider's nine
[settings](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#settings). Each setting it gives replaces the
provider's for this run, and the provider's other settings stay. They are checked by the rules the provider's ports
follow, so a value out of range, or a field that is not a setting, refuses the run with `invalid_input_data`.

A setting the vendor or the model does not accept is left out of the call, as the provider's own would be, and the
provider posts one warning naming each setting left out and why. For a model the catalog does not list, only a
setting its vendor has no field for is left out.

## From each surface

* **REST.** [Create Execution](https://docs.blobhub.io/blob-types/workflow/operations/create-execution.md) takes the entries in its
  `input_data`. A refusal is a 400 holding every problem of its kind in `problems`.
* **The SDK.** `execute()` takes `model=`, `<vendor>/<model>` or `{"id", "settings"}`, sent as the `*` entry, and
  `models=`, a provider's alias to a model, one entry each ([Workflow](https://docs.blobhub.io/sdk/workflow.md)). A refusal raises
  `CommandError` with the refusal's `error` and `message`; the SDK does not expose `problems`.
* **The CLI.** `blobhub workflow execute --model <vendor>/<model>` sends the `*` entry, and
  `--model <alias>=<vendor>/<model>` one provider's entry; the option repeats and takes no settings
  ([execute](https://docs.blobhub.io/cli/workflow/commands/execute.md)). A malformed `--model` fails before any request with
  `MODEL_SELECTION_INVALID`, and a refusal fails with `API_COMMAND_FAILED`.
* **The web.** The debugger's **New Execution** button opens the **Create a New Execution** dialog, whose
  **Input Data** field takes the entries as JSON. A refusal shows as `Failed to create execution: <message>`.
* **A schedule.** A `workflow` target's `input_data` takes the same entries, and a fire whose run is refused is
  recorded as `invocation_error` with `result.error` `invocation_failed`
  ([Execution History](https://docs.blobhub.io/blob-types/scheduler/overview.md#execution-history)).
* **A listener.** A `workflow` target's `input_data` takes the same entries, checked for their shape only when the
  listener is saved; a run they cannot start ends the batch as `invocation_error`
  ([Listeners](https://docs.blobhub.io/blob-types/workflow/workflows/listeners.md#body)).

## When a run is refused

`create_execution` answers 400 and lists every problem of one kind in the run rather than the first: `message` joins the
problems' messages with `; `, and `problems` holds `[{"index", "alias", "message"}]`, `index` being the entry's position
in `input_data`. Nothing is written: no execution, no snapshot, no event, and nothing counts against a limit. The
request's shape is checked first, as for every command, with `invalid_request_body`: a `type` must be a non-empty
string, and an alias `*` or a valid alias ([Create Execution](https://docs.blobhub.io/blob-types/workflow/operations/create-execution.md)).

For a flow with two providers, `writer`, whose `vendors` lists only `openai` and whose `allowed_models` is empty, and
`judge`, whose `vendors` lists `openai` and `gemini` and whose `allowed_models` is `openai/*`, this input is refused
twice over: `writer` cannot run the Anthropic model named for it, and `judge`, the one provider left to `*`, cannot
run the `*` model.

```json input_data theme={null}
[{"alias": "writer", "type": "genai.model",
  "value": {"type": "object", "object": {"id": "anthropic/claude-sonnet-5-5"}}},
 {"alias": "*", "type": "genai.model",
  "value": {"type": "object", "object": {"id": "gemini/gemini-3.1-flash-lite"}}}]
```

```json Response theme={null}
{
  "status": "failure",
  "error": "invalid_model",
  "message": "writer has no credential for anthropic; no genai.model can run gemini/gemini-3.1-flash-lite: judge allows only openai/*",
  "problems": [
    {"index": 0, "alias": "writer", "message": "writer has no credential for anthropic"},
    {"index": 1, "alias": "*", "message": "no genai.model can run gemini/gemini-3.1-flash-lite: judge allows only openai/*"}
  ]
}
```

`error` is the code of the table below that the problems come from. The model is checked only once every entry is
addressed, so a run with problems of both kinds is refused with `invalid_input_data` alone.

`invalid_input_data`: an entry addresses nothing it can reach.

| Entry | Message |
| - | - |
| `type` names a type that takes no run input | `genai.chat takes no run input; these do: data.message, data.messages, genai.model` |
| `type` given, and no component of that type holds the alias | `no data.message has alias "ticket"`; `"ticket" is a data.messages` when one of another type holds it |
| `*` without `type` | `"*" needs a type` |
| `*` with a type other than `genai.model` | `"*" is accepted only for genai.model` |
| a second `*`, or a second entry naming one `genai.model` | `"*" is given twice for genai.model`; `genai.model "writer" is named twice` |
| a value that does not fit the component it reaches | `writer: genai.model takes an object value, not message`; `writer: settings.temprature: unknown field`; `"*": settings.temperature: must be a number from 0 to 2` |
| `*` for `genai.model` in a flow without one | `the flow has no genai.model` |

`invalid_model`: the model cannot run where the entry sends it.

| Entry | Message |
| - | - |
| an id that is not `<vendor>/<model>`, or an unknown vendor | `"gpt-6" is not <vendor>/<model>`; `unknown vendor "mistral"; known: anthropic, gemini, openai` |
| named by alias, and its `vendors` has no entry for the vendor | `writer has no credential for anthropic` |
| named by alias, and outside its `allowed_models` | `writer allows only openai/*` |
| named by alias, and the catalog model lacks a capability its consumers need | `writer needs chat; gemini/x does not do it` |
| `*` that no provider left to it can run | `no genai.model can run anthropic/x: summarizer has no credential for anthropic; judge allows only openai/*` |

A `*` left with no provider, because an entry names every `genai.model` by its alias, is unused: the checks that depend
on a provider (credential, `allowed_models`, capability) are skipped and nothing is reported for them. It is refused for
its own problems all the same: an id that is not `<vendor>/<model>`, an unknown vendor, a setting out of range.

### Not checked when the run is created

Creation reads the definition only when an entry has a `type`, the alias `*` or an `object` value. These are not
checked there:

* An entry without `type` whose alias no component holds is ignored, since a template may still read it.
* An entry without `type` whose value is not an object and whose alias a `genai.model` holds passes creation when no
  other entry makes creation read the definition. The run then ends with `flow.error`, listing the problems.
* Whether a data value's type suits its data component.
* The definition itself: Prepare runs `check_definition`, and a failing definition ends the run with `flow.error`
  `Workflow definition check failed`, the provider's own errors among its events.
* Whether the vendor's credential exists, and whether the vendor serves the model: both are found at the call, as for
  the model a flow names itself, since a credential can be deleted between creation and the call
  ([When the call fails](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#when-the-call-fails)).

## Warnings while it runs

Each `genai.model` posts these as `processor.warning` events on its node when it runs: the adapter's after its call,
the others before it. They show wherever events are shown: the debugger, `blobhub workflow execute --watch` and the
SDK's events.

| When | Warning |
| - | - |
| `*` passed it by | `The run's model anthropic/x was not used: no credential for anthropic. Ran gemini/y.` (or `not in allowed_models`, or `gemini/z does not do chat`) |
| the run named a model the catalog does not know | `anthropic/x is not in the catalog: its capabilities were not checked and every setting is sent` |
| settings are left out | `Settings left out: temperature (anthropic/claude-opus-5-5 does not accept it), seed (anthropic has no such setting)` |
| the vendor ignores part of the request | `"response_format" is specified but is not currently supported` (Anthropic, a `response_format` other than `text`) |

An unknown model in the `model` port is not warned about at run time: `check_definition` warns when the flow is saved.

## Which model ran

A provider posts one `processor.output` event per call, and its `attributes.model` names the model it ran, as
`{"id", "chosen_by"}`. `chosen_by` is `alias` for an entry naming the provider's alias, `*` for the `*` entry, and
`flow` for the provider's own `model` port, a `*` that passed it by included:

```json theme={null}
{"model": {"id": "gemini/gemini-3.1-flash-lite", "chosen_by": "*"}}
```

The model sits in the event's `attributes`, so an event listing returns it whether or not the session keeps the events'
`data` ([`tracing.log_data`](https://docs.blobhub.io/blob-types/workflow/operations/update-session)); the call's `request`, `response` and
`usage` are in `data`. [List Execution Events](https://docs.blobhub.io/blob-types/workflow/operations/list-execution-events.md) returns it, and
the filter `{"types": ["processor.output"]}` keeps only these events; the SDK's `run.events()` returns it too, and the
debugger's **Event Details** shows it.

## Templates do not choose the model

A run's model entry stays in the execution's `input_data` like any input, so a templated session alias can read it as
`{{ execution.input_data.<alias>.id }}`. A template never chooses the model: a provider runs the model of the entry
whose alias matches its `alias` port, or of `*`. A `*` entry is no one component's input, and no template sees it.


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