Provider-qualified model IDs

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

<provider-id>:<canonical-model-id>

For example:

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:

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.

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."
  }'

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();

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()

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.

{
  "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:

{
  "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.

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.

{
  "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.

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

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:

{
  "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`

Overview

Models & Routing

Features

Integrations

Workspace & Access

Reliability & Operations

Platform & Research

Migration Guides

Community

Provider-qualified model IDs

Syntax

Send a request

Exact routing behaviour

Interaction with routing fields

Provider-qualified free models

Provider slugs and aliases

Validation errors

Choosing between the two forms

​Syntax

​Send a request

​Exact routing behaviour

​Interaction with routing fields

​Provider-qualified free models

​Provider slugs and aliases

​Validation errors

​Choosing between the two forms

​Related guides

Syntax

Send a request

Exact routing behaviour

Interaction with routing fields

Provider-qualified free models

Provider slugs and aliases

Validation errors

Choosing between the two forms

Related guides