> ## 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. # IDs de modelo qualificados por provedor > Roteie uma solicitação para um provedor e modelo exatos usando um único identificador de modelo. 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 ```text theme={null} : ``` Por exemplo: ```text theme={null} 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: ```text theme={null} 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. ```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() ``` ## 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. ```json theme={null} { "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: ```json theme={null} { "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](./routing-and-fallbacks.mdx). ## 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. ```json theme={null} { "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_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: ```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" } ] } ``` ## 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` | ## Guias relacionados * [Roteamento e alternativas](./routing-and-fallbacks.mdx) * [Provedores de API](../exploring/api-providers.mdx) * [Modelos](../exploring/models.mdx) * [Tratamento de erros](../api-reference/errors.mdx) * [Predefinições](./presets.mdx) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.