Migração Gradual para a API de Respostas
Nesta página
Atualizado a 3 de novembro de 2026: O mapeamento de parâmetros indicava anteriormente que
max_tokensmantinha o seu nome na API de Respostas; a tabela da xAI altera-o paramax_output_tokens, e os contadores de utilização também mudam de nome. Fonte: Comparação com Chat Completions.
Porquê e quando migrar
O endpoint Chat Completions está assinalado como legado. Continuará a funcionar, mas não receberá novas funcionalidades. Se a sua aplicação necessitar de ferramentas do lado do servidor (pesquisa na Web, execução de código), armazenamento de conversas ou raciocínio encriptado, a migração para a API de Respostas torna-se necessária.
A boa notícia: esta migração pode ocorrer gradualmente. Não precisa de reescrever tudo de uma vez.
Passo 1: Identificar as funcionalidades que utiliza
Antes de migrar, faça um balanço do que a sua aplicação utiliza com o Chat Completions:
# Audite o seu código existente
# Procure estes padrões:
# 1. Chamadas básicas (texto simples)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Chamada de funções
client.chat.completions.create(..., tools=[...])
# 4. Visão (imagens)
# mensagens com conteúdo como array [text, image_url]
# 5. Parâmetros de geração
# temperature, max_tokens, top_p, stop, seed
As chamadas básicas e o streaming são os mais simples de migrar. A chamada de funções requer adaptação do formato. A visão funciona de forma semelhante.
Passo 2: Migrar chamadas básicas
Migrar uma chamada simples segue este padrão:
# ANTES — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# DEPOIS — API de Respostas
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Mapeamento de campos
As principais alterações são:
messagescom papelsystem→instructions(parâmetro dedicado)messagescom papeluser→input(cadeia de caracteres simples)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, de acordo com a tabela de mapeamento da xAI;temperaturemantém o seu nomeresponse.usage.prompt_tokensecompletion_tokens→input_tokenseoutput_tokens(detalhes:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Passo 3: Migrar conversas de várias voltas
É aqui que a API de Respostas simplifica as coisas. Em vez de reconstruir o histórico a cada pedido, encadeia-os por ID:
# ANTES — Chat Completions (gerir o histórico manualmente)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# DEPOIS — API de Respostas (o servidor gere o histórico)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
O código é mais simples e já não precisa de gerir manualmente o array de mensagens.
Passo 4: Aproveitar as novas funcionalidades
Uma vez migrado, pode alavancar funcionalidades exclusivas da API de Respostas:
Pesquisa na Web integrada
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# A resposta inclui citações com URLs de origem
Armazenamento de respostas
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Mantém por 30 dias
)
# Recuperar mais tarde
stored = client.responses.retrieve(response.id)
Raciocínio encriptado
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# O raciocínio encriptado pode ser reutilizado em pedidos subsequentes
Estratégia de migração recomendada
Em vez de migrar tudo de uma vez, proceda por etapas:
- Identificar as chamadas Chat Completions no seu código
- Classificá-las por complexidade (básico → streaming → chamada de funções)
- Migrar primeiro os novos endpoints ou funcionalidades (greenfield)
- Depois migrar as chamadas existentes mais simples
- Manter o Chat Completions para integrações de terceiros que o exijam (LangChain, etc.)
Coexistência temporária
É perfeitamente aceitável executar ambos os endpoints lado a lado durante a transição:
# Wrapper que abstrai o endpoint utilizado
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Esta abordagem permite-lhe mudar gradualmente, testando cada migração individualmente.
Pontos-chave
- A migração pode ser gradual: não é necessário reescrever tudo de uma vez
- Principais alterações:
messages→input/instructions,choices[0].message.content→output_text - As conversas de várias voltas passam de um array de mensagens para um simples
previous_response_id - A API de Respostas dá acesso a funcionalidades exclusivas (web_search, armazenamento, raciocínio encriptado)
- Execute ambos os endpoints lado a lado durante a transição e migre por ordem de complexidade
Teste os seus conhecimentos
A API legada compreendida e a migração preparada.
1. O que significa o estatuto legado e sem estado do Chat Completions?
Resposta: O endpoint permanece suportado, mas deixa de evoluir: sendo sem estado, exige o reenvio de todo o histórico a cada chamada — a API de Respostas é o caminho moderno.
2. Quais os papéis que estruturam as mensagens?
Resposta: system (e developer), user, assistant — a estrutura, os pedidos, as respostas: todo o histórico recomeça a cada pedido.
3. Como utilizar código OpenAI existente com o Grok?
Resposta: Alterando o base_url para https://api.x.ai/v1 e a chave da API — a compatibilidade de formatos trata do resto, incluindo o SDK da OpenAI e o Vercel AI SDK.
4. O que lê na resposta e na utilização?
Resposta: choices transporta as respostas com finish_reason; usage detalha os tokens, incluindo reasoning_tokens para modelos de raciocínio — a base para o acompanhamento de custos.
5. Como migrar corretamente para a API de Respostas?
Resposta: Gradualmente: novos desenvolvimentos em Respostas, endpoints existentes convertidos um a um com novo teste de prompts — comparar os dois formatos guia a conversão.
Compreenda o legado, construa para o moderno: o plano de migração gradual do curso é o seu roteiro — sem «big bang».