Le traitement par lots est une approche puissante pour gérer efficacement de grands volumes de requêtes. Au lieu de traiter les requêtes une par une avec des réponses immédiates, le traitement par lots vous permet de soumettre plusieurs requêtes ensemble pour un traitement asynchrone. Ce modèle est particulièrement utile lorsque :

• Vous devez traiter de grands volumes de données
• Des réponses immédiates ne sont pas requises
• Vous souhaitez optimiser la rentabilité
• Vous effectuez des évaluations ou des analyses à grande échelle

L'API Message Batches est la première implémentation de ce modèle par Anthropic.

API Message Batches

L'API Message Batches est un moyen puissant et économique de traiter de manière asynchrone de grands volumes de requêtes Messages. Cette approche est bien adaptée aux tâches qui ne nécessitent pas de réponses immédiates, la plupart des lots étant terminés en moins d'une heure tout en réduisant les coûts de 50 % et en augmentant le débit.

Vous pouvez explorer directement la référence de l'API, en complément de ce guide.

Fonctionnement de l'API Message Batches

Lorsque vous envoyez une requête à l'API Message Batches :

1. Le système crée un nouveau Message Batch avec les requêtes Messages fournies.
2. Le lot est ensuite traité de manière asynchrone, chaque requête étant gérée indépendamment.
3. Vous pouvez interroger l'état du lot et récupérer les résultats une fois le traitement terminé pour toutes les requêtes.

Cela est particulièrement utile pour les opérations en masse qui ne nécessitent pas de résultats immédiats, telles que :

• Évaluations à grande échelle : traitez efficacement des milliers de cas de test.
• Modération de contenu : analysez de grands volumes de contenu généré par les utilisateurs de manière asynchrone.
• Analyse de données : générez des insights ou des résumés pour de grands ensembles de données.
• Génération de contenu en masse : créez de grandes quantités de texte à diverses fins (par exemple, descriptions de produits, résumés d'articles).

Limitations des lots

• Un Message Batch est limité à 100 000 requêtes Message ou à 256 Mo, selon la limite atteinte en premier.
• Le système traite chaque lot aussi rapidement que possible, la plupart des lots étant terminés en moins d'une heure. Vous pouvez accéder aux résultats du lot lorsque tous les messages sont terminés ou après 24 heures, selon la première éventualité. Les lots expirent si le traitement n'est pas terminé dans les 24 heures.
• Les résultats des lots sont disponibles pendant 29 jours après leur création. Après cela, vous pouvez toujours consulter le lot, mais ses résultats ne seront plus disponibles au téléchargement.
• Les lots sont limités à un Workspace. Vous pouvez consulter tous les lots (et leurs résultats) qui ont été créés dans le Workspace auquel appartient votre clé API.
• Les limites de débit s'appliquent à la fois aux requêtes HTTP de l'API Batches et au nombre de requêtes dans un lot en attente de traitement. Consultez Limites de débit de l'API Message Batches. De plus, le traitement peut être ralenti en fonction de la demande actuelle et de votre volume de requêtes. Dans ce cas, vous pourriez voir davantage de requêtes expirer après 24 heures.
• En raison du débit élevé et du traitement concurrent, les lots peuvent légèrement dépasser la limite de dépenses configurée pour votre Workspace.
• Chaque requête groupée doit avoir un max_tokens d'au moins . () n'est pas pris en charge dans un lot, car une entrée de cache éphémère écrite pendant le traitement du lot expirerait probablement avant l'exécution de la requête suivante.

Modèles pris en charge

Tous les modèles actifs prennent en charge l'API Message Batches.

Ce qui peut être traité par lots

Presque toutes les requêtes que vous pouvez effectuer auprès de l'API Messages peuvent être incluses dans un lot. Cela comprend :

• Vision
• Utilisation d'outils, y compris tous les outils serveur (recherche web, récupération web, exécution de code, connecteurs MCP, advisor et recherche d'outils)
• Messages système
• Conversations multi-tours
• Réflexion étendue
• La plupart des fonctionnalités bêta

Étant donné que chaque requête du lot est traitée indépendamment, vous pouvez mélanger différents types de requêtes au sein d'un même lot.

Un petit nombre de paramètres de l'API Messages ne sont pas pris en charge dans les requêtes par lots. L'inclusion de l'un d'entre eux renvoie une erreur de validation :

Tarification

L'API Batches offre des économies de coûts significatives. Toute l'utilisation est facturée à 50 % des prix standard de l'API.

Comment utiliser l'API Message Batches

Préparer et créer votre lot

Un Message Batch est composé d'une liste de requêtes pour créer un Message. La forme d'une requête individuelle comprend :

• Un custom_id unique pour identifier la requête Messages. Doit comporter de 1 à 64 caractères et contenir uniquement des caractères alphanumériques, des tirets et des traits de soulignement (correspondant à ^[a-zA-Z0-9_-]{1,64}$).
• Un objet params avec les paramètres standard de l'API Messages

Vous pouvez créer un lot en passant cette liste dans le paramètre requests :

Dans cet exemple, deux requêtes distinctes sont regroupées pour un traitement asynchrone. Chaque requête possède un custom_id unique et contient les paramètres standard que vous utiliseriez pour un appel à l'API Messages.

Lorsqu'un lot est créé pour la première fois, la réponse aura un statut de traitement in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Suivi de votre lot

Le champ processing_status du Message Batch indique l'étape de traitement dans laquelle se trouve le lot. Il commence par in_progress, puis passe à ended une fois que toutes les requêtes du lot ont terminé leur traitement et que les résultats sont prêts. Vous pouvez surveiller l'état de votre lot en visitant la Console, ou en utilisant le point de terminaison de récupération.

Interrogation pour la fin du Message Batch

Pour interroger un Message Batch, vous aurez besoin de son id, qui est fourni dans la réponse lors de la création d'un lot ou en listant les lots. Vous pouvez implémenter une boucle d'interrogation qui vérifie périodiquement l'état du lot jusqu'à ce que le traitement soit terminé :

Lister tous les Message Batches

Vous pouvez lister tous les Message Batches de votre Workspace en utilisant le point de terminaison de liste. L'API prend en charge la pagination, récupérant automatiquement les pages supplémentaires selon les besoins :

Récupération des résultats du lot

Une fois le traitement du lot terminé, chaque requête Messages du lot a un résultat. Il existe 4 types de résultats :

Vous verrez un aperçu de vos résultats avec le request_counts du lot, qui indique combien de requêtes ont atteint chacun de ces quatre états.

Les résultats du lot sont disponibles au téléchargement via la propriété results_url du Message Batch et, si les permissions de l'organisation le permettent, dans la Console. En raison de la taille potentiellement importante des résultats, il est recommandé de diffuser les résultats plutôt que de les télécharger tous en une seule fois.

Les résultats sont au format .jsonl, où chaque ligne est un objet JSON valide représentant le résultat d'une seule requête dans le Message Batch. Pour chaque résultat diffusé, vous pouvez effectuer une action différente en fonction de son custom_id et de son type de résultat. Voici un exemple d'ensemble de résultats :

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-8","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-8","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Si votre résultat comporte une erreur, son result.error sera défini selon la forme d'erreur standard.

Annulation d'un Message Batch

Vous pouvez annuler un Message Batch en cours de traitement en utilisant le point de terminaison d'annulation. Immédiatement après l'annulation, le processing_status d'un lot sera canceling. Vous pouvez utiliser la même technique d'interrogation décrite ci-dessus pour attendre que l'annulation soit finalisée. Les lots annulés se terminent avec un statut ended et peuvent contenir des résultats partiels pour les requêtes qui ont été traitées avant l'annulation.

La réponse affichera le lot dans un état canceling :

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Utilisation de la mise en cache des prompts avec les Message Batches

L'API Message Batches prend en charge la mise en cache des prompts, ce qui vous permet de réduire potentiellement les coûts et le temps de traitement des requêtes par lots. Les remises tarifaires de la mise en cache des prompts et des Message Batches peuvent se cumuler, offrant des économies de coûts encore plus importantes lorsque les deux fonctionnalités sont utilisées ensemble. Cependant, étant donné que les requêtes par lots sont traitées de manière asynchrone et concurrente, les succès de cache sont fournis dans la mesure du possible. Les utilisateurs constatent généralement des taux de succès de cache allant de 30 % à 98 %, selon leurs modèles de trafic.

Pour maximiser la probabilité de succès de cache dans vos requêtes par lots :

1. Incluez des blocs cache_control identiques dans chaque requête Message de votre lot
2. Maintenez un flux constant de requêtes pour empêcher les entrées de cache d'expirer après leur durée de vie de 5 minutes
3. Structurez vos requêtes pour partager autant de contenu mis en cache que possible

Exemple d'implémentation de la mise en cache des prompts dans un lot :

Dans cet exemple, les deux requêtes du lot incluent des messages système identiques et le texte intégral d'Orgueil et Préjugés marqué avec cache_control pour augmenter la probabilité de succès de cache.

Outils serveur et boucle agentique

Tous les outils serveur (recherche web, récupération web, exécution de code, connecteurs MCP, advisor et recherche d'outils) fonctionnent dans les requêtes par lots. Le worker de lot exécute la même boucle agentique côté serveur que l'API Messages synchrone.

Comme il n'y a pas de connexion ouverte à maintenir, la boucle de lot exécute plus d'itérations par tour qu'une requête synchrone avant de renvoyer stop_reason: "pause_turn". Si un résultat de lot revient avec pause_turn, le tour n'est pas terminé ; vous pouvez le poursuivre en soumettant le contenu assistant mis en pause dans une requête de suivi (par lot ou synchrone) exactement comme indiqué dans le modèle de continuation pause_turn.

Le worker de lot limite également web_search par organisation afin que le traitement par lots hautement concurrent n'épuise pas la limite de débit de recherche web de votre organisation. Le lot réessaie automatiquement les requêtes limitées ; vous n'avez pas besoin de gérer cela vous-même, mais les très grands lots de recherche web peuvent prendre plus de temps à se terminer.

Sortie étendue (bêta)

L'en-tête bêta output-300k-2026-03-24 augmente le plafond de max_tokens à 300 000 pour les requêtes par lots utilisant Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 ou Claude Sonnet 4.6. Incluez l'en-tête pour générer des sorties bien plus longues que la limite standard (64k à 128k selon le modèle) en un seul tour.

Utilisez la sortie étendue pour la génération de contenu long tel que des brouillons de la longueur d'un livre et de la documentation technique, l'extraction exhaustive de données structurées, de grands échafaudages de génération de code et de longues chaînes de raisonnement.

Une seule génération de 300k tokens peut prendre plus d'une heure à se terminer, alors planifiez vos soumissions de lots en tenant compte de la fenêtre de traitement de 24 heures. La tarification standard des lots (50 % des prix standard de l'API) s'applique.

Bonnes pratiques pour un traitement par lots efficace

Pour tirer le meilleur parti de l'API Batches :

• Surveillez régulièrement l'état du traitement des lots et implémentez une logique de nouvelle tentative appropriée pour les requêtes échouées.
• Utilisez des valeurs custom_id significatives pour faire correspondre facilement les résultats aux requêtes, car l'ordre n'est pas garanti.
• Envisagez de diviser les très grands ensembles de données en plusieurs lots pour une meilleure gestion.
• Effectuez un test à blanc d'une forme de requête unique avec l'API Messages pour éviter les erreurs de validation.

Résolution des problèmes courants

Si vous rencontrez un comportement inattendu :

• Vérifiez que la taille totale de la requête de lot ne dépasse pas 256 Mo. Si la taille de la requête est trop importante, vous pourriez obtenir une erreur 413 request_too_large.
• Vérifiez que vous utilisez des modèles pris en charge pour toutes les requêtes du lot.
• Assurez-vous que chaque requête du lot possède un custom_id unique.
• Assurez-vous qu'il s'est écoulé moins de 29 jours depuis l'heure created_at du lot (et non l'heure ended_at du traitement). Si plus de 29 jours se sont écoulés, les résultats ne seront plus consultables.
• Confirmez que le lot n'a pas été annulé.

Notez que l'échec d'une requête dans un lot n'affecte pas le traitement des autres requêtes.

Stockage des lots et confidentialité

• Isolation par Workspace : les lots sont isolés dans le Workspace dans lequel ils sont créés. Ils ne sont accessibles que par les clés API associées à ce Workspace, ou par les utilisateurs ayant la permission de consulter les lots du Workspace dans la Console.

• Disponibilité des résultats : les résultats des lots sont disponibles pendant 29 jours après la création du lot, ce qui laisse amplement le temps pour la récupération et le traitement.

Conservation des données

Le traitement par lots stocke les données de requête et de réponse pendant jusqu'à 29 jours après la création du lot. Vous pouvez supprimer un lot de messages à tout moment après le traitement en utilisant le point de terminaison DELETE /v1/messages/batches/{batch_id}. Pour supprimer un lot en cours, annulez-le d'abord. Le traitement asynchrone nécessite le stockage côté serveur des entrées et des sorties jusqu'à la fin du lot et la récupération des résultats.

Pour l'éligibilité ZDR sur toutes les fonctionnalités, consultez API et conservation des données.

FAQ