Modelos

O id de um modelo nomeia o modelo e onde ele roda. Esta página explica os ids, as listas que os devolvem e como saber quais modelos você realmente pode chamar.

Ids de modelo#

O id canônico é <model>@<server>:

Estes ids são exemplos.

A parte do modelo pode conter : e /. O sufixo depois do último @ é o servidor. Trate o id inteiro como uma string opaca: copie-o de uma lista, não o monte.

A forma antiga model#server ainda é aceita na entrada e nunca é devolvida.

Use o id completo#

Se você enviar um nome sem @server, o gateway procura um modelo com esse nome no melhor servidor disponível. Se não achar nenhum, ele não devolve erro. Responde com outro modelo: o primeiro que o servidor padrão lista para você.

curl -s "$SHVIA_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "a-model-that-does-not-exist", "messages": [{ "role": "user", "content": "hi" }] }'

A resposta tem status 200, e o campo model dela é o modelo que o gateway resolveu para a requisição, não o nome que você enviou. Nos endpoints nativos isso vale para profile_name; os campos separados model e server são estritos, e um par desconhecido é respondido com um erro. Um nome com um servidor explícito que não tem o modelo devolve 404 com o código model_not_found.

Quando o modelo que você pediu não consegue responder#

Em /v1/messages, /v1/responses, /v1/chat/completions (para modelos cujo driver não é ollama) e POST /api/v1/agent/chat, o gateway monta uma cadeia curta: o modelo que você pediu e depois o modelo padrão da sua conta. Se o primeiro não consegue responder, por exemplo porque é um modelo de nuvem e você não cadastrou uma chave do provedor dele, ou porque o provedor falha com algo que outro modelo pode resolver (veja combos para a lista) antes de enviar qualquer texto, o modelo padrão responde no lugar. Um modelo dos servidores do próprio operador só tem como reserva outro modelo desses servidores. Em /v1 a chamada tem sucesso com 200, e o campo model e o header X-Inference-Model continuam mostrando o modelo que você pediu: a resposta não diz que outro modelo respondeu. agent/chat nomeia o modelo que respondeu.

Se importa qual modelo responde, tenha a chave dos modelos de nuvem em que você confia (veja provedores e suas chaves) e confira que os modelos que você chama são os que você pediu antes de confiar num resultado.

GET/v1/models#

A lista compatível com OpenAI. Ela exige a sua chave de API e não recebe parâmetros.

{
  "object": "list",
  "data": [
    { "id": "claude-sonnet-4-6@anthropic", "object": "model", "created": 1767225600, "owned_by": "shvia" }
  ]
}

owned_by é sempre shvia. Não há paginação, nem metadados por modelo, nem rota para ler um modelo pelo id (/v1/models/{id}), então client.models.retrieve(...) nos SDKs da OpenAI devolve 404.

Esta lista é o que o gateway expõe. Não é uma lista de modelos que você tem permissão de usar:

• ela inclui modelos de nuvem mesmo quando você não cadastrou uma chave daquele provedor;
• ela não filtra pelos modelos permitidos do seu grupo nem pela sua cota.

Chamar um modelo listado que você não pode usar nem sempre falha do jeito que se espera: ele é recusado com 403 e o código permission_denied quando o seu grupo ou a sua cota o proíbem, e um modelo de nuvem sem chave de provedor por trás pode ser atendido pelo seu modelo padrão no lugar, como descrito acima.

GET/api/v1/profiles#

A lista nativa, e a melhor para "de quais modelos eu tenho credenciais". Ela exige a sua chave de API e devolve uma entrada por modelo visível a você. Modelos de nuvem aparecem só quando você tem uma credencial do provedor.

{
  "profiles": [
    {
      "name": "claude-sonnet-4-6@anthropic",
      "label": "claude-sonnet-4-6",
      "model": "claude-sonnet-4-6",
      "server": "anthropic",
      "driver": "anthropic",
      "data_locality": "cloud_us",
      "efforts": ["low", "medium", "high"],
      "price_tier": "$$",
      "price": { "in": 3.0, "out": 15.0 },
      "parameter_size": null,
      "quantization": null,
      "is_default": false
    }
  ]
}

Os campos em que vale confiar:

O tratamento do esforço depende do driver. Para a Anthropic, um valor fora do enum de esforço do driver é ignorado. Com uma whitelist não vazia configurada para o modelo, um nível válido fora da lista vira o nível permitido mais próximo abaixo dele, ou o menor permitido acima se nenhum for inferior. Sem essa whitelist, o driver repassa um nível válido solicitado. Não trate essa lista anunciada como uma regra universal de validação de requisições para todos os provedores.

A resposta traz também outros campos que servem aos apps (favoritos, um mapa de servidores, flags obsoletas). Não dependa deles. A resposta traz os headers Deprecation e Sunset, que se referem a alguns desses campos obsoletos.

POST/api/v1/profiles/refresh#

Descarta a sua lista em cache de modelos de nuvem e devolve o mesmo corpo de GET /api/v1/profiles. Chame depois de cadastrar uma chave de provedor.

Qual lista usar#