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

# Provider-qualified model IDs

> Route a request to one exact provider and model using a single model identifier.

Provider-qualified model IDs let you select an exact provider and canonical model in the `model` field. Use them when provider choice is part of the request contract rather than a routing preference.

## Syntax

```text theme={null}
<provider-id>:<canonical-model-id>
```

For example:

```text theme={null}
baseten:thinking-machines/inkling-small
deepinfra:deepseek/deepseek-v3
crofai:moonshotai/kimi-k3
```

The first colon separates the provider from the canonical model ID. Colons after the model namespace remain model suffixes, so this is unambiguous:

```text theme={null}
baseten:google/gemma-4-26b-a4b:free
```

In that example:

* `baseten` is the requested provider
* `google/gemma-4-26b-a4b:free` is the canonical Phaseo model ID

## Send a request

Use the qualified identifier anywhere the endpoint accepts a model ID.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.phaseo.app/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "baseten:thinking-machines/inkling-small",
      "input": "Explain mixture-of-experts routing in two sentences."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.phaseo.app/v1/responses", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "baseten:thinking-machines/inkling-small",
      input: "Explain mixture-of-experts routing in two sentences.",
    }),
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.phaseo.app/v1/responses",
      headers={
          "Authorization": f"Bearer {os.environ['PHASEO_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "baseten:thinking-machines/inkling-small",
          "input": "Explain mixture-of-experts routing in two sentences.",
      },
  )

  result = response.json()
  ```
</CodeGroup>

## Exact routing behaviour

A provider qualifier is an exact constraint. Phaseo narrows the eligible provider set to the requested provider and will not fall back to another provider for that request.

The qualifier does not bypass other controls. The provider must still:

* expose the canonical model on the requested endpoint
* be enabled for the endpoint capability
* satisfy workspace and API key policies
* satisfy preset and privacy restrictions
* support the requested service tier and parameters
* have valid pricing configured

If any of these checks fail, Phaseo rejects the request rather than silently selecting another provider.

## Interaction with routing fields

The qualified provider and explicit routing fields must agree.

```json theme={null}
{
  "model": "baseten:thinking-machines/inkling-small",
  "provider": {
    "only": ["baseten"]
  }
}
```

A matching `provider.only` or `routing.only` value is accepted. A conflicting allowlist, or an ignore list containing the qualified provider, returns a validation error.

For example, this request is contradictory and is rejected:

```json theme={null}
{
  "model": "baseten:thinking-machines/inkling-small",
  "provider": {
    "only": ["deepinfra"]
  }
}
```

If provider choice is only a preference and cross-provider fallback is desirable, continue using an unqualified canonical model ID with the normal [routing and fallback controls](./routing-and-fallbacks).

## Provider-qualified free models

A qualified `:free` request is accepted only when that exact provider has an eligible free route for the canonical model and endpoint.

```json theme={null}
{
  "model": "baseten:google/gemma-4-26b-a4b:free",
  "input": "Hello"
}
```

Phaseo fails closed unless the selected route has a non-empty pricing card where every current pricing rule:

* is explicitly labelled `free`
* has a price of exactly zero

Missing pricing, paid pricing, mixed pricing, negative pricing, or a zero-priced rule that is not explicitly labelled `free` causes the request to be rejected before provider execution.

<Note>
  The existence of a canonical `:free` model does not imply that every provider serving the underlying model offers a free route.
</Note>

## Provider slugs and aliases

Use a provider slug exposed by Phaseo's provider catalogue. Slugs are normalised to lowercase, and supported legacy or brand aliases are mapped to their canonical provider ID.

For example, `NovitaAI` and `novita-ai` currently normalise to `novita`.

Malformed and unknown slugs are rejected before provider selection. Phaseo does not send them upstream as part of the model name.

## Validation errors

Provider-qualified identifier failures use HTTP `400` with the top-level error code `validation_error`. Inspect `reason` or `details[].keyword` for the precise cause.

| Reason                                | Meaning                                                                                            |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `invalid_provider_slug`               | The provider portion is empty or contains unsupported characters.                                  |
| `unknown_provider_slug`               | The slug is well formed but is not a recognised Phaseo provider.                                   |
| `invalid_provider_qualified_model`    | The combined identifier does not match `<provider>:<publisher>/<model>`.                           |
| `provider_qualified_model_conflict`   | `provider.only`, `provider.ignore`, `routing.only`, or `routing.ignore` contradicts the qualifier. |
| `qualified_provider_unavailable`      | The provider is recognised but does not expose that model on the requested endpoint.               |
| `qualified_free_provider_unavailable` | The exact provider route is not verified as explicitly free with all-zero pricing.                 |

Example error:

```json theme={null}
{
  "error": "validation_error",
  "status_code": 400,
  "reason": "unknown_provider_slug",
  "description": "Unknown provider slug \"not-a-provider\" in provider-qualified model \"not-a-provider:publisher/model\". Use a provider slug returned by Phaseo's provider catalogue.",
  "provider": "not-a-provider",
  "model": "publisher/model",
  "details": [
    {
      "path": ["model"],
      "keyword": "unknown_provider_slug"
    }
  ]
}
```

## Choosing between the two forms

| Requirement                                       | Recommended model value                   |
| ------------------------------------------------- | ----------------------------------------- |
| Let Phaseo choose and fall back between providers | `thinking-machines/inkling-small`         |
| Require Baseten with no cross-provider fallback   | `baseten:thinking-machines/inkling-small` |
| Require one verified free provider route          | `baseten:google/gemma-4-26b-a4b:free`     |

## Related guides

* [Routing and Fallbacks](./routing-and-fallbacks)
* [API Providers](../exploring/api-providers)
* [Models](../exploring/models)
* [Error Handling](../developers/error-handling)
* [Presets](./presets)