Archivos y lotes

Crear lote de mensajes

Crea un lote de solicitudes de Messages que se ejecutan de forma asíncrona.

POST
/v1/messages/batches

Descripción general

Envía hasta 100,000 solicitudes de Messages en una sola llamada. El lote se ejecuta de forma asíncrona. La respuesta se devuelve inmediatamente con processing_status establecido en in_progress. Recupera el lote hasta que tenga el estado ended, luego obten los resultados.

Notas

  • Cada elemento en requests tiene un custom_id y params. params acepta los mismos campos que Crear mensaje, incluyendo max_tokens. Los elementos no pueden usar speed: "fast".
  • custom_id debe tener de 1 a 64 letras, dígitos, guiones bajos o guiones, y debe ser único dentro del lote.
  • Todos los modelos en el lote deben estar disponibles para lotes. TokenLab rechazará toda la solicitud con un 400 cuando no sea así, o cuando ninguna ruta pueda servir a todos los modelos del lote.
  • TokenLab reserva el costo estimado cuando acepta el lote y devuelve un 402 cuando el saldo no es suficiente para cubrirlo. Después de que el lote finaliza, TokenLab liquida el uso de las solicitudes que tuvieron éxito. Los precios de los lotes pueden diferir de los precios síncronos.
  • Si un elemento hace referencia al contenido de un file_id, envía anthropic-beta: files-api-2025-04-14.
  • Envía un Idempotency-Key para reintentar de forma segura una solicitud de creación que haya agotado el tiempo de espera. Consulta Reintentar de forma segura con una clave de idempotencia.

Ejemplo

Solicitud

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

Ejemplo de respuesta

Respuesta

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

Campos importantes

idstring
ID del lote de mensajes. Úsalo para recuperar, cancelar o eliminar el lote y para obtener sus resultados.
processing_statusstring
in_progress, canceling o ended.
request_countsobject
Número de solicitudes que están en estado processing, succeeded, errored, canceled o expired.
expires_atstring
Cuándo expira el lote. Las solicitudes que no hayan terminado para ese momento finalizarán como expired.
results_urlstring|null
URL de los resultados. Es null hasta que el lote haya finalizado.

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"
Idempotency-Key?string

Clave opcional que hace que una solicitud de creación sea segura para reintentar. Envíe un nuevo valor único, como un UUID, para cada tarea. Un reintento con la misma clave y el mismo cuerpo devuelve el resultado de la solicitud de creación original, generalmente la tarea original, y no crea, envía ni cobra una segunda tarea. Un cuerpo diferente con una clave que ya fue aceptada se rechaza con 409. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json