Convenções de Nomenclatura
Nesta página
Atualizado a 3 de novembro de 2026. Com base na página Models da xAI (secção Model Aliases): a tabela inclui o
grok-4.7, o modelo recomendado pela xAI, e ogrok-4.6. A recomendação para produção segue as orientações da xAI, que aconselha utilizar o alias para a maioria dos casos de uso e a versão datada para fluxos de trabalho que exigem consistência estrita. Fonte: Models.
Compreender os identificadores de modelo
Quando invoca a API da xAI, o campo model determina qual o modelo que processa o seu pedido. A xAI utiliza um sistema de nomenclatura estruturado com aliases e versões fixas. Compreender este sistema é essencial para gerir a estabilidade e a migração das suas aplicações.
Os três formatos de identificador
A xAI oferece três formas de referenciar um modelo, cada uma com um comportamento distinto:
Alias simples
{
"model": "grok-4.20"
}
O alias simples aponta para a versão estável mais recente do modelo. Quando a xAI lança uma atualização menor, o alias redireciona automaticamente para a nova versão. A sua aplicação utiliza sempre a versão estável mais recente sem alterações de código.
Vantagem: beneficia automaticamente das melhorias. Risco: o comportamento pode mudar ligeiramente de uma versão para a outra.
Alias “latest”
{
"model": "grok-4.20-latest"
}
O alias “latest” aponta para a versão de vanguarda — a iteração mais recente, incluindo versões ainda não promovidas para estáveis. Esta é a versão mais recente, mas potencialmente a menos testada.
Vantagem: acesso imediato às últimas melhorias. Risco: o comportamento pode mudar a qualquer momento; são possíveis regressões.
Versão fixa (Pinned)
{
"model": "grok-4.20-0309"
}
A versão fixa identifica uma versão específica do modelo, indexada pela sua data de lançamento (neste caso, 9 de março). Esta versão nunca muda: o comportamento que observa hoje será idêntico daqui a seis meses.
Vantagem: estabilidade total, resultados reproduzíveis. Risco: a versão será eventualmente descontinuada e depois removida.
Identificadores completos atuais
| Identificador da API | Tipo | Comportamento |
|---|---|---|
| grok-4.20-0309-reasoning | Versão fixa | Nunca muda |
| grok-4.20-0309-non-reasoning | Versão fixa | Nunca muda |
| grok-4.20-multi-agent-0309 | Versão fixa | Nunca muda |
| grok-4.7 | Alias | Versão estável mais recente do modelo recomendado pela xAI |
| grok-4.6 | Alias | Versão estável mais recente |
| grok-4.5 | Alias | Versão estável mais recente (alias `grok-4.5-latest` para a mais recente de todas) |
| grok-4.3 | Alias | Versão estável mais recente |
| grok-build-0.1 | Alias | Modelo de código, versão estável mais recente |
Ciclo de vida do modelo
Cada modelo da xAI segue um ciclo de vida de três fases:
- Ativo — o modelo está disponível e recomendado para uso em produção
- Descontinuado — o modelo continua a funcionar, mas a xAI recomenda a migração para uma versão mais recente. É anunciado um prazo antes da remoção
- Obsoleto — o modelo é removido. Os pedidos para este modelo falham
Fique atento aos anúncios de descontinuação na consola da xAI e nas notas de lançamento. Quando um modelo for descontinuado, planeie a sua migração sem esperar pela data de remoção.
Recomendações por ambiente
Desenvolvimento
Utilize aliases simples (grok-4.7, grok-4.3) para beneficiar automaticamente das melhorias. No desenvolvimento, uma ligeira alteração de comportamento entre versões é aceitável e permite-lhe detetar incompatibilidades antes da produção.
Staging e testes
Utilize versões fixas (grok-4.20-0309-reasoning) para garantir a reprodutibilidade dos testes. Se um teste passar hoje, deve passar amanhã com exatamente o mesmo resultado.
Produção
A xAI recomenda o alias simples ou o alias -latest para a maioria dos casos de uso, permitindo-lhe beneficiar automaticamente de novas funcionalidades, e reserva a versão datada para fluxos de trabalho que exigem consistência estrita. Se a sua produção se enquadrar nesta categoria — resultados auditáveis, conformidade, testes de regressão — fixe a versão datada e planeie migrações periódicas após validação em staging.
Migração entre versões
Quando migrar de uma versão para outra:
- Atualize o campo
modelnos seus pedidos - Teste os seus prompts existentes — os modelos mais recentes podem responder de forma diferente
- Verifique os parâmetros da API — uma nova versão pode suportar ou descontinuar certos parâmetros
- Valide os resultados — compare qualitativamente as saídas das versões antiga e nova
Endpoints da API
A xAI mantém dois endpoints principais:
/v1/responses— o endpoint principal, recomendado para todos os novos projetos/v1/chat/completions— o endpoint legado, mantido para compatibilidade com clientes existentes
O endpoint legado já não recebe novas funcionalidades. Se estiver a iniciar um novo projeto, utilize exclusivamente o /v1/responses.
Pontos-chave
- Três formatos: alias simples (estável), alias “latest” (vanguarda), versão fixa (imutável)
- Em produção, utilize versões fixas para estabilidade
- No desenvolvimento, utilize aliases para beneficiar das melhorias
- Fique atento aos anúncios de descontinuação e planeie as suas migrações
- O endpoint recomendado é
/v1/responses, não/v1/chat/completions - Teste sempre os seus prompts ao migrar de versão