Le traitement par lots est une approche puissante pour gérer efficacement de gros 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 gros volumes de données
  • Les réponses immédiates ne sont pas requises
  • Vous voulez optimiser l’efficacité des coûts
  • Vous effectuez des évaluations ou analyses à grande échelle
L’API Message Batches est notre première implémentation de ce modèle.

​
API Message Batches

L’API Message Batches est un moyen puissant et rentable de traiter de manière asynchrone de gros 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 directement la référence API, en plus de ce guide.

​
Comment fonctionne 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 le statut du lot et récupérer les résultats lorsque le traitement est 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 : Traiter efficacement des milliers de cas de test.
  • Modération de contenu : Analyser de gros volumes de contenu généré par les utilisateurs de manière asynchrone.
  • Analyse de données : Générer des insights ou des résumés pour de grands ensembles de données.
  • Génération de contenu en masse : Créer 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é à soit 100 000 requêtes Message ou 256 MB de taille, selon ce qui est atteint en premier.
  • Nous traitons chaque lot aussi rapidement que possible, la plupart des lots se terminant dans l’heure. Vous pourrez accéder aux résultats du lot lorsque tous les messages seront terminé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 la création. Après cela, vous pourrez toujours voir le Batch, mais ses résultats ne seront plus disponibles au téléchargement.
  • Les lots sont limités à un Workspace. Vous pouvez voir tous les lots—et leurs résultats—qui ont été créés dans le Workspace auquel appartient votre clé API.
  • Les limites de taux 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 taux de l’API Message Batches. De plus, nous pouvons ralentir le traitement en fonction de la demande actuelle et de votre volume de requêtes. Dans ce cas, vous pourriez voir plus de requêtes expirer après 24 heures.
  • En raison du haut débit et du traitement concurrent, les lots peuvent légèrement dépasser la limite de dépenses configurée de votre Workspace.

​
Modèles supportés

Tous les modèles actifs supportent l’API Message Batches.

​
Ce qui peut être traité par lots

Toute requête que vous pouvez faire à l’API Messages peut être incluse dans un lot. Cela inclut :
  • Vision
  • Utilisation d’outils
  • Messages système
  • Conversations multi-tours
  • Toutes les fonctionnalités bêta
Puisque 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.
Puisque les lots peuvent prendre plus de 5 minutes à traiter, considérez utiliser la durée de cache d’1 heure avec la mise en cache des prompts pour de meilleurs taux de réussite de 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 API standard.
ModelBatch inputBatch output
Claude Opus 4.1$7.50 / MTok$37.50 / MTok
Claude Opus 4$7.50 / MTok$37.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$0.50 / MTok$2.50 / MTok
Claude Haiku 3.5$0.40 / MTok$2 / MTok
Claude Opus 3 (deprecated)$7.50 / MTok$37.50 / MTok
Claude Haiku 3$0.125 / MTok$0.625 / MTok

​
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
  • 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 : 
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-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'
Dans cet exemple, deux requêtes séparées sont regroupées ensemble pour un traitement asynchrone. Chaque requête a 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 MessagesLa 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 votre entrée correctement en vérifiant d’abord la forme de votre requête avec l’API Messages.
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
}

​
Suivre 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 se met à jour à ended une fois que toutes les requêtes du lot ont fini de traiter, et 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 : 
curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'
Vous pouvez interroger ce point de terminaison pour savoir quand le traitement est terminé.

​
Récupérer les résultats du lot

Une fois le traitement du lot terminé, chaque requête Messages dans le lot aura un résultat. Il y a 4 types de résultats :
Type de RésultatDescription
succeededLa requête a réussi. Inclut le résultat du message.
erroredLa requête a rencontré une erreur et un message n’a pas été créé. Les erreurs possibles incluent des requêtes invalides et des erreurs de serveur interne. Vous ne serez pas facturé pour ces requêtes.
canceledL’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.
expiredLe lot a atteint son 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 les request_counts du lot, qui montrent 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 sur le Message Batch, et si l’autorisation de l’organisation le permet, 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 tous les télécharger en une fois. 
#!/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
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 faire quelque chose de différent selon son custom_id et son type de résultat. Voici un exemple d’ensemble de résultats :
.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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 a une erreur, son result.error sera défini sur notre forme d’erreur standard.
Les résultats des lots peuvent ne pas correspondre à l’ordre d’entréeLes résultats des lots peuvent être retournés dans n’importe quel ordre, et peuvent ne pas correspondre à l’ordre des requêtes lorsque le lot a été créé. 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.

​
Utiliser la mise en cache des prompts avec Message Batches

L’API Message Batches supporte la mise en cache des prompts, vous permettant de potentiellement réduire les coûts et le temps de traitement pour les requêtes de lot. Les remises de tarification 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, puisque les requêtes de lot sont traitées de manière asynchrone et concurrente, les réussites de cache sont fournies sur la base du meilleur effort. Les utilisateurs expérimentent généralement des taux de réussite de cache allant de 30% à 98%, selon leurs modèles de trafic. Pour maximiser la probabilité de réussites de cache dans vos requêtes de lot :
  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 : 
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-sonnet-4-5",
                "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-sonnet-4-5",
                "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."}
                ]
            }
        }
    ]
}'
Dans cet exemple, les deux requêtes du lot incluent des messages système identiques et le texte complet d’Orgueil et Préjugés marqué avec cache_control pour augmenter la probabilité de réussites de cache.

​
Meilleures pratiques pour un traitement par lots efficace

Pour tirer le meilleur parti de l’API Batches :
  • Surveillez régulièrement le statut de 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 avec les requêtes, puisque l’ordre n’est pas garanti.
  • Considérez diviser de très grands ensembles de données en plusieurs lots pour une meilleure gérabilité.
  • Effectuez un test à sec d’une forme de requête unique avec l’API Messages pour éviter les erreurs de validation.

​
Dépannage des problèmes courants

Si vous rencontrez un comportement inattendu :
  • Vérifiez que la taille totale de la requête du lot ne dépasse pas 256 MB. 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 supportés pour toutes les requêtes du lot.
  • Assurez-vous que chaque requête du lot a un custom_id unique.
  • Assurez-vous qu’il s’est écoulé moins de 29 jours depuis l’heure de created_at du lot (pas l’heure de ended_at du traitement). Si plus de 29 jours se sont écoulés, les résultats ne seront plus visibles.
  • 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 des Workspaces : Les lots sont isolés dans le Workspace dans lequel ils sont créés. Ils ne peuvent être accessibles que par les clés API associées à ce Workspace, ou les utilisateurs avec permission de voir 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, permettant amplement de temps pour la récupération et le traitement.

​
FAQ

Les lots peuvent prendre jusqu’à 24 heures pour le traitement, mais beaucoup se termineront plus tôt. Le temps de traitement réel dépend de la taille du lot, de la demande actuelle, et de votre volume de requêtes. Il est possible qu’un lot expire et ne se termine pas dans les 24 heures.
Voir ci-dessus pour la liste des modèles supportés.
Oui, l’API Message Batches supporte toutes les fonctionnalités disponibles dans l’API Messages, y compris les fonctionnalités bêta. Cependant, le streaming n’est pas supporté pour les requêtes de lot.
L’API Message Batches offre une remise de 50% sur toute utilisation par rapport aux prix API standard. Cela s’applique aux tokens d’entrée, aux tokens de sortie, et à tous les tokens spéciaux. Pour plus d’informations sur la tarification, visitez notre page de tarification.
Non, une fois qu’un lot a été soumis, il ne peut pas être modifié. Si vous devez apporter des modifications, vous devriez annuler le lot actuel et en soumettre un nouveau. Notez que l’annulation peut ne pas prendre effet immédiatement.
L’API Message Batches a des limites de taux basées sur les requêtes HTTP en plus des limites sur le nombre de requêtes nécessitant un traitement. Voir Limites de taux de l’API Message Batches. L’utilisation de l’API Batches n’affecte pas les limites de taux dans l’API Messages.
Lorsque vous récupérez les résultats, chaque requête aura un champ result indiquant si elle a succeeded, errored, été canceled, ou expired. Pour les résultats errored, des informations d’erreur supplémentaires seront fournies. Voir l’objet de réponse d’erreur dans la référence API.
L’API Message Batches est conçue avec de fortes mesures de confidentialité et de séparation des données :
  1. Les lots et leurs résultats sont isolés dans le Workspace dans lequel ils ont été créés. Cela signifie qu’ils ne peuvent être accessibles que par les clés API de ce même Workspace.
  2. Chaque requête dans un lot est traitée indépendamment, sans fuite de données entre les requêtes.
  3. Les résultats ne sont disponibles que pour une durée limitée (29 jours), et suivent notre politique de rétention des données.
  4. Le téléchargement des résultats de lot dans la Console peut être désactivé au niveau de l’organisation ou par workspace.
Oui, il est possible d’utiliser la mise en cache des prompts avec l’API Message Batches. Cependant, parce que les requêtes de lot asynchrones peuvent être traitées de manière concurrente et dans n’importe quel ordre, les réussites de cache sont fournies sur la base du meilleur effort.