Format de discussion anthropique (Messages)

Documentation officielle

Messages anthropiques - Anthropic Streaming Messages

📝Présentation

Étant donné une liste de messages d'entrée structurés contenant du texte et/ou des images, le modèle générera le prochain message de la conversation. L'API Messages peut être utilisée pour des requêtes uniques ou des conversations multitours sans état.

💡 Exemples de requêtes

Chat textuel de base ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

Response Example:

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}

Chat d'analyse d'images ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "/9j/4AAQSkZJRg..."
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}'

Response Example:

{
  "content": [
    {
      "text": "This image shows an orange cat sunbathing on a windowsill. The cat looks very relaxed, squinting its eyes while enjoying the sunlight. Some green plants can be seen outside the window.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

Appel d'outils ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": "What's the weather like in Beijing today?"
        }
    ],
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather for a specified location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, e.g.: Beijing"
                    }
                },
                "required": ["location"]
            }
        }
    ]
}'

Response Example:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_weather",
      "input": { "location": "Beijing" }
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

Réponse en streaming ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": "Tell me a story"
        }
    ],
    "stream": true
}'

Response Example:

{
  "type": "message_start",
  "message": {
    "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
    "model": "claude-3-5-sonnet-20241022",
    "role": "assistant",
    "type": "message"
  }
}
{
  "type": "content_block_start",
  "index": 0,
  "content_block": {
    "type": "text"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "Once upon a time"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "There is one"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "bunny..."
  }
}
{
  "type": "content_block_stop",
  "index": 0
}
{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 2045,
      "output_tokens": 628
    }
  }
}
{
  "type": "message_stop"
}

📮 Demande

Points de terminaison

POST /v1/messages

Méthode d'authentification

Incluez les éléments suivants dans les en-têtes de demande pour l'authentification par clé API:

x-api-key: $API_KEY

Où $API_KEY est votre clé API. Vous pouvez obtenir une clé API à partir de la console et chaque clé est limitée à un espace de travail.

En-têtes de requête

`anthropic-beta`

Type : Chaîne
Obligatoire: Non

Spécifiez la version bêta à utiliser, prise en charge par des listes séparées par des virgules comme beta1,beta2, ou spécifiez cet en-tête plusieurs fois.

`anthropic-version`

Type : Chaîne
Obligatoire : Oui

Spécifiez la version de l'API à utiliser.

Paramètres du corps de la requête

`max_tokens`

Type : Entier
Obligatoire : Oui

Le nombre maximum de jetons à générer. Différents modèles ont des limites différentes, voir la documentation du modèle. Plage x > 1.

`messages`

Type : Tableau d'objets
Obligatoire : Oui

La liste des messages d’entrée. Le modèle est formé pour alterner entre utilisateur et assistant dans la conversation. Lors de la création d'un nouveau message, vous pouvez utiliser le paramètre messages pour spécifier les tours de conversation précédents, et le modèle générera le message suivant dans la conversation. Les messages consécutifs de l'utilisateur ou de l'assistant sont fusionnés en un seul tour.

Chaque message doit contenir les champs role et content. Vous pouvez spécifier un seul message de rôle d'utilisateur ou inclure plusieurs messages d'utilisateur et d'assistant. Si le dernier message utilise le rôle d'assistant, le contenu de la réponse continuera directement à partir du contenu de ce message, qui peut être utilisé pour contraindre la réponse du modèle.

Single User Message Example:

[{ "role": "user", "content": "Hello, Claude" }]

Multi-turn Conversation Example:

[
  { "role": "user", "content": "Hello。" },
  { "role": "assistant", "content": "Hello！I am Claude。Is there anything I can help you with?？" },
  { "role": "user", "content": "Please explain in simple words what is LLM？" }
]

Partially Filled Response Example:

[
  {
    "role": "user",
    "content": "What is the Greek name for the sun?? (A) Sol (B) Helios (C) Sun"
  },
  { "role": "assistant", "content": "The correct answer is (" }
]

Le contenu de chaque message peut être une chaîne ou un tableau de blocs de contenu. Utiliser une chaîne équivaut à un raccourci pour un tableau de blocs de contenu de type « texte ». Les deux affirmations suivantes sont équivalentes:

{ "role": "user", "content": "Hello, Claude" }

{
  "role": "user",
  "content": [{ "type": "text", "text": "Hello, Claude" }]
}

A partir du modèle Claude 3, vous pouvez également envoyer des blocs de contenu image :

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRg..."
      }
    },
    {
      "type": "text",
      "text": "What's in this image?"
    }
  ]
}

Les formats d'image actuellement pris en charge incluent: base64, image/jpeg, image/png, image/gif et image/webp.

`messages.role`

Type : Chaîne
Obligatoire : Oui
Valeurs facultatives: utilisateur, assistant

Remarque: L'API Messages n'a pas de rôle "système". Si une invite système est nécessaire, veuillez utiliser le paramètre system de niveau supérieur.

`messages.content`

Type: Chaîne ou Tableau d'objets
Obligatoire : Oui

Le contenu d'un message peut être de l'un des types suivants:

Contenu du texte (Texte)

{
  "type": "text", // Required, enum value: "text"
  "text": "Hello, Claude", // Required, minimum length: 1
  "cache_control": {
    "type": "ephemeral" // Optional, enum value: "ephemeral"
  }
}

Contenu de l'image (Image)

{
  "type": "image", // Required, enum value: "image"
  "source": {
    // Required
    "type": "base64", // Required, enum value: "base64"
    "media_type": "image/jpeg", // Required, supported: image/jpeg, image/png, image/gif, image/webp
    "data": "/9j/4AAQSkZJRg..." // Required, base64 encoded image data
  },
  "cache_control": {
    "type": "ephemeral" // Optional, enum value: "ephemeral"
  }
}

Utilisation des outils (Utilisation des outils)

{
  "type": "tool_use", // Required, enum value: "tool_use", default value
  "id": "toolu_xyz...", // Required, unique identifier for tool use
  "name": "get_weather", // Required, tool name, minimum length: 1
  "input": {
    // Required, object containing tool input parameters
    // Tool input parameters, specific format defined by tool's input_schema
  },
  "cache_control": {
    "type": "ephemeral" // Optional, enum value: "ephemeral"
  }
}

Résultat de l'outil (Résultat de l'outil)

{
  "type": "tool_result", // Required, enum value: "tool_result"
  "tool_use_id": "toolu_xyz...", // Required
  "content": "Result content", // Required, can be string or array of content blocks
  "is_error": false, // Optional, boolean
  "cache_control": {
    "type": "ephemeral" // Optional, enum value: "ephemeral"
  }
}

Lorsque le contenu est un tableau de blocs de contenu, chaque bloc de contenu peut être du texte ou une image:

{
  "type": "tool_result",
  "tool_use_id": "toolu_xyz...",
  "content": [
    {
      "type": "text", // Required, enum value: "text"
      "text": "Analysis result", // Required, minimum length: 1
      "cache_control": {
        "type": "ephemeral" // Optional, enum value: "ephemeral"
      }
    },
    {
      "type": "image", // Required, enum value: "image"
      "source": {
        // Required
        "type": "base64", // Required, enum value: "base64"
        "media_type": "image/jpeg",
        "data": "..."
      },
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

Document (Document)

{
  "type": "document", // Required, enum value: "document"
  "source": {
    // Required
    // Document source data
  },
  "cache_control": {
    "type": "ephemeral" // Optional, enum value: "ephemeral"
  }
}

Note:

Chaque type peut éventuellement inclure un champ cache_control pour contrôler la mise en cache du contenu
La longueur minimale du contenu du texte est de 1
Tous les champs de type sont des chaînes d'énumération obligatoires
Le champ content des résultats de l'outil prend en charge une chaîne ou un tableau de blocs de contenu contenant du texte/image.

`model`

Type : Chaîne
Obligatoire : Oui

Le nom du modèle à utiliser, voir la documentation du modèle. Plage de 1 - 256 caractères.

`metadata`

Type : Objet
Obligatoire: Non

Un objet décrivant les métadonnées de la demande. Comprend les champs facultatifs suivants:

user_id : Un identifiant externe de l'utilisateur associé à la requête. Il doit s'agir d'un uuid, d'un hachage ou d'un autre identifiant opaque. N'incluez aucune information d'identification telle que votre nom, votre adresse e-mail ou votre numéro de téléphone. Longueur maximale : 256.

`stop_sequences`

Type : Tableau de chaînes
Obligatoire: Non

Séquences de texte personnalisées pour arrêter la génération.

`stream`

Type: Booléen
Obligatoire: Non

Indique s'il faut utiliser les événements envoyés par le serveur (SSE) pour renvoyer progressivement le contenu de la réponse.

`system`

Type : Chaîne
Obligatoire: Non

Invite du système, fournit des informations et des instructions à Claude. Il s'agit d'un moyen de fournir un contexte et des objectifs ou rôles spécifiques au modèle. Notez que ceci est différent du role dans les messages et que l'API Messages n'a pas de rôle « système ».

`temperature`

Type : Numéro
Obligatoire: Non
Par défaut: 1,0

Contrôle le caractère aléatoire de la génération, 0,0 - 1,0. Plage 0 < x < 1`. Il est recommandé d'utiliser une valeur proche de 0,0 pour les tâches analytiques/à choix multiples, et une valeur proche de 1,0 pour les tâches créatives et génératives.

Remarque: Même si la température est définie sur 0,0, le résultat ne sera pas complètement déterministe.

🆕 `thinking`

Type : Objet
Obligatoire: Non

Configure la fonction de réflexion étendue de Claude. Lorsqu'elle est activée, la réponse comprendra des blocs de contenu montrant le processus de réflexion de Claude avant de donner la réponse finale. Nécessite au moins 1 024 jetons de budget et est pris en compte dans votre limite max_tokens.

Peut être réglé sur l’un des deux modes suivants:

1. Mode activé

{
  "type": "enabled",
  "budget_tokens": 2048
}

type: Obligatoire, valeur d'énumération: "enabled"
budget_tokens : Obligatoire, entier. Détermine le nombre de jetons que Claude peut utiliser pour les processus de raisonnement interne. Un budget plus important permet au modèle d'effectuer une analyse plus approfondie sur des questions complexes, améliorant ainsi la qualité des réponses. Doit être ≥1024 et inférieur à max_tokens. Plage x > 1024`.

2. Mode désactivé

{
  "type": "disabled"
}

type: Obligatoire, valeur d'énumération: "désactivé"

`tool_choice`

Type : Objet
Obligatoire: Non

Contrôle la manière dont le modèle utilise les outils fournis. Il peut s'agir de l'un des trois types suivants:

1. Mode automatique (sélection automatique)

{
  "type": "auto", // Required, enum value: "auto"
  "disable_parallel_tool_use": false // Optional, default false. If true, the model will only use one tool at most
}

2. N'importe quel mode (n'importe quel outil)

{
  "type": "any", // Required, enum value: "any"
  "disable_parallel_tool_use": false // Optional, default false. If true, the model will exactly use one tool
}

3. Mode outil (outil spécifique)

{
  "type": "tool", // Required, enum value: "tool"
  "name": "get_weather", // Required, specify the tool name to use
  "disable_parallel_tool_use": false // Optional, default false. If true, the model will exactly use one tool
}

Note:

Mode automatique: le modèle peut décider s'il doit utiliser les outils lui-même.
N'importe quel mode: le modèle doit utiliser des outils, mais peut choisir n'importe quel outil disponible.
Mode outil: le modèle doit utiliser l'outil spécifié

`tools`

Type : Tableau d'objets
Obligatoire: Non

Définit les outils que le modèle peut utiliser. Les outils peuvent être des outils personnalisés ou des types d'outils intégrés:

1. Outil personnalisé (Outil)

Chaque définition d'outil personnalisé comprend:

type: Facultatif, valeur d'énumération: "custom"
name: Nom de l'outil, obligatoire, 1 à 64 caractères
description: Description de l'outil, il est recommandé d'être la plus détaillée possible
input_schema: définition du schéma JSON pour la saisie de l'outil, obligatoire
cache_control: Contrôle du cache, optionnel, le type est "éphémère"

Exemple:

[
  {
    "type": "custom",
    "name": "get_weather",
    "description": "Get the current weather for a specified location",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name, e.g.: Beijing"
        }
      },
      "required": ["location"]
    }
  }
]

2. Outil informatique (ComputerUseTool)

{
  "type": "computer_20241022", // Required
  "name": "computer", // Required, enum value: "computer"
  "display_width_px": 1024, // Required, display width (pixels)
  "display_height_px": 768, // Required, display height (pixels)
  "display_number": 0, // Optional, X11 display number
  "cache_control": {
    "type": "ephemeral" // Optional
  }
}

3. Outil Bash (BashTool)

{
  "type": "bash_20241022", // Required
  "name": "bash", // Required, enum value: "bash"
  "cache_control": {
    "type": "ephemeral" // Optional
  }
}

4. Outil d'édition de texte (TextEditor)

{
  "type": "text_editor_20241022", // Required
  "name": "str_replace_editor", // Required, enum value: "str_replace_editor"
  "cache_control": {
    "type": "ephemeral" // Optional
  }
}

Lorsque le modèle utilise un outil, il renvoie un bloc de contenu tool_use:

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_weather",
    "input": { "location": "Beijing" }
  }
]

Vous pouvez exécuter un outil et renvoyer le résultat via un bloc de contenu tool_result:

[
  {
    "type": "tool_result",
    "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "content": "The weather in Beijing today is sunny, with a temperature of 25°C"
  }
]

`top_k`

Type : Entier
Obligatoire: Non
Plage : x > 0

Échantillons des K principales options de jetons. Utilisé pour supprimer les réponses « longue traîne » avec de faibles probabilités. Il est recommandé de ne l'utiliser que dans des cas d'utilisation avancés, généralement seul le réglage de la température suffit.

`top_p`

Type : Numéro
Obligatoire: Non
Plage : 0 `< x < 1

Utilise l'échantillonnage du noyau. Calcule la distribution cumulée des probabilités pour chaque jeton suivant par ordre décroissant, tronque lorsque la probabilité atteint le top_p spécifié. Il est recommandé de régler un seul élément de température ou top_p, pas les deux.

📥 Réponse

Réponse réussie

Renvoie un objet de fin de discussion contenant les champs suivants:

`content`

Type : Tableau d'objets
Obligatoire : Oui

Le contenu généré par le modèle, composé de plusieurs blocs de contenu. Chaque bloc de contenu possède un type qui détermine sa forme. Les blocs de contenu peuvent être de l'un des types suivants:

Bloc de contenu texte (Texte)

{
  "type": "text", // Required, enum value: "text", default value
  "text": "Hello，I am Claude。" // Required, maximum length: 5000000, minimum length: 1
}

Bloc de contenu d'utilisation de l'outil (utilisation de l'outil)

{
  "type": "tool_use", // Required, enum value: "tool_use", default value
  "id": "toolu_xyz...", // Required, unique identifier for tool use
  "name": "get_weather", // Required, tool name, minimum length: 1
  "input": {
    // Required, object containing tool input parameters
    // Tool input parameters, specific format defined by tool's input_schema
  }
}

Exemple:

// Text content example
[{"type": "text", "text": "Hello，I am Claude。"}]

// Tool use example
[{
  "type": "tool_use",
  "id": "toolu_xyz...",
  "name": "get_weather",
  "input": { "location": "Beijing" }
}]

// Mixed content example
[
  {"type": "text", "text": "Query results based on weather："},
  {
    "type": "tool_use",
    "id": "toolu_xyz...",
    "name": "get_weather",
    "input": { "location": "Beijing" }
  }
]

Si le dernier message de la demande était un rôle d'assistant, le contenu de la réponse continuera directement à partir de ce message. Par exemple:

// Request
[
  {"role": "user", "content": "What is the Greek name for the sun?? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The correct answer is ("}
]

// Response
[{"type": "text", "text": "B)"}]

`id`

Type : Chaîne
Obligatoire : Oui

L'identifiant unique de la réponse.

`model`

Type : Chaîne
Obligatoire : Oui

Le nom du modèle utilisé.

`role`

Type : Chaîne
Obligatoire : Oui
Par défaut: assistant

Le rôle de session pour le message généré, toujours "assistant".

`stop_reason`

Type: chaîne ou null
Obligatoire : Oui

La raison de l'arrêt de la génération, les valeurs possibles incluent:

"end_turn": Le modèle a atteint un point d'arrêt naturel
"max_tokens": Dépassement du nombre max_tokens demandé ou de la limite maximale du modèle
"stop_sequence": Génération d'une des séquences d'arrêt personnalisées
"tool_use" : Modèle appelé un ou plusieurs outils

Cette valeur est toujours non vide en mode non-streaming. En mode streaming, il est nul dans l'événement message_start, et non nul dans le cas contraire.

`stop_sequence`

Type: chaîne ou null
Obligatoire : Oui

La séquence d'arrêt personnalisée générée. Si le modèle a rencontré l'une des stop_sequences spécifiées dans le paramètre stop_sequences, ce champ contiendra cette séquence d'arrêt correspondante. S'il n'est pas arrêté par une séquence d'arrêt, il est nul.

`type`

Type : Chaîne
Obligatoire : Oui
Par défaut: message
Facultatif: message

Type d'objet, toujours "message" pour Messages.

`usage`

Type : Objet
Obligatoire : Oui

Statistiques d'utilisation liées à la facturation et aux limites tarifaires. Comprend les champs suivants:

input_tokens : Nombre de jetons d'entrée utilisés, requis, plage x >` 0
output_tokens: Nombre de jetons de sortie utilisés, requis, plage x > 0
cache_creation_input_tokens : Nombre de jetons d'entrée utilisés pour créer des entrées de cache (le cas échéant), obligatoire, plage x > 0
cache_read_input_tokens: Nombre de jetons d'entrée lus dans le cache (le cas échéant), obligatoire, plage x > 0

Remarque: En raison des transformations et de l'analyse internes de l'API, le nombre de jetons peut ne pas correspondre exactement au contenu visible réel des requêtes et des réponses. Par exemple, même une réponse de chaîne vide aura une valeur output_tokens non nulle.

Réponse d'erreur

Lorsqu'une requête rencontre un problème, l'API renvoie un objet de réponse d'erreur, avec des codes d'état HTTP compris entre 4XX et 5XX.

Codes d'état d'erreur courants

401 Unauthorized: Clé API invalide ou non fournie
400 Bad Request: Paramètres de requête invalides
429 Too Many Requests: limite d'appels API dépassée
500 Internal Server Error: Erreur interne du serveur

Exemple de réponse d'erreur:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key"
  }
}

Principaux types d'erreurs:

invalid_request_error: Erreur de paramètre de requête
authentication_error: Erreur liée à l'authentification
rate_limit_error: Fréquence de requête dépassée
server_error: Erreur interne du serveur

Sommaire