Demande et utilisation de l'API Claude Messages

Anthropic Claude est un système de dialogue AI très puissant, capable de générer des réponses fluides et naturelles en quelques secondes simplement en entrant un mot-clé. L’API Claude Messages est le format d’API natif officiel d’Anthropic, qui, contrairement au format compatible avec OpenAI (Chat Completion), utilise sa propre structure de requête et de réponse, permettant 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 caractéristiques avancées. Ce document présente principalement le processus d’utilisation de l’API Claude Messages, permettant d’utiliser une interface native conforme aux normes d’Anthropic pour appeler les fonctionnalités de dialogue de Claude.

Processus de demande

Pour utiliser l’API Claude Messages, vous pouvez d’abord vous rendre sur la page Claude Messages API et cliquer sur le bouton « Acquire » pour obtenir les informations d’identification nécessaires à la demande :

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter. Après vous être connecté ou inscrit, vous serez automatiquement renvoyé à la page actuelle. Lors de la première demande, un quota gratuit sera offert, vous permettant d’utiliser cette API gratuitement.

Utilisation de base

Le chemin de requête de l’API Claude Messages est /v1/messages, en accord avec l’API officielle d’Anthropic. Nous devons fournir au moins trois paramètres obligatoires :

model : choisir le modèle Claude à utiliser, tel que claude-opus-4-20250514, claude-sonnet-4-20250514, etc.
messages : tableau de messages d’entrée, chaque message contenant role (rôle) et content (contenu), où role prend en charge user et assistant.
max_tokens : nombre maximum de tokens de sortie, utilisé pour limiter la longueur de la réponse unique.

Paramètres optionnels courants :

system : mot-clé système, utilisé pour définir le comportement et le rôle du modèle.
temperature : aléatoire de génération, entre 0 et 1, plus la valeur est élevée, plus la réponse est dispersée.
stream : utiliser ou non la réponse en continu, en le définissant sur true, vous pouvez obtenir un effet de retour lettre par lettre.
stop_sequences : séquences d’arrêt personnalisées, le modèle s’arrêtera de générer lorsqu’il rencontrera ces textes.
top_p : paramètre d’échantillonnage nucléaire, en combinaison avec la température pour contrôler le caractère aléatoire de la génération.
top_k : échantillonnage uniquement parmi les K options les plus probables.
tools : définition des outils, permettant au modèle d’appeler des fonctions externes.
tool_choice : contrôle de la manière dont le modèle utilise les outils fournis.

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": "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-sonnet-4-20250514",
    "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-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Explication des champs de résultat :

id : identifiant unique de ce message.
type : toujours message.
role : toujours assistant.
content : tableau de contenu de réponse, chaque élément contenant type (comme text) et le contenu correspondant.
model : nom du modèle traitant la demande.
stop_reason : raison de l’arrêt, les valeurs possibles incluent end_turn (fin normale), max_tokens (atteint la longueur maximale), stop_sequence (rencontre une séquence d’arrêt), tool_use (appel d’outil).
stop_sequence : si l’arrêt est dû à une séquence d’arrêt personnalisée, le texte de la séquence d’arrêt correspondante est affiché.
usage : statistiques d’utilisation des tokens, comprenant input_tokens (nombre de tokens d’entrée) et output_tokens (nombre de tokens de sortie).

Mot-clé système

L’API Claude Messages prend en charge la définition de mots-clés système via le champ system, utilisé 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": "Vous êtes un assistant de traduction chinois professionnel, veuillez traduire l'anglais saisi par l'utilisateur en chinois.",
    "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 mot-clé system, vous pouvez contrôler précisément le rôle et le comportement de Claude.

Réponse en continu

Cette interface prend également en charge les réponses en continu, en définissant le paramètre stream sur true, vous pouvez obtenir un effet de retour progressif, très adapté pour afficher lettre par lettre 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"))

Les réponses en continu sont retournées au format Server-Sent Events (SSE), chaque ligne étant précédée de event: et data:. Les types d’événements en continu 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 de nouveaux segments 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 d’usage.
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":"Salut"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! Je m'appelle"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. Comment puis-je vous aider aujourd'hui?"}}

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"}

On peut voir que l’événement content_block_delta dans la réponse en streaming contient le contenu généré progressivement, en concaténant tous les text_delta, on peut 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: "Bonjour, 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));
}

Dialogue multi-tours

Si vous souhaitez intégrer une fonctionnalité de dialogue multi-tours, vous devez alterner les messages des rôles user et assistant dans le tableau messages, en incluant 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": "Bonjour, je m'appelle Alice."},
        {"role": "assistant", "content": "Bonjour Alice ! Enchanté de vous rencontrer. Comment puis-je vous aider aujourd'hui ?"},
        {"role": "user", "content": "Quel est mon nom ?"}
    ]
}

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

Le résultat est le suivant :

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Votre nom est Alice, comme vous venez de me le dire !"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

En passant l’historique complet de la conversation dans messages, Claude peut répondre avec précision en tenant compte du contexte.

Modèle de réflexion approfondie

Claude prend en charge la fonctionnalité de réflexion approfondie (Extended Thinking), qui permet au modèle de procéder à un raisonnement interne avant de répondre, améliorant ainsi la précision du traitement des problèmes complexes. Pour utiliser cette fonctionnalité, il est nécessaire de passer le paramètre thinking.

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": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Quelle est le sinus de 30 degrés ? Montrez votre raisonnement."}
    ]
}

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

Le résultat est le suivant :

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "L'utilisateur demande le sinus de 30 degrés. C'est une question de trigonométrie de base.\n\nDans un triangle 30-60-90, les côtés sont dans le rapport 1:√3:2.\n\nPour un angle de 30° :\n- Le côté opposé est 1\n- L'hypoténuse est 2\n- Donc sin(30°) = opposé/hypoténuse = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "Le sinus de 30 degrés est **1/2** ou **0.5**.\n\nC'est l'une des valeurs trigonométriques fondamentales. Dans un triangle 30-60-90, les côtés sont dans le rapport 1:√3:2, où le côté opposé à l'angle de 30° a une longueur de 1 et l'hypoténuse a une longueur de 2, ce qui nous donne sin(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}

On peut voir que le tableau content contient deux blocs de contenu :

type: "thinking" : le processus de réflexion interne du modèle, montrant les étapes de raisonnement.
type: "text" : le résultat final de la réponse.

Remarques :

Lors de l’utilisation de thinking, max_tokens doit être supérieur à budget_tokens, car budget_tokens est le budget de tokens alloué au processus de réflexion.
Plus budget_tokens est élevé, plus le modèle a d’espace pour un raisonnement approfondi, ce qui est adapté pour traiter des problèmes complexes.

Modèle visuel

Claude prend en charge les entrées multimodales, pouvant traiter simultanément du texte et des images. Dans l’API Messages, vous pouvez utiliser la capacité visuelle en définissant content au format tableau et en passant des blocs de contenu d’image.

Utilisation d’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"
}

# Lire et encoder l'image
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": "Qu'est-ce qu'il y a dans cette image ?"
                }
            ]
        }
    ]
}

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

Utilisation d’images par URL

```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": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Qu'est-ce qu'il y a dans cette image ?"
                }
            ]
        }
    ]
}

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

cURL Exemple

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": "Qu'est-ce qu'il y a dans cette image ?"
          }
        ]
      }
    ]
  }'

Les formats d’image pris en charge incluent : image/jpeg, image/png, image/gif, image/webp. Exemple de résultat retourné :

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Cette image montre une interface de configuration de requête API pour ce qui semble être un service de complétion de chat AI. L'interface comprend des paramètres pour la sélection du modèle, les messages, le mode de flux et les paramètres de tokens maximum."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Utilisation des outils (Tool Use)

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

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": "Obtenir la météo actuelle dans un lieu donné",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ville et l'état, par exemple San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Quel temps fait-il à San Francisco ?"}
    ]
}

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

Lorsque le modèle décide d’appeler un outil, le contenu de la réponse contiendra un bloc de type tool_use :

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Laissez-moi vérifier la météo à San Francisco pour vous."
    },
    {
      "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 de l’outil et renvoyer le résultat sous la forme tool_result au modèle :

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle dans un lieu donné",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ville et l'état, par exemple San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Quel temps fait-il à San Francisco ?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Laissez-moi vérifier la météo à San Francisco pour vous."},
                {"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": "Ensoleillé, 72°F"
                }
            ]
        }
    ]
}

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

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

Différences avec l’API de complétion de chat

Ace Data Cloud propose deux formats d’API Claude, les principales différences sont les suivantes :

Caractéristique	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
Format	Format natif d’Anthropic	Format compatible avec OpenAI
Système de prompt	Champ `system` indépendant	Transmis via `role: "system"` dans `messages`
Structure de réponse	Tableau `content` (supporte plusieurs types)	Tableau `choices` (contient `message`)
Format de flux	Événements SSE (plusieurs types d’événements)	Lignes SSE `data`
Réflexion profonde	Paramètre `thinking` natif	Déclenché par un nom de modèle spécial (comme suffixe `-thinking`)
Appel d’outils	`tools` natif + `input_schema`	Format `functions` compatible avec OpenAI
Statistiques de tokens	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

Si votre système est déjà intégré à l’API au format OpenAI, vous pouvez utiliser l’API de complétion de chat pour une transition fluide. Si vous avez besoin d’utiliser toutes les capacités natives de Claude, il est recommandé d’utiliser l’API Messages.

Gestion des erreurs

Lors de l’appel de l’API, si une erreur se produit, l’API renverra le code d’erreur et les informations correspondantes. Par exemple :

400 token_mismatched : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
400 api_not_implemented : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
401 invalid_token : Non autorisé, jeton d’autorisation invalide ou manquant.
429 too_many_requests : Trop de requêtes, vous avez dépassé la limite de taux.
500 api_error : Erreur interne du serveur, quelque chose s’est mal passé sur le serveur.

Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "échec de la récupération"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Grâce à ce document, vous avez compris 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 des fonctionnalités riches telles que la conversation de base, les invites système, les réponses en continu, les conversations multi-tours, la réflexion approfondie, la compréhension visuelle et les appels 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é

Proxy

Avancé

Demande et utilisation de l'API Claude Messages

Processus de demande

Utilisation de base

Exemple cURL

Exemple Python

Mot-clé système

Exemple Python

Réponse en continu

Exemple Python

Exemple JavaScript

Dialogue multi-tours

Exemple Python

Modèle de réflexion approfondie

Exemple Python

Modèle visuel

Utilisation d’images encodées en Base64

Utilisation d’images par URL

cURL Exemple

Utilisation des outils (Tool Use)

Exemple Python

Différences avec l’API de complétion de chat

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

​Processus de demande

​Utilisation de base

​Exemple cURL

​Exemple Python

​Mot-clé système

​Exemple Python

​Réponse en continu

​Exemple Python

​Exemple JavaScript

​Dialogue multi-tours

​Exemple Python

​Modèle de réflexion approfondie

​Exemple Python

​Modèle visuel

​Utilisation d’images encodées en Base64

​Utilisation d’images par URL

​cURL Exemple

​Utilisation des outils (Tool Use)

​Exemple Python

​Différences avec l’API de complétion de chat

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

Processus de demande

Utilisation de base

Exemple cURL

Exemple Python

Mot-clé système

Exemple Python

Réponse en continu

Exemple Python

Exemple JavaScript

Dialogue multi-tours

Exemple Python

Modèle de réflexion approfondie

Exemple Python

Modèle visuel

Utilisation d’images encodées en Base64

Utilisation d’images par URL

cURL Exemple

Utilisation des outils (Tool Use)

Exemple Python

Différences avec l’API de complétion de chat

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion