TokenLab

Texte

Créer un message

Crée un message en utilisant le format Anthropic Messages API

POST
/v1/messages

Aperçu

Ce point de terminaison accepte le format natif Anthropic Messages, ce qui permet aux SDK Anthropic et aux outils basés sur ceux-ci de fonctionner avec l'URL de base de TokenLab. Il fonctionne avec les modèles dont le champ accepted_request_formats liste anthropic_messages : les modèles Claude et certains autres modèles.

messages contient les tours user et assistant. Placez les instructions système dans le champ system au niveau racine. max_tokens est requis. Pour les messages de style OpenAI avec des rôles tels que system ou tool, utilisez Chat Completions.

URL de base pour le SDK Anthropic : https://api.tokenlab.sh (sans le suffixe /v1)

En-têtes de requête

x-api-keystringheader

Votre clé API TokenLab. Envoyez soit x-api-key, soit Authorization: Bearer <API_KEY>. Si vous envoyez les deux avec des valeurs différentes, TokenLab utilise x-api-key.

anthropic-versionstringheader

Version de l'API Anthropic. Les SDK Anthropic l'envoient pour vous ; utilisez 2023-06-01 lorsque vous appelez l'API directement.

anthropic-betastringheader

Noms des fonctionnalités bêta d'Anthropic, séparés par des virgules. TokenLab transmet l'en-tête, et le fonctionnement d'une fonctionnalité bêta dépend du modèle. Le contenu faisant référence à un file_id nécessite files-api-2025-04-14.

Corps de la requête

Les paramètres optionnels pris en charge, les valeurs acceptées et les valeurs par défaut dépendent du modèle sélectionné. Vérifiez ses détails du modèle avant de définir les options d'échantillonnage, de raisonnement ou d'outils.

modelstringrequis

ID d'un modèle qui prend en charge le format anthropic_messages. Vérifiez ses détails du modèle pour connaître les capacités actuelles.

messagesarrayrequis

Tableau d'objets de message avec role (user ou assistant) et content. Jusqu'à 100 000 messages.

content peut être une chaîne de caractères simple ou un tableau de blocs de contenu. Pour envoyer des images, utilisez des blocs de contenu structurés plutôt que de placer des URL d'image ou des chaînes Base64 directement dans du texte brut. D'autres blocs natifs, tels que tool_use, tool_result, thinking et document, sont acceptés pour les modèles qui les prennent en charge.

Exemples de blocs de contenu :

  • bloc texte : { "type": "text", "text": "Décris cette image" }
  • bloc image via URL : { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • bloc image via Base64 : { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensintegerrequis

Nombre maximum de jetons à générer. Requis : TokenLab n'ajoute pas de valeur par défaut. Le maximum utilisable dépend du modèle ; voir max_output_tokens dans ses détails du modèle. Une valeur élevée augmente le montant que TokenLab retient sur votre solde pendant l'exécution de la requête, et un solde insuffisant pour couvrir cette retenue renvoie une erreur 402.

systemstring | array

Prompt système sous forme de chaîne ou de tableau de blocs de contenu textuel, séparé du tableau messages.

temperaturenumber

Température d'échantillonnage. La prise en charge, les valeurs autorisées et la valeur par défaut dépendent du modèle sélectionné ; omettez ce champ pour utiliser sa valeur par défaut.

streambooleanpar défaut: false

Renvoie la réponse sous forme de flux d'événements envoyés par le serveur (SSE). Voir Streaming.

thinkingobject

Configuration native de réflexion (thinking), par exemple {"type":"enabled","budget_tokens":10000}. Les modes, budgets et combinaisons avec d'autres paramètres pris en charge dépendent du modèle sélectionné. Pour un modèle connu pour rejeter un budget manuel, TokenLab exécute {"type":"enabled"} en tant que réflexion adaptative et ignore budget_tokens.

toolsarray

Outils disponibles pour le modèle. La prise en charge dépend du modèle sélectionné.

tool_choiceobject

Objet natif de choix d'outil, par exemple {"type":"auto"}. Les types pris en charge dépendent du modèle sélectionné.

cache_controlobject

Marqueur de mise en cache du prompt, par exemple {"type":"ephemeral"} ; ajoutez "ttl": "1h" pour un cache d'une heure. Au niveau racine, cela active la mise en cache automatique. Vous pouvez également le définir sur les blocs system, les tools et les blocs de contenu. La prise en charge dépend du modèle ; les modèles qui le prennent en charge listent prompt-cache dans leurs capabilities.

top_pnumber

Paramètre d'échantillonnage Nucleus. Utilisez soit la température, soit top_p, mais pas les deux. La prise en charge dépend du modèle sélectionné.

top_kinteger

Échantillonne uniquement parmi les K meilleures options pour chaque jeton. La prise en charge dépend du modèle sélectionné.

stop_sequencesarray

Séquences d'arrêt personnalisées qui entraîneront l'arrêt de la génération par le modèle. Jusqu'à 8 191 entrées.

metadataobject

Métadonnées de la requête au format Anthropic. user_id est un identifiant opaque pour votre utilisateur final.

service_tierstring

Seuls auto et standard_only ont un effet. TokenLab facture uniquement le niveau standard et ignore toute autre valeur.

Réponse

idstring

Identifiant unique du message.

typestring

Toujours message.

rolestring

Toujours assistant.

contentarray

Tableau de blocs de contenu, tels que text, thinking ou tool_use.

modelstring

Modèle ayant produit la réponse.

stop_reasonstring

Raison pour laquelle la génération s'est arrêtée, telle que end_turn, max_tokens, stop_sequence ou tool_use. Un modèle peut renvoyer d'autres valeurs, par exemple refusal.

stop_sequencestring | null

La séquence d'arrêt qui a mis fin à la génération, ou null.

usageobject

Utilisation des jetons avec input_tokens et output_tokens. Lorsque le modèle rapporte des jetons de cache de prompt, usage contient également cache_creation_input_tokens et cache_read_input_tokens.

Chaque réponse contient l'ID de la requête dans les en-têtes request-id et X-Request-ID. Citez-le lorsque vous contactez le support.

Requête

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Réponse

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

Exemple d'entrée Vision

Pour les modèles Claude avec prise en charge de la vision, placez les images dans messages[].content sous forme de blocs d'image structurés.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Exemple de réflexion étendue (Extended Thinking)

Utilisez un modèle avec la capacité reasoning. Ajustez max_tokens et budget_tokens aux limites du modèle ; certains modèles nécessitent une configuration de réflexion différente.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this math problem..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Streaming

Définissez "stream": true pour recevoir les événements SSE d'Anthropic : message_start, content_block_start, content_block_delta, content_block_stop, message_delta et message_stop. L'utilisation des jetons arrive dans message_start et message_delta.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • Pendant que le modèle travaille, le flux peut contenir des lignes de commentaire SSE telles que : keep-alive. Les SDK les ignorent.
  • Le statut HTTP peut déjà être 200 lorsqu'une erreur survient. Une erreur survenant après le début du flux arrive sous la forme d'un événement event: error avec le même corps d'erreur que ci-dessous.

Erreurs

Les erreurs utilisent le format d'erreur Anthropic. request_id est l'ID de la requête TokenLab. Certaines erreurs ajoutent des champs tels que code et hint.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
Statuterror.typeCause typique
400invalid_request_errorUn champ manquant ou invalide, un modèle inconnu ou un modèle qui n'accepte pas le format Messages
401authentication_errorLa clé API est manquante ou invalide
402billing_errorLe solde ne peut pas couvrir la requête (error.code est insufficient_balance). Une clé API ayant atteint sa limite de dépenses reçoit également 402, avec error.code quota_exceeded et error.type rate_limit_error
403permission_errorLa clé API ne peut pas utiliser le modèle demandé, ou le compte est suspendu ou restreint
409conflict_errorUne nouvelle tentative avec la même Idempotency-Key. Voir Retry safely with an idempotency key
413request_too_largeL'entrée de la requête est trop volumineuse
429rate_limit_errorTrop de requêtes
500, 502, 503api_error ou overloaded_errorLa requête n'a pas pu être terminée, ou aucune route n'est disponible pour le moment. Réessayez plus tard
504timeout_errorLa requête a expiré

Interfaces associées

Autorisation

BearerAuth
AuthorizationBearer <token>

Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.

Emplacement: header

En-têtes

X-TokenLab-Delivery-Policy?string

Politique de livraison par requête. Remplace les valeurs par défaut de la clé API et de l'espace de travail. Tente automatiquement TokenLab Verified en premier et peut basculer une fois vers Official uniquement avant la sortie, l'acceptation de la requête ou la création de ressource persistante.

Valeurs possibles

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clé optionnelle qui empêche une seconde exécution de la même requête. Envoyez une nouvelle valeur unique, telle qu'un UUID, pour chaque requête, et conservez-la pour les tentatives après un délai d'attente. Une tentative avec la même clé ne s'exécute pas à nouveau : elle renvoie 409 avec idempotency_replay_unavailable, ou généralement idempotency_conflict si le corps a été modifié. Exception : lorsqu'un résultat sans streaming est terminé après la déconnexion du client, une tentative avec la même clé et le même corps dans les 24 heures renvoie ce résultat (jusqu'à 1 Mo) avec l'en-tête Idempotent-Replayed: true sans facturation supplémentaire. Une clé de plus de 255 caractères est ignorée, et la requête ne bénéficie alors d'aucune protection d'idempotence. Voir Réessayer en toute sécurité avec une clé d'idempotence.

Longueur1 <= length <= 255

Corps de la requête

application/json

Réponse

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json