Adicionar Pedidos em JSON
Nesta página
Atualizado a 2 de novembro de 2026 com base na documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (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 a de Conclusões de Chat, um endpoint legado na xAI. Fontes: Batch API · REST Reference · Batch Pricing.
Adicionar via API
Assim que o lote for criado, adiciona pedidos ao mesmo através de POST /v1/batches/{batch_id}/requests. Cada chamada transporta uma lista de pedidos e podes invocar o endpoint quantas vezes forem necessárias, desde que o lote não tenha sido cancelado. Esta abordagem funciona para lotes construídos de forma incremental.
Estrutura do Pedido
O corpo da chamada contém um array batch_requests. Cada elemento associa um identificador (batch_request_id) ao próprio pedido, armazenado sob a chave correspondente ao seu tipo — responses para a API de Respostas:
{
"batch_requests": [
{
"batch_request_id": "avis-001",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Classify the sentiment: positive, negative, or neutral."},
{"role": "user", "content": "The product exceeded my expectations!"}
]
}
}
}
]
}
batch_request_id: O teu identificador, único dentro do lote. Esta é a chave que associa o pedido ao seu resultado; se estiver em falta, a xAI gera um UUID.batch_request: O pedido, sob a chave do respetivo tipo; a referência da API documenta tambémchat_get_completionpara o formato de Conclusões de Chat.
Para imagens e vídeos, utiliza o SDK (lição 9) ou um ficheiro JSONL (próxima lição).
Pedido cURL
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batch_requests": [
{
"batch_request_id": "article-42",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "user", "content": "Classify this text: positive, neutral, or negative."}
]
}
}
}
]
}'
Adicionar com o SDK Python
Com o SDK, cada pedido é construído como uma conversa padrão, recebendo um batch_request_id; de seguida, adicionas esses pedidos em blocos:
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client()
documents = [
{"id": "doc-1", "text": "First document to analyze..."},
{"id": "doc-2", "text": "Second document to analyze..."},
{"id": "doc-3", "text": "Third document to analyze..."},
]
batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"
requests = []
for doc in documents:
chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
chat.append(system("Summarize the document in two sentences."))
chat.append(user(doc["text"]))
requests.append(chat)
# Adicionar em blocos de 100: uma chamada à API por bloco
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
A documentação não define um número máximo de pedidos por chamada; tamanhos de bloco moderados limitam simplesmente o que precisa de ser reenviado em caso de incidente de rede.
Limites de Taxa na Adição
Uma equipa pode efetuar até 1.000 chamadas de adição a cada 30 segundos, numa janela deslizante partilhada por todos os seus lotes. O limite aplica-se às chamadas, não aos pedidos: com blocos de 100 pedidos, isto já permite mais de 3.000 pedidos por segundo. Dois outros limites são mais relevantes:
- 25 MB máximo por pedido individual, o que diz respeito principalmente a imagens codificadas em base64.
- Além de 100.000 pedidos num lote, a xAI pode reduzir a velocidade de processamento para preservar a estabilidade do serviço.
Quando Utilizar a Adição via API
A adição via API funciona sempre que a flexibilidade importa mais do que a preparação prévia. Torna-se a escolha natural quando o lote é construído incrementalmente: os pedidos que chegam de uma fila são adicionados à medida que surgem, enquanto um ficheiro JSONL exigiria conhecer tudo antecipadamente — e fecharia o lote. É também o caminho para a prototipagem, para testar o fluxo de trabalho completo com cinco pedidos antes de escalar, e para lotes heterogéneos.
Validação do Pedido
Verifica o código de estado de cada chamada de adição: um erro nesta fase significa que o bloco não foi guardado e precisas de o reenviar. Um pedido pode também falhar mais tarde, durante o processamento; nesse caso, aparece nos resultados com a sua mensagem de erro. Um modelo que não aceite o lote é rejeitado com a mensagem not supported for batch processing: verifica a elegibilidade na página do modelo antes de lançar um lote de grande dimensão.
Pontos-chave
- A adição ocorre através de
POST /v1/batches/{id}/requests, com uma listabatch_requests. - Cada pedido transporta um
batch_request_idúnico e o seu conteúdo sob a chave do respetivo tipo (responses,chat_get_completion). - O SDK constrói pedidos com
client.chat.create(..., batch_request_id=...)e adiciona-os comclient.batch.add. - O limite é de 1.000 chamadas de adição por 30 segundos para a equipa; cada chamada pode transportar muitos pedidos.
- Ao contrário do ficheiro JSONL, a adição via API mantém o lote aberto a novas adições.