API Claude Fable 5.1 : Guide d'utilisation étape par étape avec Apidog

Claude Fable 5.1 a été livré le 1er septembre 2026. Son ID API exact est claude-fable-5-1, sans suffixe de date. Il coûte 10 $ par million de tokens d'entrée et 50 $ par million de tokens de sortie, comme Fable 5, tandis que les lectures de cache passent à 0,25 $ par million.

Essayez Apidog dès aujourd'hui

Ce guide couvre l'intégration complète : clé API, première requête, effort, streaming, outils sans tool_choice forcé, replis après refus, mises à jour de progression et vérification du cache. Chaque exemple utilise HTTP et JSON, afin que vous puissiez le tester et le déboguer dans Apidog avant de l'intégrer à votre application.

Pour une migration depuis Fable 5 ou Opus 5, consultez le guide de migration complet. Pour découvrir le modèle, commencez par ce qu'est Claude Fable 5.1.

Avant votre premier appel : trois causes de 400

1. La réflexion est adaptative

Fable 5.1 active toujours une réflexion adaptative. Omettez thinking ou envoyez :

{"type": "adaptive"}

Ces configurations renvoient 400 :

{"type": "disabled"}

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

Si vous migrez depuis Opus 5, où disabled était accepté avec un effort high ou inférieur, supprimez ce champ et contrôlez plutôt les dépenses avec output_config.effort.

2. L'utilisation forcée des outils n'est plus disponible

Ces valeurs renvoient une erreur :

{"type": "any"}

{"type": "tool", "name": "..."}

Conservez tool_choice à auto et utilisez l'approche décrite à l'étape 5.

3. La rétention des données doit être de 30 jours

Fable 5.1 est un modèle couvert par cette exigence. Une organisation ou un espace de travail configuré avec une rétention nulle renvoie 400 invalid_request_error, même si le corps de la requête est valide.

Consultez la documentation Nouveautés de Claude Fable 5.1 pour les détails.

Étape 1 : obtenir une clé API

Connectez-vous à la console Claude, ouvrez les clés API dans les paramètres de votre organisation, puis créez une clé. Copiez-la immédiatement : elle ne sera plus lisible ensuite.

Stockez-la dans une variable d'environnement plutôt que dans le code :

export ANTHROPIC_API_KEY="sk-ant-..."

Dans Apidog, créez une variable d'environnement ANTHROPIC_API_KEY et référencez-la avec {{ANTHROPIC_API_KEY}} dans l'en-tête. La clé ne sera ainsi jamais enregistrée dans le corps d'une requête.

Étape 2 : envoyer une première requête

Créez une requête POST vers https://api.anthropic.com/v1/messages avec ces en-têtes :

• x-api-key
• anthropic-version: 2023-06-01
• content-type: application/json

curl https://api.anthropic.com/v1/messages \
  -H "x-[REDACTED CREDENTIAL]_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 16000,
    "messages": [
      {"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}
    ]
  }'

Le même appel avec le SDK Python officiel :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}],
)

if response.stop_reason == "refusal":
    print("declined:", response.stop_details.category if response.stop_details else None)
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)

Vérifiez toujours stop_reason avant de lire content. Un refus classifié renvoie HTTP 200, avec un tableau de contenu vide.

Prévoyez également une valeur généreuse pour max_tokens. Cette limite couvre les tokens de réflexion et de réponse, alors que la réflexion est toujours active.

La réponse contient un bloc thinking vide lorsque display vaut omitted. C'est normal : renvoyez ce bloc inchangé au tour suivant.

Étape 3 : contrôler le coût avec effort

Le paramètre effort se trouve dans output_config, pas au niveau supérieur. Il accepte low, medium, high, xhigh et max. La valeur par défaut est high.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Summarize this changelog in five bullets."}]
}

Commencez par high, puis comparez les autres niveaux avec vos propres évaluations. Les niveaux ne correspondent pas à la même quantité de réflexion d'un modèle à l'autre, même si leur nom est identique.

Selon Anthropic :

• medium offre un comportement proche de Fable 5 pour un coût inférieur ;
• low peut être compétitif avec Opus et Sonnet sur le coût par tâche ;
• avec low, le modèle appelle moins souvent les outils de recherche et de récupération et s'appuie davantage sur sa mémoire ;
• avec xhigh et max, il peut rédiger un document long pendant sa réflexion avant de le réécrire : augmentez donc max_tokens en conséquence.

Modifier l'effort en cours de conversation

Sur Fable 5, modifier l'effort entre deux requêtes supprimait le préfixe mis en cache. Sur Fable 5.1, un message system vide avec output_config modifie l'effort à partir du tour utilisateur suivant sans invalider le cache.

Cette fonctionnalité nécessite l'en-tête bêta mid-conversation-output-config-2026-07-01 et l'espace de noms client.beta.messages :

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    output_config={"effort": "high"},
    betas=["mid-conversation-output-config-2026-07-01"],
    messages=[
        {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
        {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
)

La baisse de l'effort est fiable. Pour l'augmenter, privilégiez les grands écarts, par exemple de low à xhigh.

Consultez le guide du paramètre d'effort pour Opus 5 et la documentation du paramètre d'effort.

Étape 4 : diffuser la réponse

À effort élevé, une tâche difficile peut prendre plusieurs minutes. Diffusez toute réponse potentiellement longue. Le SDK exige le streaming lorsque max_tokens approche la limite de 128 000 tokens, afin d'éviter les délais d'attente HTTP.

with client.messages.stream(
    model="claude-fable-5-1",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a test plan for a rate-limited public API."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

print(final.stop_reason, final.usage.output_tokens)

Dans Apidog, le streaming affiche la réponse au fur et à mesure. Vous pouvez ainsi mesurer le temps passé à réfléchir avant l'arrivée du premier token de texte.

Étape 5 : utiliser les outils sans forcer leur appel

La définition des outils reste identique à celle de Fable 5. En revanche, ne forcez plus l'appel avec tool_choice: {"type": "tool", ...} : Fable 5.1 renvoie 400, car un appel forcé pourrait contourner la réflexion et pousser le raisonnement dans les arguments.

Utilisez plutôt :

1. tool_choice: {"type": "auto"} ;
2. une instruction qui nomme explicitement l'outil ;
3. strict: true ;
4. additionalProperties: false dans le schéma.

record_summary_tool = {
    "name": "record_summary",
    "description": "Record the structured summary of the document.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result."}],
)

Si le seul objectif de l'appel forcé était d'obtenir du JSON, utilisez les sorties structurées avec output_config.format.

Si l'application exige un outil spécifique au tour actuel d'une conversation multi-tours, ajoutez après le dernier tour utilisateur un message system qui nomme l'outil et indique que l'appel est obligatoire. Conservez ensuite ce message dans l'historique. tool_choice: {"type": "none"} reste disponible pour les tours qui ne doivent appeler aucun outil.

La boucle agentique ne change pas :

1. lorsque stop_reason vaut tool_use, exécutez chaque bloc tool_use ;
2. renvoyez tous les blocs tool_result dans un seul message utilisateur ;
3. ajoutez le tour assistant exactement tel qu'il a été renvoyé, y compris les blocs de réflexion.

Cette dernière règle est particulièrement importante avec Fable 5.1. Consultez le guide de la réflexion préservée.

Dans les longues boucles, Fable 5.1 peut effectuer un appel d'outil par tour lorsqu'il pourrait en regrouper plusieurs. Après chaque résultat d'outil, ajoutez cette instruction comme message système limité au tour :

Listez d'abord en privé ce dont vous avez besoin ensuite ; puis demandez chaque élément qui ne dépend pas du résultat d'un autre dans cette seule réponse.

Utilisez clear_at: "next_user_message" avec l'en-tête bêta mid-conversation-system-clear-at-2026-08-21, et conservez les copies précédentes.

Étape 6 : gérer les refus avec des replis

Fable 5.1 utilise des classificateurs de sécurité. Une requête refusée renvoie HTTP 200 avec :

• stop_reason: "refusal" ;
• stop_details.category égal à cyber, bio, frontier_llm, reasoning_extraction ou general_harms.

Un refus qui intervient avant toute sortie n'est pas facturé.

La forme la plus simple du repli côté serveur utilise fallbacks: "default" et l'en-tête bêta server-side-fallback-2026-07-01 :

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
    messages=[{"role": "user", "content": "Audit this authentication middleware for logic bugs."}],
)

fallback_ran = any(
    entry.type == "fallback_message" for entry in (response.usage.iterations or [])
)
if fallback_ran and response.stop_reason != "refusal":
    print("served by", response.model)

Pour Fable 5.1, les cibles autorisées sont claude-opus-4-8 et claude-opus-5. Le modèle effectivement utilisé figure dans le champ supérieur model, et un bloc de contenu fallback marque le transfert.

Conservez ce bloc à la même position lorsque vous renvoyez le tour.

fallbacks n'est pas disponible avec l'API Batches, Bedrock, Google Cloud ou Foundry. Sur ces plateformes, enregistrez plutôt BetaRefusalFallbackMiddleware du SDK côté client. Le guide de gestion des refus couvre la facturation, le routage persistant et la nouvelle tentative manuelle avec crédit de repli.

Étape 7 : afficher la progression pendant les longs tours

Entre les appels d'outils, Fable 5.1 peut produire de courtes mises à jour sur ce qu'il a trouvé et ce qu'il fera ensuite. Chaque mise à jour arrive dans son propre bloc thinking, juste avant l'appel d'outil.

Par défaut, ces blocs sont vides. Pour afficher leur texte sans exposer le raisonnement, utilisez display: "updates" avec l'en-tête bêta thinking-display-updates-2026-08-18 :

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": {"type": "adaptive", "display": "updates"},
  "tools": [...],
  "messages": [{"role": "user", "content": "Review the PRs open against our billing service."}]
}

Affichez chaque bloc thinking dont le texte n'est pas vide comme une ligne d'état. Fable 5.1 en produit moins que Fable 5 ; si votre interface dépend de cette narration, supprimez aussi les invites demandant au modèle de conserver les résultats pour la réponse finale.

Étape 8 : vérifier le tarif des lectures de cache

Le cache d'invites est l'endroit où la baisse de prix se vérifie. Placez cache_control sur le préfixe stable et inspectez l'objet usage :

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    system=[{"type": "text", "text": LONG_STABLE_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "Which endpoints in the spec lack an error schema?"}],
)
u = response.usage
print(u.input_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens)

Au premier envoi, cache_creation_input_tokens doit être non nul. Ces tokens sont facturés 12,50 $ par million avec un TTL de cinq minutes.

Lors d'un deuxième envoi identique dans les cinq minutes, cache_read_input_tokens doit être non nul. Ils sont facturés 0,25 $ par million sur Fable 5.1.

Si la valeur reste à zéro, le préfixe change probablement à chaque requête. Vérifiez notamment :

• les horodatages dans l'invite système ;
• le JSON non trié ;
• les tableaux d'outils variables.

Le préfixe minimal pouvant être mis en cache est de 512 tokens.

Un échec de cache coûte 40 fois plus cher qu'une réussite : gardez donc le cache chaud. L'effort par message et les messages système limités au tour permettent notamment de modifier une session sans la réinitialiser.

Attention : reconstruire system ou modifier les tours précédents réinitialise le cache et invalide désormais aussi les blocs de réflexion. Une discipline d'ajout uniquement protège donc les deux mécanismes.

Consultez la documentation de la mise en cache des invites et l'analyse des prix.

Tester tout le flux dans Apidog

Enregistrez chaque étape dans une collection Apidog :

• première requête ;
• variantes d'effort ;
• streaming ;
• boucle d'outils ;
• repli ;
• vérification du cache.

Utilisez des variables d'environnement pour ANTHROPIC_API_KEY et model. Vous pourrez ainsi basculer toute la collection de claude-fable-5 à claude-fable-5-1 en modifiant une seule variable.

Ajoutez ensuite ces assertions :

• stop_reason n'est pas refusal pour les invites de test bénignes ;
• usage.cache_read_input_tokens est supérieur à zéro lors de la deuxième requête ;
• aucune entrée input_transformations n'a reason: "prefix_binding_mismatch" lorsque vous utilisez l'en-tête de liaison de la réflexion.

Exécutez la collection avant et après chaque modification du harnais. Vous pouvez télécharger Apidog pour la configurer ; la même collection peut servir de vérification CI via l'interface CLI d'Apidog.

Erreurs et pièges courants

• 400 tool_choice: type "tool" and "any" are not supported for this model
  
  Utilisez auto, une instruction explicite et strict: true.

• 400 avec thinking: {"type": "disabled"}
  
  Supprimez thinking et réduisez plutôt effort.

• 400 invalid_request_error avec un corps valide
  
  Vérifiez la rétention de 30 jours de l'organisation ou de l'espace de travail.

• 400 Invalid signature in thinking block. The block is bound to a different conversation.
  
  Un tour précédent, l'invite système ou le tableau d'outils a été modifié. Consultez le guide de la réflexion préservée.

• Texte de réflexion vide
  
  C'est attendu avec display: "omitted". Utilisez summarized ou updates pour afficher du contenu.

• Lectures de cache nulles
  
  Le préfixe est probablement volatile. Recherchez les horodatages et les objets non triés.

• Échec de validation du Tier Prioritaire
  
  Fable 5.1 ne prend pas en charge le Tier Prioritaire, contrairement à Fable 5.

FAQ

Quel est l'ID du modèle Claude Fable 5.1 ?

Sur l'API Claude, utilisez claude-fable-5-1.

Sur Amazon Bedrock, utilisez anthropic.claude-fable-5-1. Google Cloud, Microsoft Foundry et Claude Platform sur AWS utilisent également claude-fable-5-1.

Un en-tête bêta est-il nécessaire ?

Non. Le modèle, la réflexion adaptative, l'effort, les outils et le cache fonctionnent avec l'en-tête standard :

anthropic-version: 2023-06-01

Les en-têtes bêta sont uniquement nécessaires pour :

• l'effort par message ;
• les messages système limités au tour ;
• les mises à jour de progression ;
• les replis côté serveur ;
• les contrôles de liaison de réflexion.

Puis-je forcer un appel d'outil ?

Non. tool_choice: {"type": "any"} et tool_choice: {"type": "tool", ...} renvoient 400.

Utilisez auto, nommez l'outil dans l'invite et définissez strict: true pour valider les arguments selon le schéma. Pour extraire du JSON, préférez les sorties structurées.

Quelle est la sortie maximale ?

L'API Messages accepte jusqu'à 128 000 tokens. Utilisez le streaming pour les sorties volumineuses.

La version bêta de l'API Batch, limitée à 300 000 tokens, n'est pas listée pour Fable 5.1.

Comment vérifier les lectures de cache moins chères ?

Répétez une requête avec le même préfixe, puis inspectez :

response.usage.cache_read_input_tokens

Ces tokens coûtent 0,25 $ par million sur Fable 5.1, contre 1 $ sur Fable 5 et 0,50 $ sur Opus 5.

Le guide de l'API Fable 5 reste-t-il valable ?

En grande partie. Le guide de l'API Fable 5 couvre le même point d'accès, mais ses exemples d'utilisation forcée des outils renvoient désormais 400. Il est également antérieur à l'effort par message et aux mises à jour de progression.