Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Adicionar Pedidos em JSON

Aula 5 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Adicionar via API
  2. Estrutura do Pedido
  3. Pedido cURL
  4. Adicionar com o SDK Python
  5. Limites de Taxa na Adição
  6. Quando Utilizar a Adição via API
  7. Validação do Pedido
  8. Pontos-chave

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-sdk oficial (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ém chat_get_completion para 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 lista batch_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 com client.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.