Pular para o conteúdo principal
Coloque um ID de provedor e dois-pontos antes do ID do modelo, como baseten:thinking-machines/inkling-small, para executar a solicitação apenas nesse provedor, sem alternativa em outro provedor. O formato é <provider-id>:<canonical-model-id>. Os primeiros dois-pontos separam o provedor; os dois-pontos depois do namespace do modelo continuam fazendo parte do ID do modelo. Em google-ai-studio:google/gemma-4-26b-a4b:free, o provedor é google-ai-studio e o modelo é google/gemma-4-26b-a4b:free. Se você só prefere um provedor e quer uma alternativa quando ele falhar, use o ID de modelo simples com os controles de roteamento e alternativas.

Enviar uma solicitação

Use o ID qualificado em qualquer lugar onde o endpoint aceite um ID de modelo.

O que o provedor ainda precisa atender

O qualificador restringe o roteamento a um provedor; ele não pula nenhuma outra verificação. O provedor ainda precisa:
  • servir o modelo canônico no endpoint solicitado, com essa capacidade ativada
  • atender às restrições do espaço de trabalho, da chave de API, da predefinição e de privacidade
  • aceitar o nível de serviço e os parâmetros solicitados
  • ter preços configurados
Se alguma verificação falhar, a solicitação é rejeitada. O Phaseo nunca escolhe outro provedor sem avisar.

Combinar com os campos provider ou routing

O qualificador e os campos de roteamento explícitos precisam concordar. Um provider.only ou routing.only correspondente é aceito:
Uma lista de permitidos que indica outros provedores, ou uma lista de ignorados que contém o provedor qualificado, é rejeitada com provider_qualified_model_conflict:

Solicitar uma rota gratuita em um provedor

Um modelo :free qualificado só é aceito quando esse provedor tem uma rota gratuita elegível para o modelo e o endpoint. Um modelo :free canônico não significa que todos os provedores do modelo subjacente o ofereçam de graça.
A tabela de preços da rota não pode estar vazia, e todas as regras de preço atuais dela precisam ter o rótulo free e preço exatamente zero. Preços ausentes, pagos, mistos ou negativos, ou uma regra com preço zero sem o rótulo free, rejeitam a solicitação antes de ela chegar ao provedor.

IDs e aliases de provedores

Use um ID de provedor do catálogo de provedores do Phaseo (veja Provedores de API). Os IDs são convertidos para minúsculas, e aliases conhecidos de nomes antigos ou de marca são mapeados para o ID canônico: NovitaAI e novita-ai viram novita. IDs malformados e desconhecidos são rejeitados antes da seleção do provedor; eles nunca são enviados upstream como parte do nome do modelo.

Erros de validação

Um ID qualificado inválido retorna HTTP 400 com o código de erro validation_error. reason e details[].keyword indicam a causa:
Para outros formatos de erro, veja Erros e depuração.
Última modificação em 5 de novembro de 2026