PolarPOLAR

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

EndpointMétodoDescrição
/v1/batchesPOSTCriar um job de batch
/v1/batches/{batch_id}GETConsultar status de um batch
/v1/batchesGETListar todos os batches
/v1/batches/{batch_id}/cancelPOSTCancelar um batch
/v1/filesPOSTUpload do arquivo JSONL
/v1/files/{file_id}/contentGETDownload 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.jsonl

Status do Batch

StatusDescrição
validatingArquivo sendo validado
in_progressRequisições sendo processadas
completedTodas as requisições finalizadas
failedO batch falhou
cancelledO batch foi cancelado
expiredO 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

On this page