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
Les réponses immédiates ne sont pas requises
Vous souhaitez optimiser l'efficacité des coûts
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.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

API Message Batches

L'API Message Batches est un moyen puissant et rentable 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 se terminant en moins d'1 heure tout en réduisant les coûts de 50 % et en augmentant le débit.

Vous pouvez explorer la référence API directement, en plus de ce guide.

Fonctionnement de l'API Message Batches

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

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

Ceci 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 Messages ou 256 Mo de taille, selon la limite atteinte en premier.
Le système traite chaque lot aussi rapidement que possible, la plupart des lots se terminant en moins d'1 heure. Vous pourrez accéder aux résultats du lot lorsque tous les messages auront été traités ou après 24 heures, selon ce qui arrive en premier. Les lots expireront si le traitement ne se termine pas dans les 24 heures.
Les résultats des lots sont disponibles pendant 29 jours après leur création. Après cela, vous pourrez toujours consulter le lot, mais ses résultats ne seront plus disponibles au téléchargement.
Les lots sont limités à un Espace de travail. Vous pouvez consulter tous les lots (et leurs résultats) créés dans l'Espace de travail 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. Voir 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 pourrez 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 de votre Espace de travail.

Modèles pris en charge

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

Ce qui peut être mis en lot

Toute requête que vous pouvez effectuer vers l'API Messages peut être incluse dans un lot. Cela comprend :

Vision
Utilisation d'outils
Messages système
Conversations multi-tours
Toutes les fonctionnalités bêta

Étant donné que chaque requête dans le lot est traitée indépendamment, vous pouvez mélanger différents types de requêtes dans un seul lot.

Étant donné que les lots peuvent prendre plus de 5 minutes à traiter, envisagez d'utiliser la durée de cache d'1 heure avec la mise en cache des invites pour de meilleurs taux de succès du cache lors du traitement de lots avec un contexte partagé.

Tarification

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

Model	Batch input	Batch output
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4.5	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5

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 structure d'une requête individuelle comprend :

Un custom_id unique pour identifier la requête Messages
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.

Testez vos requêtes de lot avec l'API Messages

La validation de l'objet params pour chaque requête de message est effectuée de manière asynchrone, et les erreurs de validation sont retournées lorsque le traitement de l'ensemble du lot est terminé. Vous pouvez vous assurer que vous construisez correctement votre entrée en vérifiant la structure de votre requête avec l'API Messages d'abord.

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

JSON

{
  "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 complétion 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 dans votre Espace de travail en utilisant le point de terminaison de liste. L'API prend en charge la pagination, récupérant automatiquement des 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 dans le lot aura un résultat. Il existe 4 types de résultats :

Type de résultat	Description
`succeeded`	La requête a réussi. Inclut le résultat du message.
`errored`	La requête a rencontré une erreur et un message n'a pas été créé. Les erreurs possibles incluent les requêtes invalides et les erreurs de serveur interne. Vous ne serez pas facturé pour ces requêtes.
`canceled`	L'utilisateur a annulé le lot avant que cette requête puisse être envoyée au modèle. Vous ne serez pas facturé pour ces requêtes.
`expired`	Le lot a atteint son délai d'expiration de 24 heures avant que cette requête puisse être envoyée au modèle. Vous ne serez pas facturé pour ces requêtes.

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 à la propriété results_url du Message Batch, et si les autorisations 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 même temps.

Les résultats seront 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 de résultats :

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","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-6","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 contient une erreur, son result.error sera défini selon la forme d'erreur standard.

Les résultats du lot peuvent ne pas correspondre à l'ordre d'entrée

Les résultats du lot peuvent être retournés dans n'importe quel ordre, et peuvent ne pas correspondre à l'ordre des requêtes lors de la création du lot. Dans l'exemple ci-dessus, le résultat de la deuxième requête du lot est retourné avant le premier. Pour faire correspondre correctement les résultats avec leurs requêtes correspondantes, utilisez toujours le champ custom_id.

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 montrera le lot dans un état canceling :

JSON

{
  "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 du cache de prompts avec les lots de messages

L'API Message Batches prend en charge le cache de prompts, vous permettant potentiellement de réduire les coûts et le temps de traitement pour les requêtes par lots. Les remises de prix du cache de prompts et des Message Batches peuvent se cumuler, offrant des économies 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 simultanée, les correspondances de cache sont fournies dans la mesure du possible. Les utilisateurs constatent généralement des taux de correspondance de cache allant de 30 % à 98 %, selon leurs modèles de trafic.

Pour maximiser la probabilité de correspondances de cache dans vos requêtes par lots :

Incluez des blocs cache_control identiques dans chaque requête de message au sein de votre lot
Maintenez un flux régulier de requêtes pour éviter que les entrées du cache n'expirent après leur durée de vie de 5 minutes
Structurez vos requêtes pour partager autant de contenu mis en cache que possible

Exemple d'implémentation du cache de prompts dans un lot :

Dans cet exemple, les deux requêtes du lot incluent des messages système identiques et le texte intégral de Pride and Prejudice marqué avec cache_control pour augmenter la probabilité de correspondances de cache.

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 par lots et implémentez une logique de nouvelle tentative appropriée pour les requêtes échouées.
Utilisez des valeurs custom_id significatives pour associer 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 gérabilité.
Effectuez un test à blanc d'une seule forme de requête avec l'API Messages pour éviter les erreurs de validation.

Résolution des problèmes courants

En cas de comportement inattendu :

Vérifiez que la taille totale de la requête par lots ne dépasse pas 256 Mo. Si la taille de la requête est trop grande, vous pouvez 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 la date created_at du lot (et non la date 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 et confidentialité des lots

Isolation de l'espace de travail : Les lots sont isolés au sein de l'espace de travail dans lequel ils sont créés. Ils ne sont accessibles que par les clés API associées à cet espace de travail, ou par les utilisateurs autorisés à consulter les lots de l'espace de travail dans la Console.
Disponibilité des résultats : Les résultats des lots sont disponibles pendant 29 jours après la création du lot, laissant suffisamment de 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}. Le traitement asynchrone nécessite un 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

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

import anthropic

client = anthropic.Anthropic()

# Récupère automatiquement plus de pages si nécessaire.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

Traitement par lots

Traitement par lots

API Message Batches

Fonctionnement de l'API Message Batches

Limitations des lots

Modèles pris en charge

Ce qui peut être mis en lot

Tarification

Comment utiliser l'API Message Batches

Préparer et créer votre lot

Suivi de votre lot

Interrogation pour la complétion du Message Batch

Lister tous les Message Batches

Récupération des résultats du lot

Annulation d'un Message Batch

Utilisation du cache de prompts avec les lots de messages

Bonnes pratiques pour un traitement par lots efficace

Résolution des problèmes courants

Stockage et confidentialité des lots

Conservation des données

FAQ

API Message Batches

Fonctionnement de l'API Message Batches

Limitations des lots

Modèles pris en charge

Ce qui peut être mis en lot

Tarification

Comment utiliser l'API Message Batches

Préparer et créer votre lot

Suivi de votre lot

Interrogation pour la complétion du Message Batch

Lister tous les Message Batches

Récupération des résultats du lot

Annulation d'un Message Batch

Utilisation du cache de prompts avec les lots de messages

Bonnes pratiques pour un traitement par lots efficace

Résolution des problèmes courants

Stockage et confidentialité des lots

Conservation des données

FAQ

Combien de temps faut-il pour traiter un lot ?

L'API Batches est-elle disponible pour tous les modèles ?

Puis-je utiliser l'API Message Batches avec d'autres fonctionnalités de l'API ?

Comment l'API Message Batches affecte-t-elle la tarification ?

Puis-je mettre à jour un lot après sa soumission ?

L'API Message Batches a-t-elle des limites de débit et interagissent-elles avec les limites de débit de l'API Messages ?

Comment gérer les erreurs dans mes requêtes par lots ?

Comment l'API Message Batches gère-t-elle la confidentialité et la séparation des données ?

Puis-je utiliser le cache de prompts dans l'API Message Batches ?