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

Criar um lote vazio

Aula 4 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Primeiro passo: inicialização
  2. A chamada de criação
  3. Implementação em Python
  4. Implementação em JavaScript
  5. Limites de taxa de criação
  6. Boas práticas
  7. 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 utilizam a API REST e o SDK oficial xai-sdk (client.batch.*; a API de Lotes da xAI não utiliza o formato da OpenAI, pelo que o SDK da 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: API de Lotes · Referência REST · Preços de Lotes.

Primeiro passo: inicialização

Criar um lote é a primeira ação concreta no seu fluxo de trabalho. Uma chamada POST /v1/batches inicializa um contentor vazio que receberá posteriormente os seus pedidos. Este passo é deliberadamente minimalista: cria o identificador e prepara o lote no lado do servidor.

1

POST /v1/batches

Cria um lote nomeado e devolve o seu batch_id.

2

Guardar o batch_id

Guarde o identificador para operações futuras.

3

Adicionar os pedidos

O lote está pronto para receber pedidos através da API.

A chamada de criação

O corpo do pedido contém apenas um campo obrigatório, name:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

A resposta contém o batch_id, as datas de criação e de expiração, e os contadores do lote, ainda a zero (exemplo da referência da API):

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "customer_review_analysis",
  "create_time": "2025-11-11",
  "expire_time": "2025-11-12",
  "create_api_key_id": "********-****-****-****-************",
  "cancel_time": null,
  "cancel_by_xai_message": null,
  "state": {
    "num_requests": 0,
    "num_pending": 0,
    "num_success": 0,
    "num_error": 0,
    "num_cancelled": 0
  }
}

Implementação em Python

O SDK oficial instala-se com pip install xai-sdk (versão 1.21.0 em 2 de novembro de 2026; Python 3.10 mínimo). Lê a chave a partir da variável de ambiente XAI_API_KEY:

from xai_sdk import Client

client = Client()

batch = client.batch.create(batch_name="customer_review_analysis")
batch_id = batch.batch_id
print(f"Batch created: {batch_id}")

O batch_id devolvido é a referência única do seu lote. Guarde-o numa variável, num ficheiro ou numa base de dados, consoante a sua arquitetura.

Implementação em JavaScript

Sem um SDK, um simples fetch para a API REST é suficiente:

const response = await fetch("https://api.x.ai/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "customer_review_analysis" })
});

const batch = await response.json();
console.log(`Batch created: ${batch.batch_id}`);

Limites de taxa de criação

A criação de lotes está limitada a 2 por segundo por equipa; o número total de lotes não tem limite. Na prática, raramente atingirá este limite: geralmente cria-se um lote por operação e adicionam-se todos os pedidos ao mesmo. Se criar vários num ciclo, espace as chamadas pelo menos 500 milissegundos.

Boas práticas

Nomeie os seus lotes com cuidado: o nome é obrigatório, por isso torne-o útil. Um nome que indique o conjunto de dados e a data (customer_reviews_2026_11_02) é fácil de encontrar na lista de lotes e na consola da xAI, que também lhe permite acompanhar os lotes visualmente.

Registe a expiração: expire_time indica quando o lote e os seus resultados deixam de estar acessíveis. O seu processo de recuperação deve ser executado antes dessa data.

Trate os erros de criação: um erro de autenticação, exceder o limite de taxa ou um problema de rede podem impedir a criação. Re tente erros transitórios com um atraso crescente (backoff exponencial), mas nunca re tente erros de autenticação.

Pontos-chave

  • Criar um lote é um POST /v1/batches cujo único campo obrigatório é name
  • A resposta contém um batch_id único a guardar para o restante fluxo de trabalho
  • Em Python, o SDK oficial xai-sdk expõe client.batch.create(batch_name=...)
  • O limite é de 2 criações por segundo por equipa, sem limite no número de lotes
  • Vigie o expire_time e re tente apenas erros transitórios