Traitement par lots

Le traitement par lots est une approche puissante pour gérer efficacement de grands volumes de demandes. Au lieu de traiter les demandes une par une avec des réponses immédiates, le traitement par lots vous permet de soumettre plusieurs demandes 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 exécutez 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 demandes Messages. Cette approche convient bien aux tâches qui ne nécessitent pas de réponses immédiates, la plupart des lots se terminant en moins d'une 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.

Comment fonctionne l'API Message Batches

Lorsque vous envoyez une demande à l'API Message Batches :

Le système crée un nouveau Message Batch avec les demandes Messages fournies.
Le lot est ensuite traité de manière asynchrone, chaque demande é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 demandes.

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 manière asynchrone de grands volumes de contenu généré par les utilisateurs.
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é à soit 100 000 demandes Messages, soit 256 Mo de taille, selon ce qui est atteint en premier.
Le système traite chaque lot aussi rapidement que possible, la plupart des lots se terminant en moins d'une heure. Vous pouvez accéder aux résultats du lot une fois que tous les messages sont terminés ou après 24 heures, selon ce qui arrive en premier. Les lots expirent 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 pouvez toujours afficher le Batch, mais ses résultats ne seront plus disponibles pour téléchargement.
Les lots sont limités à un Workspace. Vous pouvez afficher tous les lots (et leurs résultats) qui ont été créés dans le Workspace auquel votre clé API appartient.
Les limites de débit s'appliquent à la fois aux demandes HTTP de l'API Batches et au nombre de demandes 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 demandes. Dans ce cas, vous pouvez voir plus de demandes 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 Workspace.

Modèles pris en charge

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

Ce qui peut être traité par lots

Toute demande que vous pouvez faire à l'API Messages peut être incluse dans un lot. Ceci inclut :

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

Puisque chaque demande du lot est traitée indépendamment, vous pouvez mélanger différents types de demandes dans un seul lot.

Puisque 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 des lots avec un contexte partagé.

Tarification

L'API Batches offre des économies de coûts significatives. Tous les usages sont facturés à 50 % des prix standard de l'API.

Model	Batch input	Batch output
Claude Opus 4.7	$2.50 / MTok	$12.50 / MTok
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)

Comment utiliser l'API Message Batches

Préparez et créez votre lot

Un Message Batch est composé d'une liste de demandes pour créer un Message. La forme d'une demande individuelle est composée de :

Un custom_id unique pour identifier la demande Messages. Doit contenir 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 demandes distinctes sont traitées par lots ensemble pour un traitement asynchrone. Chaque demande a un custom_id unique et contient les paramètres standard que vous utiliseriez pour un appel API Messages.

Testez vos demandes de lot avec l'API Messages

La validation de l'objet params pour chaque demande de message est effectuée de manière asynchrone, et les erreurs de validation sont renvoyées une fois le traitement du lot entier terminé. Vous pouvez vous assurer que vous construisez votre entrée correctement en vérifiant d'abord la forme de votre demande avec l'API Messages.

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

Output

{
  "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 du traitement du lot. Il commence par in_progress, puis se met à jour à ended une fois que toutes les demandes du lot ont terminé le 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 de l'achèvement 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é :

Listing all Message Batches

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

Récupération des résultats du lot

Une fois que le traitement par lot est terminé, chaque demande Messages du lot a un résultat. Il y a 4 types de résultats :

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

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

Les résultats du lot sont disponibles en téléchargement à la propriété results_url sur le Message Batch, et si la permission 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 les télécharger tous à la fois.

Les résultats sont au format .jsonl, où chaque ligne est un objet JSON valide représentant le résultat d'une seule demande 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-opus-4-7","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-7","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 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 demandes lors de la création du lot. Dans l'exemple ci-dessus, le résultat de la deuxième demande du lot est retourné avant le premier. Pour faire correspondre correctement les résultats avec leurs demandes correspondantes, utilisez toujours le champ custom_id.

Annulation d'un Message Batch

Vous pouvez annuler un Message Batch qui est actuellement 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 de ended et peuvent contenir des résultats partiels pour les demandes qui ont été traitées avant l'annulation.

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

Output

{
  "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 invites avec Message Batches

L'API Message Batches supporte la mise en cache des invites, ce qui vous permet de réduire potentiellement les coûts et le temps de traitement pour les demandes par lot. Les réductions de prix de la mise en cache des invites et de Message Batches peuvent s'accumuler, offrant des économies de coûts encore plus importantes lorsque les deux fonctionnalités sont utilisées ensemble. Cependant, comme les demandes par lot sont traitées de manière asynchrone et concurrente, les accès au cache sont fournis sur la base du meilleur effort. Les utilisateurs connaissent généralement des taux d'accès au cache allant de 30 % à 98 %, selon leurs modèles de trafic.

Pour maximiser la probabilité d'accès au cache dans vos demandes par lot :

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

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

Dans cet exemple, les deux demandes du lot incluent des messages système identiques et le texte complet de Pride and Prejudice marqué avec cache_control pour augmenter la probabilité d'accès au cache.

Sortie étendue (bêta)

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

La sortie étendue est disponible uniquement sur l'API Message Batches, pas sur l'API Messages synchrone. Elle est prise en charge sur l'API Claude et n'est pas disponible sur Amazon Bedrock, Vertex AI ou Microsoft Foundry.

Utilisez la sortie étendue pour la génération de contenu long comme les brouillons de livres et la documentation technique, l'extraction de données structurées exhaustive, les grands échafaudages de génération de code et les longues chaînes de raisonnement.

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

Meilleures pratiques pour un traitement par lot efficace

Pour tirer le meilleur parti de l'API Batches :

Surveillez régulièrement l'état du traitement par lot et implémentez une logique de nouvelle tentative appropriée pour les demandes échouées.
Utilisez des valeurs custom_id significatives pour faire correspondre facilement les résultats aux demandes, 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 demande 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 demande par lot ne dépasse pas 256 Mo. Si la taille de la demande 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 demandes du lot.
Assurez-vous que chaque demande du lot a un custom_id unique.
Assurez-vous qu'il s'est écoulé moins de 29 jours depuis le temps created_at du lot (pas le temps 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 demande dans un lot n'affecte pas le traitement des autres demandes.

Stockage et confidentialité des lots

Isolation de l'espace de travail : Les lots sont isolés dans l'espace de travail dans lequel ils sont créés. Ils ne peuvent être accessibles que par les clés API associées à cet espace de travail, ou par les utilisateurs ayant la permission de 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, ce qui laisse amplement de temps pour la récupération et le traitement.

Conservation des données

Le traitement par lot stocke les données de demande et de réponse 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 de traitement, annulez-le d'abord. Le traitement asynchrone nécessite le stockage côté serveur des entrées et des sorties jusqu'à la fin du traitement par lot et la récupération des résultats.

Pour l'admissibilité à ZDR sur toutes les fonctionnalités, consultez Conservation des données et de l'API.

FAQ

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

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)

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

client = anthropic.Anthropic()

# Stream results file in memory-efficient chunks, processing one at a time
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # Request body must be fixed before re-sending request
                print(f"Validation error {result.custom_id}")
            else:
                # Request can be retried directly
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                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.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                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.",
                    }
                ],
            ),
        ),
    ]
)

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)

API Message Batches

Comment fonctionne l'API Message Batches

Limitations des lots

Modèles pris en charge

Ce qui peut être traité par lots

Tarification

Comment utiliser l'API Message Batches

Préparez et créez votre lot

Suivi de votre lot

Interrogation de l'achèvement du Message Batch

Listing all Message Batches

Récupération des résultats du lot

Annulation d'un Message Batch

Utilisation de la mise en cache des invites avec Message Batches

Sortie étendue (bêta)

Meilleures pratiques pour un traitement par lot efficace

Dépannage 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 ?

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

Comment gérer les erreurs dans mes demandes par lot ?

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

Puis-je utiliser la mise en cache des invites dans l'API Message Batches ?