Claude Message Batches

Les opérations de lecture/contrôle par lots existantes restent disponibles avec un solde nul pour un identifiant actif par ailleurs valide, mais POST /v1/messages/batches nécessite une nouvelle admission de solde positif/dépense avant que les lignes de travail/élément ne soient stockées. Une clé à solde nul ne peut donc pas créer un nouveau lot Claude ni consommer le stockage de rétention MariaDB. Les articles réels revérifient l'admission lorsque les travailleurs les réclament et attendent dans la file d'attente durable si les fonds sont épuisés par la suite. L'entrée est décodée progressivement élément par élément plutôt que chargée sous la forme d'un document JSON complet en mémoire de 256 Mo, et les quotas de tâches actives/d'éléments en file d'attente par utilisateur limitent les abus de stockage indépendamment de la facturation.

Model Gate implémente une API de lots de messages compatible Anthropic sur https://api.model-gate.com. Il s'agit d'une couche de compatibilité : Model Gate stocke le lot de manière durable et exécute chaque élément via le Model Gate normal. /v1/messages chemin. C'est le cas pas soumettre un lot Anthropic natif du fournisseur en amont.

Utilisez une clé API de modèle normale (mg_live_...). Chaque article est comptabilisé comme une demande individuelle avec request_mode=batch, batch_protocol=claude, l'ID du lot et son custom_id.

Le streaming n’est pas pris en charge dans un lot. Les alias de modèle sont résolus avant que l'élément ne soit mis en file d'attente.

Créer un lot de messages

Demande

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."}]
        }
      }
    ]
  }'

Réponse — 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
}

Récupérer un lot

Demande

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

Réponse — terminé

{
  "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"
}

Lire les résultats

Les résultats sont renvoyés sous forme de lignes JSON. Ne présumez pas que la logique de l'application dépend de l'ordre d'entrée d'origine ; résultats des matchs par custom_id.

Demande

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

Réponse — 200

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

Lister les lots

limit par défaut 20 et doit provenir de 1 à 100. Utiliser after_id ou before_id pour la pagination du curseur ; n’envoyez pas les deux en une seule demande.

Demande

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

Réponse — 200

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

Annuler un lot

Annuler empêche la réclamation des éléments en file d’attente. Un article en cours de traitement peut se terminer.

Demande

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

Réponse — 200

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

Supprimer un lot terminé

La suppression n'est acceptée qu'une fois que le lot a atteint un état terminal.

Demande

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

Réponse — 200

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

Sémantique de récupération

Les éléments par lots utilisent la même file d'attente durable que les requêtes asynchrones natives. La récupération est au moins une fois, pas exactement une fois : après un crash de travailleur, un bail abandonné peut être récupéré et un élément peut être à nouveau envoyé en amont si la première réponse en amont n'a pas été stockée de manière durable. L'ID de demande Model Gate reste stable au fil des tentatives et les gardes de règlement empêchent un deuxième débit de compte pour une demande déjà terminée.

Chaque article est admis immédiatement avant qu'un travailleur ne le réclame. Les articles autrement valides restent en file d'attente tant que le solde actuel du compte n'est pas positif ou que la limite de dépenses réinitialisable par clé/groupe est déjà épuisée ; l'attente de fonds ne consomme pas de tentative et ne marque pas l'échec de l'élément. Une recharge ultérieure, une réinitialisation de l'utilisation ou une augmentation de la limite rétablit automatiquement les éléments éligibles en file d'attente. Model Gate ne réserve pas de coût de lot dans le pire des cas, donc les articles admis simultanément peuvent se terminer avec un solde final négatif ou un léger dépassement de la limite de dépenses ; seuls les nouveaux éléments ultérieurs sont conservés.

Tarification et comptabilité

Chaque élément de lot utilise le même modèle de routage, la même comptabilité des jetons, le même instantané de tarification, la même évaluation de l'utilisation, les mêmes limites de clé/groupe API et la même logique de règlement qu'une demande Model Gate normale. Un administrateur peut configurer un Coefficient de prix de demande de lot sur le modèle de tarification du compte. La valeur par défaut est 1.

Par exemple, avec le coût normal du Model Gate 0.02 et coefficient de lot 0.5, le débit réel du compte est 0.01. Le montant de référence du fournisseur officiel économisé n’est pas multiplié par ce coefficient de lot Model Gate. Requêtes natives utilisant "async": true ne sont pas non plus concernés.

Si le coefficient diffère de 1, il est affiché sur la page Tarifs des modèles et dans /v1/models comme batch_pricing plus l'efficacité batch_cost tarifs.

Erreurs

Invalide ou en double custom_id, un modèle inconnu, stream:true, imbriqué async:true, une requête surdimensionnée ou un corps non valide renvoie une réponse d'erreur normale de style Anthropic.

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