Chat Completions vs. API Responses: Comparação
Nesta página
Dois endpoints, duas filosofias
A xAI disponibiliza dois endpoints para interagir com os modelos Grok: Chat Completions (/v1/chat/completions) e a API Responses (/v1/responses). Compreender as suas diferenças é essencial para escolher o endpoint adequado ao seu projeto e planear qualquer migração potencial.
| Aspeto | Chat Completions | API Responses |
|---|---|---|
| Estado | Legado | Primário (recomendado) |
| Gestão de estado | Sem estado (enviar histórico) | Com estado (previous_response_id) |
| Armazenamento no servidor | Não | Sim (30 dias com store: true) |
| Conversa | Vetor de mensagens | Encadeada por ID |
| Ferramentas do servidor | Apenas chamada de funções | web_search, x_search, code_interpreter, functions |
| Raciocínio encriptado | Não | Sim (encrypted_content) |
| Novas funcionalidades | Não prioritárias | Prioritárias |
| Compatibilidade OpenAI | Total | Parcial |
Gestão de estado: a diferença fundamental
Chat Completions: gere o histórico
Em cada pedido, tem de reenviar toda a conversa:
# Chat Completions — reenviar tudo de cada vez
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello, my name is Alice."},
{"role": "assistant", "content": "Hello Alice! How can I help you?"},
{"role": "user", "content": "What is my first name?"}
]
)
API Responses: o servidor gere o histórico
Com a API Responses, um simples identificador basta para continuar uma conversa:
# API Responses — apenas o ID da resposta anterior
response1 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Hello, my name is Alice."
)
response2 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What is my first name?",
previous_response_id=response1.id
)
O servidor mantém o contexto e reconstrói o histórico automaticamente. Não paga menos tokens (o histórico continua a ser faturado), mas simplifica o seu código e reduz o tamanho dos seus pedidos.
Ferramentas e funcionalidades exclusivas
A API Responses dá acesso a ferramentas do servidor que o Chat Completions não oferece:
web_search: pesquisa na web em tempo realx_search: pesquisa em publicações do X (Twitter)code_interpreter: execução de código Python no lado do servidor
Estas ferramentas estão integradas diretamente no pedido:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What is the latest news on AI?",
tools=[{"type": "web_search"}]
)
O Chat Completions suporta a chamada de funções (ferramentas definidas pelo programador), mas não estas ferramentas do servidor geridas pela xAI.
Quando utilizar o Chat Completions?
O Chat Completions continua a ser a escolha certa em vários cenários:
- Migração a partir da OpenAI: o seu código existente funciona sem grandes modificações
- Multi-fornecedor: pretende alternar entre OpenAI, Anthropic e xAI com o mesmo código
- Frameworks de terceiros: LangChain, LlamaIndex, Haystack e a maioria dos frameworks utilizam o formato Chat Completions
- Controlo total: deseja gerir o histórico por conta própria (resumo, filtragem, modificação)
Quando utilizar a API Responses?
A API Responses é preferível para:
- Novos projetos: beneficiar das funcionalidades mais recentes desde o início
- Ferramentas do servidor: necessidade de pesquisa na web, execução de código ou pesquisa no X
- Conversas longas: sem necessidade de reenviar o histórico em cada pedido
- Raciocínio encriptado: acesso ao conteúdo de raciocínio para continuidade entre pedidos
Pontos-chave
- O Chat Completions é sem estado (gerida o histórico), a API Responses é com estado (o servidor gere)
- A API Responses oferece ferramentas de servidor exclusivas: web_search, x_search, code_interpreter
- O Chat Completions tem compatibilidade total com a OpenAI, a API Responses é específica da xAI
- Ambos os endpoints faturam o histórico completo da conversa
- Utilize o Chat Completions para compatibilidade, a API Responses para novas funcionalidades