IDs de modelo qualificados por provedor

Os IDs de modelo qualificados por provedor permitem selecionar um provedor específico e um modelo canônico no campo model. Use-os quando a escolha do provedor fizer parte do contrato da solicitação, e não for apenas uma preferência de roteamento.

Sintaxe

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

Por exemplo:

baseten:thinking-machines/inkling-small
deepinfra:deepseek/deepseek-v3
crofai:moonshotai/kimi-k3

Os dois-pontos iniciais separam o provedor do ID canônico do modelo. Os dois-pontos depois do namespace do modelo continuam sendo sufixos do modelo, então não há ambiguidade:

baseten:google/gemma-4-26b-a4b:free

Nesse exemplo:

baseten é o provedor solicitado
google/gemma-4-26b-a4b:free é o ID canônico do modelo na Phaseo

Envie uma solicitação

Use o identificador qualificado em qualquer endpoint que aceite um ID de modelo.

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

Comportamento do roteamento exato

A qualificação do provedor é uma restrição exata. A Phaseo limita o conjunto de provedores elegíveis ao provedor solicitado e não usa outro provedor como alternativa naquela solicitação. A qualificação não ignora os demais controles. O provedor também precisa:

expor o modelo canônico no endpoint solicitado
estar habilitado para o recurso do endpoint
atender às políticas do espaço de trabalho e da chave de API
atender às restrições de predefinição e privacidade
oferecer suporte ao nível de serviço e aos parâmetros solicitados
ter preços válidos configurados

Se qualquer uma dessas verificações falhar, a Phaseo rejeita a solicitação em vez de selecionar outro provedor silenciosamente.

Interação com campos de roteamento

O provedor qualificado e os campos de roteamento explícitos precisam estar de acordo.

{
  "model": "baseten:thinking-machines/inkling-small",
  "provider": {
    "only": ["baseten"]
  }
}

Um valor correspondente em provider.only ou routing.only é aceito. Uma lista de permissão conflitante ou uma lista de ignorados que contenha o provedor qualificado resulta em erro de validação. Por exemplo, esta solicitação é contraditória e será rejeitada:

{
  "model": "baseten:thinking-machines/inkling-small",
  "provider": {
    "only": ["deepinfra"]
  }
}

Se o provedor for apenas uma preferência e você quiser permitir alternativas entre provedores, continue usando um ID canônico sem qualificação com os controles normais de roteamento e alternativas.

Modelos gratuitos qualificados por provedor

Uma solicitação qualificada com :free só é aceita quando esse provedor específico tem uma rota gratuita elegível para o modelo canônico e o endpoint.

{
  "model": "baseten:google/gemma-4-26b-a4b:free",
  "input": "Hello"
}

A Phaseo falha de forma segura, a menos que a rota selecionada tenha uma tabela de preços não vazia e cada regra de preço atual:

esteja explicitamente marcada como free
tenha preço exatamente igual a zero

A falta de preços, preços pagos, preços mistos, preços negativos ou uma regra de preço zero sem o rótulo explícito de gratuito faz com que a solicitação seja rejeitada antes da execução no provedor.

A existência de um modelo canônico :free não significa que todos os provedores do modelo subjacente ofereçam uma rota gratuita.

Slugs e aliases de provedores

Use um slug de provedor exposto pelo catálogo da Phaseo. Os slugs são normalizados para letras minúsculas, e aliases legados ou de marca compatíveis são mapeados para o ID canônico do provedor. Por exemplo, NovitaAI e novita-ai atualmente são normalizados para novita. Slugs malformados ou desconhecidos são rejeitados antes da seleção do provedor. A Phaseo não os envia ao upstream como parte do nome do modelo.

Erros de validação

Falhas em IDs qualificados por provedor usam HTTP 400 e o código de erro principal validation_error. Consulte reason ou details[].keyword para ver a causa exata.

Motivo	Significado
`invalid_provider_slug`	A parte do provedor está vazia ou contém caracteres não compatíveis.
`unknown_provider_slug`	O slug está bem formado, mas não corresponde a um provedor Phaseo reconhecido.
`invalid_provider_qualified_model`	O identificador combinado não corresponde a `<provider>:<publisher>/<model>`.
`provider_qualified_model_conflict`	`provider.only`, `provider.ignore`, `routing.only` ou `routing.ignore` contradiz a qualificação.
`qualified_provider_unavailable`	O provedor é reconhecido, mas não oferece esse modelo no endpoint solicitado.
`qualified_free_provider_unavailable`	A rota exata do provedor não foi verificada como gratuita com preços zerados em todas as regras.

Exemplo de erro:

{
  "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"
    }
  ]
}

Escolha entre os dois formatos

Requisito	Valor de modelo recomendado
Deixar a Phaseo escolher e alternar entre provedores	`thinking-machines/inkling-small`
Exigir Baseten sem alternativa entre provedores	`baseten:thinking-machines/inkling-small`
Exigir uma rota gratuita verificada do provedor	`baseten:google/gemma-4-26b-a4b:free`

Visão geral

Modelos e roteamento

Recursos

Integrações

Espaços de trabalho e acesso

Confiabilidade e operações

Plataforma e pesquisa

Guias de migração

Comunidade

IDs de modelo qualificados por provedor

Sintaxe

Envie uma solicitação

Comportamento do roteamento exato

Interação com campos de roteamento

Modelos gratuitos qualificados por provedor

Slugs e aliases de provedores

Erros de validação

Escolha entre os dois formatos

Guias relacionados

​Sintaxe

​Envie uma solicitação

​Comportamento do roteamento exato

​Interação com campos de roteamento

​Modelos gratuitos qualificados por provedor

​Slugs e aliases de provedores

​Erros de validação

​Escolha entre os dois formatos

​Guias relacionados

Sintaxe

Envie uma solicitação

Comportamento do roteamento exato

Interação com campos de roteamento

Modelos gratuitos qualificados por provedor

Slugs e aliases de provedores

Erros de validação

Escolha entre os dois formatos

Guias relacionados