Archivos y lotes

Crear lote

Cree un lote a partir de un archivo JSONL cargado.

POST
/v1/batches

Descripción general

Cargue un archivo JSONL con purpose=batch y luego utilice su ID como input_file_id. Los lotes completados devuelven los IDs de los archivos de salida y de error.

Archivo de entrada

El archivo debe estar en formato JSONL: una solicitud por línea, hasta 50,000 líneas y 200 MiB. Para /v1/embeddings, el número total de entradas en todas las líneas también está limitado a 50,000. Cada línea requiere:

  • custom_id: una cadena, única en el archivo.
  • method: POST.
  • url: el mismo valor que el endpoint del lote.
  • body: el cuerpo de la solicitud, con model.
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}}

Notas

  • Los archivos de entrada por lotes deben usar purpose=batch.
  • completion_window es 24h, el valor predeterminado y único.
  • metadata admite hasta 16 pares de cadenas: claves de hasta 64 caracteres, valores de hasta 512.
  • output_expires_after establece cuándo caducan los archivos de resultados: anchor es created_at o completed_at, y seconds es como máximo 30 días.
  • El orden de salida puede diferir del orden de entrada. Haga coincidir cada resultado mediante custom_id.
  • El streaming no es compatible dentro de los elementos del lote.
  • Los endpoints de elementos admitidos son /v1/chat/completions y /v1/embeddings. /v1/responses no es compatible.
  • El costo estimado se reserva cuando se crea el lote. Un saldo insuficiente devuelve 402.
  • Un archivo no válido devuelve 400 con param establecido en input_file_id, y el mensaje indica la línea afectada.

Ejemplo

Solicitud

cURL
curl -X POST "https://api.tokenlab.sh/v1/batches" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

Los precios de los lotes pueden diferir de las solicitudes síncronas. Consulte la factura final para ver el cargo.

Ejemplo de respuesta

Respuesta

200 OK
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1706000000
}

Campos importantes

idstring
ID del lote.
statusstring
Estado del lote.
output_file_idstring|null
ID del archivo de salida tras la finalización.

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json