Claude Message Batches

Las operaciones de control/lectura por lotes existentes permanecen disponibles con saldo cero para una credencial activa que de otro modo sería válida, pero POST /v1/messages/batches requiere una nueva admisión de saldo positivo/gasto antes de almacenar cualquier fila de trabajo/artículo. Por lo tanto, una clave de saldo cero no puede crear un nuevo lote de Claude ni consumir el almacenamiento de retención de MariaDB. Los artículos reales vuelven a verificar la admisión cuando los trabajadores los reclaman y esperan en la cola duradera si los fondos se agotan más adelante. La entrada se decodifica de forma incremental elemento por elemento en lugar de cargarse como un documento JSON completo en memoria de 256 MB, y las cuotas de trabajos activos/elementos en cola por usuario limitan el abuso de almacenamiento independientemente de la facturación.

Model Gate implementa una API de lotes de mensajes compatible con Anthropic en https://api.model-gate.com. Es una capa de compatibilidad: Model Gate almacena el lote de forma duradera y ejecuta cada elemento a través del Model Gate normal. /v1/messages camino. lo hace no envíe un lote Anthropic nativo del proveedor en sentido ascendente.

Utilice una clave API de modelo normal (mg_live_...). Cada artículo se contabiliza como una solicitud individual con request_mode=batch, batch_protocol=claude, el ID del lote y su custom_id.

La transmisión no se admite dentro de un lote. Los alias de modelo se resuelven antes de que el elemento se ponga en cola.

Crear un lote de mensajes

Pedido

curl https://api.model-gate.com/v1/messages/batches \
  -H "x-api-key: mg_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "summary-1",
        "params": {
          "model": "ch-47",
          "max_tokens": 256,
          "messages": [{"role":"user","content":"Summarize this text."}]
        }
      }
    ]
  }'

Respuesta: 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 1,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-08-13T08:30:00Z",
  "expires_at": "2026-08-14T08:30:00Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Recuperar un lote

Pedido

curl https://api.model-gate.com/v1/messages/batches/msgbatch_01K... \
  -H "x-api-key: mg_live_..."

Respuesta - finalizada

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "ended",
  "request_counts": {
    "processing": 0,
    "succeeded": 1,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": "2026-08-13T08:30:04Z",
  "results_url": "https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../results"
}

Leer resultados

Los resultados se devuelven como líneas JSON. No asuma que la lógica de la aplicación depende del orden de entrada original; resultados del partido por custom_id.

Pedido

curl https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../results \
  -H "x-api-key: mg_live_..."

Respuesta: 200

{"custom_id":"summary-1","result":{"type":"succeeded","message":{"id":"msg_...","type":"message","role":"assistant","content":[{"type":"text","text":"..."}]}}}

Listar lotes

limit por defecto es 20 y debe ser de 1 a 100. Usar after_id o before_id para paginación del cursor; no envíe ambos en una sola solicitud.

Pedido

curl "https://api.model-gate.com/v1/messages/batches?limit=20&after_id=msgbatch_01K..." \
  -H "x-api-key: mg_live_..."

Respuesta: 200

{
  "data": [],
  "has_more": false,
  "first_id": null,
  "last_id": null
}

Cancelar un lote

Cancelar evita que se reclamen los artículos en cola. Es posible que finalice un artículo que ya se está procesando.

Pedido

curl -X POST https://api.model-gate.com/v1/messages/batches/msgbatch_01K.../cancel \
  -H "x-api-key: mg_live_..."

Respuesta: 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 1,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  }
}

Eliminar un lote finalizado

La eliminación se acepta solo después de que el lote haya alcanzado un estado terminal.

Pedido

curl -X DELETE https://api.model-gate.com/v1/messages/batches/msgbatch_01K... \
  -H "x-api-key: mg_live_..."

Respuesta: 200

{
  "id": "msgbatch_01K...",
  "type": "message_batch_deleted"
}

Semántica de recuperación

Los elementos por lotes utilizan la misma cola duradera que las solicitudes asíncronas nativas. La recuperación es al menos una vez, no exactamente una vez: después de un accidente de trabajo, se puede reclamar un contrato de arrendamiento abandonado y un artículo puede enviarse nuevamente al flujo ascendente si la primera respuesta ascendente no se almacenó de manera duradera. El ID de solicitud de Model Gate permanece estable en todos los reintentos y los protectores de liquidación evitan un segundo débito de cuenta para una solicitud ya finalizada.

Cada artículo se admite inmediatamente antes de que un trabajador lo reclame. Los artículos que de otro modo serían válidos permanecen en cola mientras el saldo de la cuenta actual no sea positivo o el límite de gasto reiniciable de clave/grupo ya esté agotado; esperar fondos no consume un intento ni marca el elemento como fallido. Una recarga posterior, un restablecimiento de uso o un aumento de límite reanudan automáticamente los elementos elegibles en cola. Model Gate no reserva un costo de lote en el peor de los casos, por lo que los artículos admitidos simultáneamente pueden terminar con un saldo final negativo o un pequeño exceso en el límite de gasto; sólo se mantienen los elementos nuevos posteriores.

Precios y contabilidad

Cada artículo de lote utiliza el mismo enrutamiento modelo, contabilidad de tokens, instantánea de precios, valoración de uso, límites de grupo/clave API y lógica de liquidación que una solicitud de Model Gate normal. Un administrador puede configurar un Coeficiente de precio de solicitud de lote en la plantilla de precios de cuenta. El valor predeterminado es 1.

Por ejemplo, con el costo normal de Model Gate 0.02 y coeficiente de lote 0.5, el débito real de la cuenta es 0.01. El importe de referencia guardado del proveedor oficial no se multiplica por este coeficiente de lote de Model Gate. Solicitudes nativas usando "async": true tampoco se ven afectados.

Si el coeficiente difiere de 1, se muestra en la página de precios de los modelos y en /v1/models como batch_pricing más el efectivo batch_cost tarifas.

Errores

Inválido o duplicado custom_id, un modelo desconocido, stream:true, anidado async:true, una solicitud de gran tamaño o un cuerpo no válido devuelve una respuesta de error normal de estilo antrópico.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "summary-1: stream=true is not supported inside a batch"
  }
}