API diferida (lotes)

Si no necesitas la respuesta al momento (clasificar miles de tickets, resumir documentos de noche, enriquecer un CRM…), manda las peticiones en un lote: se procesan en un plazo de hasta 24 horas y pagas un 30 % menos que a demanda. La API es compatible con la Batch API de OpenAI, así que puedes usar su SDK tal cual.

Método y rutaPara qué
POST /v1/filesSubir el fichero JSONL de peticiones (purpose=batch).
POST /v1/batchesCrear el lote a partir del fichero.
GET /v1/batches/{id}Consultar el estado.
GET /v1/batchesListar los lotes del equipo (limit, after).
POST /v1/batches/{id}/cancelCancelar.
GET /v1/files/{id}Datos de un fichero.
GET /v1/files/{id}/contentDescargar un fichero (entrada, resultados o errores).
DELETE /v1/files/{id}Borrar un fichero.

Los lotes y los ficheros pertenecen al equipo de la key: cualquier key del mismo equipo los ve.

1. Prepara el fichero

Un fichero JSONL (una petición por línea, UTF-8) con el formato de OpenAI:

JSONL
{"custom_id": "ticket-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "claude-haiku-4-5", "max_tokens": 50, "messages": [{"role": "system", "content": "Clasifica el ticket: facturación, envío u otro. Responde sólo la categoría."}, {"role": "user", "content": "No me ha llegado el paquete"}]}}
{"custom_id": "ticket-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "claude-haiku-4-5", "max_tokens": 50, "messages": [{"role": "system", "content": "Clasifica el ticket: facturación, envío u otro. Responde sólo la categoría."}, {"role": "user", "content": "Mi factura tiene mal el RFC"}]}}

Reglas que se validan al subirlo (si algo falla, 400 invalid_batch_file con el número de línea):

  • custom_id obligatorio, de 1 a 200 caracteres y único en el fichero. Es lo que te permite emparejar cada resultado.
  • url debe ser /v1/chat/completions y method, POST.
  • Un único modelo en todo el fichero, y que admita proceso diferido (hoy, claude-haiku-4-5). También vale auto: se usa el modelo del equipo si lo admite o, si no, uno que sí.
  • Sólo texto: roles system, developer, user y assistant; sin imágenes, sin herramientas, sin stream y con n igual a 1.
  • Como máximo 50.000 peticiones y 50 MB por fichero.
  • max_tokens es opcional; si falta se usa la salida máxima por defecto de tu equipo o 4.096.

2. Súbelo, crea el lote y recoge los resultados

import json, time
from openai import OpenAI

client = OpenAI(base_url="https://api.quipua.com/v1", api_key="ci_live_xxx")

f = client.files.create(file=open("tickets.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
    input_file_id=f.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={"proceso": "clasificar-tickets"},
)

while batch.status not in ("completed", "failed", "expired", "cancelled"):
    time.sleep(60)
    batch = client.batches.retrieve(batch.id)

print(batch.request_counts)
if batch.output_file_id:
    for line in client.files.content(batch.output_file_id).text.splitlines():
        r = json.loads(line)
        print(r["custom_id"], r["response"]["body"]["choices"][0]["message"]["content"])
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.quipua.com/v1", apiKey: "ci_live_xxx" });

const f = await client.files.create({ file: fs.createReadStream("tickets.jsonl"), purpose: "batch" });
let batch = await client.batches.create({
  input_file_id: f.id,
  endpoint: "/v1/chat/completions",
  completion_window: "24h",
});

while (!["completed", "failed", "expired", "cancelled"].includes(batch.status)) {
  await new Promise((r) => setTimeout(r, 60_000));
  batch = await client.batches.retrieve(batch.id);
}

if (batch.output_file_id) {
  const text = await (await client.files.content(batch.output_file_id)).text();
  for (const line of text.trim().split("\n")) {
    const r = JSON.parse(line);
    console.log(r.custom_id, r.response.body.choices[0].message.content);
  }
}
# 1. Subir el fichero
curl https://api.quipua.com/v1/files \
  -H "Authorization: Bearer ci_live_xxx" \
  -F purpose=batch -F [email protected]

# 2. Crear el lote con el id del fichero
curl https://api.quipua.com/v1/batches \
  -H "Authorization: Bearer ci_live_xxx" -H "Content-Type: application/json" \
  -d '{"input_file_id": "file-…", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'

# 3. Consultar el estado
curl https://api.quipua.com/v1/batches/batch_… -H "Authorization: Bearer ci_live_xxx"

# 4. Descargar los resultados (output_file_id)
curl https://api.quipua.com/v1/files/file-…/content -H "Authorization: Bearer ci_live_xxx"

Al crear el lote, endpoint debe ser /v1/chat/completions y completion_window, 24h. metadata es opcional: hasta 16 pares clave/valor de texto (hasta 512 caracteres cada valor).

El objeto lote

JSON
{
  "id": "batch_…",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-…",
  "completion_window": "24h",
  "status": "in_progress",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1791360000,
  "in_progress_at": 1791360000,
  "expires_at": 1791446400,
  "completed_at": null,
  "request_counts": {"total": 2, "completed": 0, "failed": 0},
  "metadata": {"proceso": "clasificar-tickets"},
  "model": "claude-haiku-4-5"
}
EstadoSignificado
in_progressEn cola o procesándose.
cancellingCancelado mientras se procesaba: se entregará lo que ya esté hecho.
completedTerminado. Los resultados están en output_file_id y los errores en error_file_id.
cancelledCancelado.
expiredNo terminó en 24 h: lo pendiente caduca sin cobro.

Ficheros de resultados

Cada línea del fichero de resultados (output_file_id) tiene la forma de OpenAI. body es una respuesta de chat completions normal, con su usage:

JSON
{"id": "batch_req_…", "custom_id": "ticket-1", "error": null, "response": {"status_code": 200, "request_id": "…", "body": {"object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "envío"}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 40, "completion_tokens": 2, "total_tokens": 42}}}}

Las peticiones que fallan van al fichero de errores (error_file_id) con el mismo formato, su status_code y el error en body. El orden de las líneas no está garantizado: empareja por custom_id.

Precio

  • Cuando el lote se procesa en diferido, cada petición se cobra al precio normal menos un 30 %.
  • Para procesar en diferido, el proveedor exige un mínimo de 100 peticiones por trabajo. Quipua junta lotes del mismo modelo (también de otras empresas: cada petición va con un identificador opaco y la atribución sólo vive en Quipua) para llegar a ese mínimo. Si en 60 minutos no se llega, tu lote se ejecuta a demanda y se cobra a precio normal.
  • Si es el proveedor el que falla, el lote se ejecuta a demanda pero mantiene el precio diferido.
  • Al crear el lote se reserva de tu saldo el máximo de todo el lote a precio normal (entrada estimada + max_tokens de cada línea), con las mismas comprobaciones que una petición: saldo (402), presupuesto del equipo y límite de la key (403). Al terminar se cobra lo real y se libera la reserva.
  • Los lotes no llevan la memoria de la empresa ni el modo ahorro.

Cancelar

POST /v1/batches/{id}/cancel:

  • Si el lote aún estaba en cola, se cancela del todo y no se cobra nada.
  • Si ya estaba procesándose, pasa a cancelling: se entrega y se cobra lo que se procese, y termina en cancelled.

Plazos y caducidades

QuéCuánto dura
Plazo del lote24 h desde que se crea. Lo que no termine, caduca sin cobro.
Fichero de entrada sin usar24 h.
Fichero de entrada usado en un loteHasta que termina el lote; entonces se borra.
Ficheros de resultados y errores72 h. Después, 410 file_expired.

DELETE /v1/files/{id} borra el contenido al momento (salvo la entrada de un lote en curso: 409 file_in_use).

Privacidad

Es la única parte de la API en la que Quipua guarda contenido de peticiones y respuestas, porque hace falta para procesarlas más tarde: los ficheros se guardan cifrados, la entrada se borra al terminar el lote y los resultados a las 72 h. Ver Privacidad.

Errores propios

CódigoCuándo
400 invalid_purposepurpose distinto de batch.
400 missing_fileFalta el campo file.
400 invalid_batch_fileEl JSONL no cumple las reglas (el mensaje dice la línea).
400 invalid_endpoint / invalid_completion_window / invalid_metadataParámetros del lote no válidos.
400 model_not_batchEl modelo no admite proceso diferido.
404 file_not_found / batch_not_foundNo existe o es de otro equipo.
409 file_in_useBorrar la entrada de un lote en curso.
410 file_expiredEl fichero ya se borró.
413 file_too_largeMás de 50 MB.
503 batch_unavailableLa API diferida no está disponible en este entorno.