Demande et utilisation de l’API Claude Messages

Anthropic Claude est un système de conversation IA très puissant ; il suffit de saisir une invite pour générer une réponse fluide et naturelle en quelques secondes. L’API Claude Messages est le format d’API natif officiel d’Anthropic. Contrairement au format compatible OpenAI (Chat Completion), elle adopte la structure de requête et de réponse propre à Anthropic, ce qui permet de mieux exploiter les capacités uniques de Claude, telles que l’entrée de contenu multimodal, l’appel d’outils, la réflexion approfondie (Extended Thinking) et d’autres fonctionnalités avancées. Ce document présente principalement le processus d’utilisation de l’API Claude Messages. Grâce à elle, nous pouvons utiliser une interface native cohérente avec celle d’Anthropic officiel pour appeler les fonctionnalités de conversation de Claude.

Processus de demande

Pour utiliser l’API Claude Messages, récupérez d’abord votre API Token depuis la console Ace Data Cloud, et conservez-le pour une utilisation ultérieure.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion qui vous invitera à vous inscrire et à vous connecter ; une fois cela terminé, vous reviendrez automatiquement sur la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service. La première demande offre un quota gratuit, permettant une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger votre solde universel dans la console.

📘 Documentation complète : Claude Messages API →

Utilisation de base

Le chemin de requête de l’API Claude Messages est /v1/messages, identique à celui de l’API officielle d’Anthropic. Nous devons fournir au minimum trois paramètres obligatoires :

model : sélectionnez le modèle Claude à utiliser. claude-opus-5-5 est fourni uniquement via l’API Messages, prend en charge un contexte de 1 million de Token, une sortie maximale de 128K Token, et active toujours la réflexion adaptative. Le dernier modèle phare est claude-fable-5-1 (contexte de 1 million de Token, sortie maximale de 128K Token) ; l’ancien claude-fable-5 reste conservé pour la compatibilité. claude-sonnet-5-5 a rejoint l’interface de la série native Messages, prend en charge l’entrée d’images et la réflexion adaptative ; ses prix de référence officiels pour l’entrée, la sortie et la lecture du cache sont respectivement de 2, 10 et 0,20 dollars par million de Token.
messages : le tableau des messages d’entrée ; chaque message contient role (rôle) et content (contenu), où role prend en charge user et assistant.
max_tokens : le nombre maximal de tokens de sortie, utilisé pour limiter la longueur d’une réponse unique.

Paramètres optionnels couramment utilisés :

system : l’invite système, utilisée pour définir le comportement et le rôle du modèle.
temperature : le caractère aléatoire de la génération, entre 0 et 1 ; plus la valeur est élevée, plus les réponses sont diversifiées.
stream : indique si une réponse en streaming est utilisée ; définie sur true, elle permet un retour caractère par caractère.
stop_sequences : séquences d’arrêt personnalisées ; le modèle cesse de générer lorsqu’il rencontre ces textes.
top_p : paramètre d’échantillonnage nucléaire, utilisé avec temperature pour contrôler le caractère aléatoire de la génération.
top_k : échantillonne uniquement parmi les K options ayant la probabilité la plus élevée.
tools : définition des outils, utilisée pour permettre au modèle d’appeler des fonctions externes.
tool_choice : contrôle la manière dont le modèle utilise les outils fournis.
cache_control : crée automatiquement un point d’arrêt de cache au dernier bloc de contenu pouvant être mis en cache dans la requête ; peut également être écrit sur un bloc de contenu spécifique.

Exemple cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Exemple Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Après l’appel, le résultat retourné est le suivant :

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Description des champs du résultat retourné :

id : l’identifiant unique de ce message.
type : toujours message.
role : toujours assistant.
content : tableau du contenu de la réponse ; chaque élément contient type (tel que text) et le contenu correspondant.
model : le nom du modèle qui traite la requête.
stop_reason : la raison de l’arrêt. Les valeurs stables incluent end_turn, max_tokens, stop_sequence, tool_use, pause_turn (le contenu actuel de l’assistant peut être renvoyé tel quel pour continuer), refusal et model_context_window_exceeded.
stop_sequence : si l’arrêt est dû à une séquence d’arrêt personnalisée, affiche le texte de la séquence d’arrêt correspondante.
stop_details : lorsque stop_reason est refusal, peut contenir la catégorie du refus et une explication.
usage : statistiques d’utilisation des tokens. input_tokens correspond aux entrées non mises en cache ; cache_creation_input_tokens et cache_read_input_tokens correspondent respectivement à l’écriture et à la lecture du cache ; output_tokens est le nombre total de tokens de sortie. Si output_tokens_details.thinking_tokens est retourné, cette valeur est un sous-ensemble de output_tokens ; ne l’ajoutez pas à nouveau lors du calcul du total ou du coût. Ce détail peut être null ou omis lorsqu’aucun comptage faisant autorité n’est disponible.
usage.cache_creation : détail optionnel du TTL d’écriture du cache, contenant ephemeral_5m_input_tokens et ephemeral_1h_input_tokens. Lorsque l’objet existe, la somme des deux est égale à cache_creation_input_tokens ; un champ null ou omis indique qu’aucune ventilation TTL n’est disponible dans la réponse actuelle et ne doit pas être interprété comme 0.
usage.cost : les réponses non streaming peuvent contenir un objet de consommation de quota enregistré par Ace Data Cloud, dans lequel amount est la consommation réelle de cette requête, currency est l’unité de mesure, et list_amount est le montant avant remise (le cas échéant). Le prix de base officiel de lecture du cache pour Fable 5.1 est de 0,25 $/million de Token, et les prix de base d’écriture du cache pour 5 minutes et 1 heure sont respectivement de 12,50$ et 20 $/million de Token ; le prix réel de la plateforme est converti selon les remises du forfait.

Invite système

L’API Claude Messages prend en charge la définition d’une invite système via le champ system, utilisée pour définir le comportement, le rôle et le contexte du modèle.

Exemple Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

En définissant le prompt system, vous pouvez contrôler précisément le rôle et le comportement de Claude.

Réponse en streaming

Cette interface prend également en charge les réponses en streaming ; définissez le paramètre stream sur true pour obtenir un retour progressif, ce qui est particulièrement adapté à l’implémentation d’un affichage caractère par caractère sur une page web.

Exemple Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

La réponse en streaming est renvoyée au format Server-Sent Events (SSE), chaque ligne étant préfixée par event: et data:. Les types d’événements de streaming incluent :

message_start : début du message, contenant les informations de base du message et le nom du modèle.
content_block_start : début du bloc de contenu.
content_block_delta : mise à jour incrémentielle du bloc de contenu, contenant les nouveaux fragments de texte générés.
content_block_stop : fin du bloc de contenu.
message_delta : mise à jour incrémentielle au niveau du message, contenant stop_reason et les informations finales de usage. La valeur de référence de output_tokens_details.thinking_tokens doit uniquement être lue depuis le dernier message_delta.usage, ne l’accumulez pas entre les événements.
message_stop : fin du message.

L’effet de sortie est le suivant :

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

Vous pouvez constater que, dans la réponse en streaming, l’événement content_block_delta contient le contenu textuel généré progressivement ; en concaténant tous les text_delta, vous pouvez obtenir la réponse complète.

Exemple JavaScript

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Hello, Claude" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Conversation multi-tours

Si vous souhaitez intégrer une fonctionnalité de conversation multi-tours, vous devez alterner les messages avec les rôles user et assistant dans le tableau messages, en transmettant également l’historique des conversations précédentes.

Exemple Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Le résultat renvoyé est le suivant :

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

En transmettant l’historique complet de la conversation dans messages, Claude peut fournir des réponses précises en tenant compte du contexte.

Modèle de réflexion approfondie

Le thinking et le thinking summary de Claude sont deux concepts différents : le modèle peut effectuer un raisonnement interne, mais l’API ne renvoie pas la chaîne de pensée brute. Lorsqu’il est nécessaire d’afficher le processus de raisonnement, l’API renvoie un résumé traité. Il est actuellement recommandé d’utiliser l’adaptive thinking pour le modèle actuel, et de contrôler l’investissement global de raisonnement via output_config.effort :

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Le bloc thinking dans la réponse se présente comme suit :

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized" renvoie un résumé de réflexion lisible ; ce n’est pas la chaîne de pensée brute.
display: "omitted" renvoie thinking: "", mais conserve toujours une signature opaque pour prendre en charge les conversations ultérieures.
display: "updates" est le mode beta d’Anthropic, qui nécessite anthropic-beta: thinking-display-updates-2026-08-18. La définition officielle est de masquer le corps du raisonnement et d’afficher de brèves mises à jour de progression entre les appels d’outils. La plateforme transmet ce paramètre et l’en-tête de requête beta tels quels, sans forcer leur réécriture en summarized ; le contenu réel de la sortie dépend de la prise en charge du modèle sélectionné.
thinking, output_config, effort, les paramètres d’échantillonnage et les nouveaux champs d’extension sont transmis tels quels. La plateforme ne maintient pas d’énumérations de valeurs ni de restrictions de combinaisons codées en dur par modèle, et ne réécrit pas automatiquement les modes thinking ; l’acceptation de ces paramètres est déterminée par le modèle sélectionné, et les erreurs de paramètres renvoyées par le modèle seront transmises au client.
Les valeurs par défaut de display pour Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 et Opus 4.7 sont omitted ; Opus 4.6, Sonnet 4.6 et les modèles antérieurs prenant en charge thinking utilisent summarized par défaut.
Display n’affecte que le contenu retourné et la latence de streaming, ne désactive pas le raisonnement et ne réduit pas la facturation des tokens thinking.
L’activation de thinking par défaut et la valeur par défaut de display sont deux questions indépendantes. Opus 5 et Sonnet 5 activent adaptive thinking par défaut ; pour Opus 5, omettre thinking équivaut à adaptive, et omettre output_config.effort équivaut à high. Opus 4.8, 4.7 et 4.6 nécessitent une activation explicite.
Thinking et le corps final partagent le budget de sortie max_tokens. Si le budget est trop faible, thinking peut consommer la majeure partie du quota, laissant le corps vide ou tronqué ; augmentez max_tokens, ou utilisez l’effort low / medium pour contrôler l’investissement dans le raisonnement.
Pour les modèles qui autorisent la désactivation de thinking, vous pouvez transmettre thinking: {"type":"disabled"}. Les nouveaux modes tels que between_tools ainsi que les combinaisons d’effort dépendent du modèle sélectionné ; la plateforme ne les rejettera pas à l’avance selon les anciennes règles de modèle.
Un budget de réflexion fixe peut être transmis via budget_tokens ; les nouveaux modèles utilisent généralement thinking.type=adaptive et output_config.effort. La prise en charge d’un budget fixe ou de la désactivation de la réflexion dépend des capacités actuelles du modèle sélectionné.
Lors de conversations multi-tours et d’appels d’outils, le bloc thinking complet et la signature renvoyés par l’assistant doivent être retransmis tels quels ; ne modifiez pas et ne générez pas vous-même de signature.
La transmission directe des paramètres ne signifie pas que chaque modèle prend en charge toutes les fonctionnalités. Les appels inter-protocoles nécessitent toujours une conversion, et la portée de prise en charge ainsi que les erreurs pour des contenus comme redacted_thinking sont déterminées par le service de modèle qui traite réellement la requête.

Dans les requêtes en streaming, summarized produit thinking_delta ; omitted ne produit pas thinking_delta, et conserve uniquement le cycle de vie du bloc thinking et signature_delta.

Modèles visuels

Claude prend en charge les entrées multimodales et peut traiter simultanément du texte et des images. Dans l’API Messages, les capacités visuelles peuvent être utilisées en définissant content au format tableau et en transmettant des blocs de contenu d’image.

Utiliser des images encodées en Base64

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# 读取并编码图片
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Utiliser des images URL

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Exemple cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'

Les formats d’image pris en charge incluent : image/jpeg, image/png, image/gif, image/webp.

Documents et PDF

Les PDF utilisent des blocs de contenu document et prennent en charge deux sources stables : Base64 et URL. Les sources Base64 doivent utiliser application/pdf :

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

Les sources URL s’écrivent {"type":"url","url":"https://example.com/report.pdf"}. document prend également en charge text/plain et les sources content composées de blocs text/image ; les champs optionnels incluent title, context et citations. Les sources file_id de l’API Files constituent une fonctionnalité beta distincte et ne font pas partie du contrat stable de cette interface.

Mise en cache des prompts

Le cache_control de niveau supérieur placera automatiquement le point d’arrêt du cache sur le dernier bloc pouvant être mis en cache :

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

Lorsque vous devez contrôler précisément la position, vous pouvez également écrire le même cache_control sur les blocs de contenu text, image, document, tool_use, tool_result ou sur la définition de l’outil. ttl prend en charge 5m (par défaut) et 1h ; veuillez déterminer l’écriture et l’atteinte du cache via usage.cache_creation_input_tokens et usage.cache_read_input_tokens. Lorsque la réponse fournit usage.cache_creation, alors ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. Si cache_creation est null ou omis, cela indique qu’il n’existe qu’un total d’écriture dans le cache, sans répartition TTL faisant autorité ; dans ce cas, ne considérez aucun bucket comme étant connu à 0, la facturation et les totaux restent basés sur le champ aggregate. Exemple de résultat retourné :

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Appel d’outils (Tool Use)

L’API Claude Messages prend nativement en charge la fonctionnalité d’appel d’outils, permettant au modèle d’appeler vos outils/fonctions prédéfinis lorsque nécessaire.

Exemple Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Lorsque le modèle décide d’appeler un outil, le champ content dans le résultat retourné contient un bloc de contenu de type tool_use :

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

Notez que stop_reason est tool_use, ce qui indique que le modèle doit appeler un outil. Après avoir reçu ce résultat, vous devez exécuter la fonction outil et renvoyer le résultat au modèle sous la forme d’un tool_result :

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sunny, 72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Le modèle générera une réponse finale en langage naturel sur la base du résultat retourné par l’outil.

Différences avec l’API Chat Completion

Ace Data Cloud fournit simultanément deux formats d’API Claude, dont les principales différences sont les suivantes : Le champ usage.input_tokens de l’API Messages ne représente que les entrées non mises en cache ; cache_read_input_tokens et cache_creation_input_tokens sont des buckets de facturation indépendants ; les trois sont calculés séparément selon les prix correspondants.

Fonctionnalité	API Messages (`/v1/messages`)	API Chat Completion (`/v1/chat/completions`)
Format	Format natif Anthropic	Format compatible OpenAI
Invite système	Champ `system` indépendant	Transmise via `role: "system"` dans `messages`
Structure de réponse	Tableau `content` (prend en charge plusieurs types)	Tableau `choices` (contient `message`)
Format de streaming	Événements SSE (plusieurs types d’événements)	Lignes SSE `data`
Raisonnement approfondi	`thinking` natif et `output_config.effort`	Stratégie par défaut du modèle et paramètres de compatibilité
Appel d’outils	`tools` natif + `input_schema`	Format `tools` compatible OpenAI
Statistiques de tokens	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

Si votre système est déjà intégré à une API au format OpenAI, vous pouvez utiliser l’API Chat Completion pour basculer de manière transparente. Si vous devez utiliser toutes les capacités natives de Claude, il est recommandé d’utiliser l’API Messages.

Gestion des erreurs

Les réponses d’erreur de l’interface publique utilisent l’enveloppe de la plateforme Ace Data Cloud : error.code est un code d’erreur stable, error.message est une description, et trace_id est utilisé pour diagnostiquer les requêtes. Les statuts HTTP courants incluent :

400 : les paramètres de la requête ou le contenu du protocole sont invalides.
401 : le jeton d’autorisation est invalide, absent ou expiré.
403 : accès interdit, solde insuffisant ou quota limité.
404 : l’API ou le modèle n’existe pas.
413 : le corps de la requête est trop volumineux.
429 : trop de requêtes.
500 / 503 / 504 : erreur de service, indisponibilité temporaire ou délai de traitement dépassé.

Exemple de réponse d’erreur

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Cette structure d’erreur est le contrat d’exécution d’Ace Data Cloud et n’est pas équivalente à l’enveloppe d’erreur officielle d’Anthropic ; veuillez la traiter selon le statut HTTP et error.code.

Conclusion

Grâce à ce document, vous avez déjà appris comment utiliser l’API Claude Messages pour appeler les fonctionnalités de conversation de Claude au format natif d’Anthropic. L’API Messages prend en charge de nombreuses fonctionnalités, notamment les conversations de base, les invites système, les réponses en streaming, les conversations à plusieurs tours, la réflexion approfondie, la compréhension visuelle, les PDF, la mise en cache des invites et l’appel d’outils. Si vous avez des questions, n’hésitez pas à contacter notre équipe de support technique.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Demande et utilisation de l’API Claude Messages

Processus de demande

Utilisation de base

Exemple cURL

Exemple Python

Invite système

Exemple Python

Réponse en streaming

Exemple Python

Exemple JavaScript

Conversation multi-tours

Exemple Python

Modèle de réflexion approfondie

Modèles visuels

Utiliser des images encodées en Base64

Utiliser des images URL

Exemple cURL

Documents et PDF

Mise en cache des prompts

Appel d’outils (Tool Use)

Exemple Python

Différences avec l’API Chat Completion

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

​Processus de demande

​Utilisation de base

​Exemple cURL

​Exemple Python

​Invite système

​Exemple Python

​Réponse en streaming

​Exemple Python

​Exemple JavaScript

​Conversation multi-tours

​Exemple Python

​Modèle de réflexion approfondie

​Modèles visuels

​Utiliser des images encodées en Base64

​Utiliser des images URL

​Exemple cURL

​Documents et PDF

​Mise en cache des prompts

​Appel d’outils (Tool Use)

​Exemple Python

​Différences avec l’API Chat Completion

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

Processus de demande

Utilisation de base

Exemple cURL

Exemple Python

Invite système

Exemple Python

Réponse en streaming

Exemple Python

Exemple JavaScript

Conversation multi-tours

Exemple Python

Modèle de réflexion approfondie

Modèles visuels

Utiliser des images encodées en Base64

Utiliser des images URL

Exemple cURL

Documents et PDF

Mise en cache des prompts

Appel d’outils (Tool Use)

Exemple Python

Différences avec l’API Chat Completion

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion