Batch API
Processe grandes volumes de requisições de forma assíncrona com 50% de desconto.
Visão Geral
A Batch API permite enviar grandes volumes de requisições para processamento assíncrono. Os jobs de batch são processados em fila com prioridade reduzida, oferecendo 50% de desconto em relação ao preço da API em tempo real. Ideal para tarefas que não exigem resposta imediata.
Endpoints
| Endpoint | Método | Descrição |
|---|---|---|
/v1/batches | POST | Criar um job de batch |
/v1/batches/{batch_id} | GET | Consultar status de um batch |
/v1/batches | GET | Listar todos os batches |
/v1/batches/{batch_id}/cancel | POST | Cancelar um batch |
/v1/files | POST | Upload do arquivo JSONL |
/v1/files/{file_id}/content | GET | Download dos resultados |
Formato JSONL
Cada linha do arquivo JSONL representa uma requisição individual:
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "urso-base", "messages": [{"role": "user", "content": "Resuma o artigo 5 da Constituição Federal."}], "max_tokens": 500}}
{"custom_id": "req-002", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "urso-base", "messages": [{"role": "user", "content": "Explique o que é LGPD."}], "max_tokens": 500}}
{"custom_id": "req-003", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "urso-base", "messages": [{"role": "user", "content": "Quais são os direitos do consumidor?"}], "max_tokens": 500}}Fluxo Completo
Python
from openai import OpenAI
import json
import time
client = OpenAI(
base_url="https://api.polar-ai.com/v1",
api_key="pk-your-key-here"
)
# 1. Criar arquivo JSONL
requests = [
{
"custom_id": f"req-{i:03d}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "urso-base",
"messages": [{"role": "user", "content": question}],
"max_tokens": 500
}
}
for i, question in enumerate([
"Resuma o artigo 5 da Constituição Federal.",
"Explique o que é LGPD.",
"Quais são os direitos do consumidor?",
"O que é o Simples Nacional?",
"Explique o FGTS."
])
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# 2. Fazer upload do arquivo
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch"
)
print(f"Arquivo enviado: {batch_file.id}")
# 3. Criar o job de batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h"
)
print(f"Batch criado: {batch.id}")
# 4. Aguardar conclusão
while True:
batch_status = client.batches.retrieve(batch.id)
print(f"Status: {batch_status.status} ({batch_status.request_counts.completed}/{batch_status.request_counts.total})")
if batch_status.status in ["completed", "failed", "cancelled"]:
break
time.sleep(30)
# 5. Recuperar resultados
if batch_status.status == "completed":
result_file = client.files.content(batch_status.output_file_id)
results = result_file.text
for line in results.strip().split("\n"):
result = json.loads(line)
print(f"\n{result['custom_id']}:")
print(result['response']['body']['choices'][0]['message']['content'][:200])TypeScript
import OpenAI from "openai";
import * as fs from "fs";
const client = new OpenAI({
baseURL: "https://api.polar-ai.com/v1",
apiKey: "pk-your-key-here",
});
// 1. Create JSONL file
const questions = [
"Resuma o artigo 5 da Constituição Federal.",
"Explique o que é LGPD.",
"Quais são os direitos do consumidor?",
];
const jsonlContent = questions
.map(
(q, i) =>
JSON.stringify({
custom_id: `req-${String(i).padStart(3, "0")}`,
method: "POST",
url: "/v1/chat/completions",
body: {
model: "urso-base",
messages: [{ role: "user", content: q }],
max_tokens: 500,
},
})
)
.join("\n");
fs.writeFileSync("batch_input.jsonl", jsonlContent);
// 2. Upload file
const file = await client.files.create({
file: fs.createReadStream("batch_input.jsonl"),
purpose: "batch",
});
// 3. Create batch job
const batch = await client.batches.create({
input_file_id: file.id,
endpoint: "/v1/chat/completions",
completion_window: "24h",
});
console.log(`Batch created: ${batch.id}`);
// 4. Poll for completion
let status = await client.batches.retrieve(batch.id);
while (!["completed", "failed", "cancelled"].includes(status.status)) {
await new Promise((r) => setTimeout(r, 30000));
status = await client.batches.retrieve(batch.id);
console.log(`Status: ${status.status}`);
}
// 5. Retrieve results
if (status.status === "completed" && status.output_file_id) {
const resultFile = await client.files.content(status.output_file_id);
const text = await resultFile.text();
console.log(text);
}curl
# 1. Upload do arquivo JSONL
curl -X POST https://api.polar-ai.com/v1/files \
-H "Authorization: Bearer pk-your-key-here" \
-F purpose="batch" \
-F file=@batch_input.jsonl
# 2. Criar job de batch
curl -X POST https://api.polar-ai.com/v1/batches \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pk-your-key-here" \
-d '{
"input_file_id": "file-abc123",
"endpoint": "/v1/chat/completions",
"completion_window": "24h"
}'
# 3. Consultar status
curl https://api.polar-ai.com/v1/batches/batch_abc123 \
-H "Authorization: Bearer pk-your-key-here"
# 4. Download dos resultados
curl https://api.polar-ai.com/v1/files/file-result123/content \
-H "Authorization: Bearer pk-your-key-here" \
--output batch_results.jsonlStatus do Batch
| Status | Descrição |
|---|---|
validating | Arquivo sendo validado |
in_progress | Requisições sendo processadas |
completed | Todas as requisições finalizadas |
failed | O batch falhou |
cancelled | O batch foi cancelado |
expired | O batch expirou (janela de 24h) |
Formato dos Resultados
Cada linha do arquivo de resultados:
{
"id": "batch_req_abc123",
"custom_id": "req-001",
"response": {
"status_code": 200,
"body": {
"id": "chatcmpl-xyz789",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "O artigo 5º da Constituição Federal..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 15,
"completion_tokens": 200,
"total_tokens": 215
}
}
}
}Preço
A Batch API oferece 50% de desconto sobre o preço padrão da API. O trade-off é que os resultados podem levar até 24 horas para serem processados.
Casos de Uso
- Análise de dados em lote: Processar milhares de documentos ou registros
- Classificação em massa: Categorizar grandes volumes de texto
- Geração de conteúdo: Criar descrições, resumos ou traduções em larga escala
- Embeddings em lote: Gerar embeddings para todo um corpus de documentos
- Avaliação de modelos: Executar benchmarks em datasets grandes
Próximos Passos
- Chat Completions — API em tempo real
- Embeddings — gere embeddings em lote
- Structured Output — saída estruturada em lote