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 ruta | Para qué |
|---|---|
POST /v1/files | Subir el fichero JSONL de peticiones (purpose=batch). |
POST /v1/batches | Crear el lote a partir del fichero. |
GET /v1/batches/{id} | Consultar el estado. |
GET /v1/batches | Listar los lotes del equipo (limit, after). |
POST /v1/batches/{id}/cancel | Cancelar. |
GET /v1/files/{id} | Datos de un fichero. |
GET /v1/files/{id}/content | Descargar 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:
{"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_idobligatorio, de 1 a 200 caracteres y único en el fichero. Es lo que te permite emparejar cada resultado.urldebe ser/v1/chat/completionsymethod,POST.- Un único modelo en todo el fichero, y que admita proceso diferido (hoy,
claude-haiku-4-5). También valeauto: se usa el modelo del equipo si lo admite o, si no, uno que sí. - Sólo texto: roles
system,developer,useryassistant; sin imágenes, sin herramientas, sinstreamy connigual a 1. - Como máximo 50.000 peticiones y 50 MB por fichero.
max_tokenses 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
{
"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"
}| Estado | Significado |
|---|---|
in_progress | En cola o procesándose. |
cancelling | Cancelado mientras se procesaba: se entregará lo que ya esté hecho. |
completed | Terminado. Los resultados están en output_file_id y los errores en error_file_id. |
cancelled | Cancelado. |
expired | No 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:
{"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_tokensde 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 encancelled.
Plazos y caducidades
| Qué | Cuánto dura |
|---|---|
| Plazo del lote | 24 h desde que se crea. Lo que no termine, caduca sin cobro. |
| Fichero de entrada sin usar | 24 h. |
| Fichero de entrada usado en un lote | Hasta que termina el lote; entonces se borra. |
| Ficheros de resultados y errores | 72 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ódigo | Cuándo |
|---|---|
400 invalid_purpose | purpose distinto de batch. |
400 missing_file | Falta el campo file. |
400 invalid_batch_file | El JSONL no cumple las reglas (el mensaje dice la línea). |
400 invalid_endpoint / invalid_completion_window / invalid_metadata | Parámetros del lote no válidos. |
400 model_not_batch | El modelo no admite proceso diferido. |
404 file_not_found / batch_not_found | No existe o es de otro equipo. |
409 file_in_use | Borrar la entrada de un lote en curso. |
410 file_expired | El fichero ya se borró. |
413 file_too_large | Más de 50 MB. |
503 batch_unavailable | La API diferida no está disponible en este entorno. |