Completions de Chat e Respostas em Lotes
Nesta página
Atualizado a 3 de novembro de 2026. Com base nas melhores práticas da xAI: recomenda-se definir
temperatureem 0,7 etop_pem 0,95, em vez de uma temperatura baixa. Fonte: Melhores práticas.
Atualizado a 2 de novembro de 2026. De acordo com a documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (e não 50%); os exemplos seguem a API REST e o
xai-sdkoficial (client.batch.*; a API de Lotes da xAI não utiliza o formato OpenAI, pelo que o SDK OpenAI não se aplica); e a API de Respostas tem precedência sobre as Completions de Chat, um endpoint legado na xAI. Fontes: API de Lotes · Referência REST · Preços de Lotes.
Os dois endpoints de texto em modo de lote
Os endpoints /v1/responses e /v1/chat/completions gerem a maioria dos lotes de texto. Em modelos elegíveis, ambos beneficiam do desconto de 20%. No entanto, a xAI não os considera iguais: Respostas é a API recomendada, enquanto Completions de Chat é um endpoint legado mantido para código existente. Esta lição detalha as suas especificidades num contexto de processamento em lote.
Respostas num lote
Em modo de lote, a API de Respostas aceita os mesmos parâmetros que no modo síncrono; apenas o envelope JSONL muda:
{"custom_id": "sum-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "instructions": "You are a summarization expert.", "input": "Summarize this financial report in five key points: ...", "temperature": 0.3, "max_output_tokens": 500}}
Proporciona acesso às ferramentas do servidor do Grok — pesquisa na web, pesquisa no X, execução de código, MCP — executadas durante o processamento em lote:
{"custom_id": "research-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What are the latest trends in generative AI?"}], "tools": [{"type": "web_search"}]}}
Casos de uso típicos
- Classificação de texto (sentimento, categoria, urgência)
- Extração estruturada de informações (entidades, datas, valores)
- Resumos, reformulações e traduções em escala
- Enriquecimento de dados via pesquisa na web
Completions de Chat num lote
As Completions de Chat continuam a ser aceites, com o seu formato messages:
{"custom_id": "sum-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "system", "content": "You are a summarization expert."}, {"role": "user", "content": "Summarize this financial report in five key points: ..."}], "temperature": 0.3, "max_completion_tokens": 500}}
O limite de comprimento denomina-se max_completion_tokens; o antigo max_tokens está obsoleto. Reserve este endpoint para pedidos provenientes de código já escrito para o mesmo: as novas funcionalidades chegam primeiro às Respostas.
Diferenças em lote
| Funcionalidade | Respostas | Completions de Chat |
|---|---|---|
| Estado na xAI | Recomendado | Legado |
| Formato de entrada | input (texto ou lista de mensagens), instructions | messages |
| Ferramentas do servidor | Sim (web, X, código, MCP) | Não documentado |
| Chamada de funções | Sim | Sim |
| Saídas estruturadas | text.format | response_format |
| Limite de saída | max_output_tokens | max_completion_tokens |
| Desconto de lote (modelos elegíveis) | 20% | 20% |
Parâmetros avançados comuns
temperature varia de 0 a 2 na xAI, sendo que valores superiores a 1 são amostrados como 1. Contudo, as melhores práticas da xAI recomendam defini-lo em 0,7, com top_p em 0,95, e não desviar muito disto: a consistência do lote depende primeiramente de instruções precisas e saídas estruturadas.
O limite de saída (max_output_tokens ou max_completion_tokens) deve ser definido explicitamente: sem ele, um pedido pode gerar uma resposta muito longa e consumir tokens desnecessariamente. Aplica-se apenas ao texto visível, não aos tokens de raciocínio.
Saídas estruturadas impõem um esquema JSON à resposta, tornando os resultados utilizáveis programaticamente sem necessidade de análise sintática frágil. Com Respostas, o esquema coloca-se em text.format:
{"custom_id": "classify-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "Classify this comment: « Delivery fast, product as described. »", "text": {"format": {"type": "json_schema", "name": "classification", "schema": {"type": "object", "properties": {"sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]}}, "required": ["sentiment"], "additionalProperties": false}, "strict": true}}}}
Com Completions de Chat, o equivalente é response_format, do tipo json_schema (ou json_object para JSON válido sem um esquema imposto).
Misturar os dois endpoints
Pode combinar Respostas e Completions de Chat no mesmo lote, designando cada linha o seu endpoint no campo url:
{"custom_id": "simple-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Summarize in one sentence: ..."}]}}
{"custom_id": "search-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "AI news this week", "tools": [{"type": "web_search"}]}}
Esta flexibilidade permite que pedidos antigos de Completions de Chat e novos pedidos de Respostas coexistam durante uma migração.
Pontos-chave
- Respostas é o endpoint recomendado, Completions de Chat é um endpoint legado; ambos beneficiam do desconto de 20% em modelos elegíveis
- Respostas é obrigatório para ferramentas do servidor (web, X, código, MCP)
- Defina
temperatureem 0,7 etop_pem 0,95, conforme recomenda a xAI, e estabeleça um limite de saída adequado - As saídas estruturadas utilizam
text.format(Respostas) ouresponse_format(Completions de Chat) - Ambos os endpoints podem coexistir no mesmo lote