Tool Integrations29 juin 2026Flatkey

Configuration du routeur API Claude Code : Base URL, modèles et journaux d'utilisation

La configuration d'un routeur API Claude Code est différente de la simple modification d'une Base URL du SDK OpenAI. Claude Code utilise le format de la passerelle Messages d'Anthropic, donc les vérifications importantes concernent la racine du routeur, l'en-tête d'identification, le nom du modèle que Claude Code enverra et les enregistrements d'utilisation qui prouvent que les requêtes aboutissent.

La configuration d'un routeur API Claude Code n'est pas la même chose que de changer une URL de base du SDK OpenAI. Claude Code utilise le format de la passerelle Anthropic Messages, donc les vérifications importantes sont la racine du routeur, l'en-tête d'authentification, le nom du modèle que Claude Code enverra, et les enregistrements d'utilisation qui prouvent que les requêtes atteignent le bon compte.

Ce guide fournit une configuration Flatkey orientée production pour les développeurs, les équipes produit IA, les créateurs d'automatisations, les ingénieurs de plateforme, les opérateurs financiers et les évaluateurs des achats. Il couvre l'URL de base, la pré-vérification à un jeton, les noms de modèles, la découverte de modèles par la passerelle, les journaux d'utilisation et les modes de défaillance avant que vous ne transfériez votre travail de codage quotidien vers un routeur API Claude Code.

Note sur la source : ceci a été vérifié le 29 juin 2026 par rapport à la documentation officielle des passerelles LLM de Claude Code, le guide de connexion à la passerelle Claude Code, la référence du protocole de la passerelle, la documentation de configuration des modèles, la documentation de surveillance, et les pages publiques actuelles de Flatkey. Aucune clé Flatkey spécifique à un compte n'a été utilisée pour un test de fumée en direct de Claude Code, donc les extraits ci-dessous sont des modèles à exécuter avec votre propre clé et un modèle approuvé.

Réponse rapide : configuration du routeur API Claude Code

Pour une configuration de routeur API Claude Code avec Flatkey, configurez Claude Code avec la racine du routeur Claude Code de Flatkey, une clé Flatkey, et un nom de modèle Claude exact que votre compte peut appeler. Ensuite, testez le point de terminaison Anthropic Messages avant d'ouvrir une longue session de codage.

Champ de configuration	Valeur ou vérification Flatkey	Pourquoi c'est important
URL de base	`https://router.flatkey.ai` pour le cas d'utilisation de Claude Code, sauf si votre compte Flatkey affiche une valeur plus récente spécifique à Claude Code	Claude Code ajoute `/v1/messages`. Ne collez pas une base SDK OpenAI se terminant par `/v1` à moins que votre test ne confirme que cela ne crée pas `/v1/v1/messages`.
Identifiant	`ANTHROPIC_AUTH_TOKEN` pour le routage par jeton porteur, ou `ANTHROPIC_API_KEY` lorsque la passerelle attend `x-api-key`	La documentation officielle de Claude Code associe chaque variable à un en-tête HTTP différent. Une clé valide dans la mauvaise variable renverra quand même une erreur `401`.
Pré-vérification du point de terminaison	`$ANTHROPIC_BASE_URL/v1/messages`	La page de tarification actuelle de Flatkey liste `/v1/messages` dans la carte des points de terminaison, qui est le chemin dont Claude Code a besoin pour le trafic Anthropic Messages.
Modèle	Utilisez un ID de modèle Claude exact ou un alias Claude Code qui se résout en une route Flatkey activée	La sélection du modèle est distincte du routage de l'URL de base. Le routeur décide où va le trafic ; Claude Code envoie toujours un nom de modèle.
Preuve d'utilisation	Vérifiez l'utilisation de Flatkey et la télémétrie de Claude Code après la première invite	Une sortie réussie ne suffit pas. Les équipes ont besoin de preuves concernant la clé, le modèle, l'horodatage, la session, le coût et les jetons.

Ceci est la version courte. Le reste de ce guide sur le routeur API Claude Code transforme ces champs en un manuel de configuration reproductible.

Ce que confirment les documents officiels de la passerelle Claude Code

La présentation officielle de la passerelle Claude Code définit une passerelle LLM comme un proxy entre Claude Code et un fournisseur de modèles. Claude Code envoie le trafic API à la passerelle, et la passerelle le transmet avec un identifiant de fournisseur contrôlé par l'organisation. La même page énumère les avantages de la passerelle tels que la centralisation des identifiants, le suivi de l'utilisation, le contrôle des coûts, les journaux d'audit et le changement de fournisseur.

La règle de l'URL de base est spécifique. Normalement, Claude Code envoie les requêtes à l'API d'Anthropic, mais la définition de ANTHROPIC_BASE_URL dirige ces requêtes vers la passerelle à la place. Le guide de connexion vérifie ensuite la route en effectuant une requête POST vers $ANTHROPIC_BASE_URL/v1/messages avec anthropic-version: 2023-06-01.

La référence du protocole de la passerelle ajoute les détails côté opérateur. Pour le format Anthropic Messages, une passerelle sélectionnée par ANTHROPIC_BASE_URL doit servir /v1/messages et optionnellement /v1/messages/count_tokens. Elle indique également que les réponses d'inférence doivent être diffusées en continu (streamed) car Claude Code consomme les événements envoyés par le serveur (server-sent events) à mesure qu'ils arrivent.

Pour un routeur API Claude Code, cela signifie que vous devez valider le chemin Anthropic Messages, et pas seulement un chemin de complétion de chat compatible avec OpenAI. Une route OpenAI peut fonctionner pour d'autres outils alors que Claude Code échouera toujours si /v1/messages, la diffusion en continu ou les en-têtes Anthropic requis sont manquants.

Valeurs Flatkey vérifiées pour cette configuration

La page d'accueil de Flatkey, vérifiée le 29 juin 2026, a pour titre One API gateway for production AI teams et une méta-description indiquant que Flatkey unifie l'accès aux modèles, le routage, la facturation, l'analyse de l'utilisation et les contrôles opérationnels. La même page d'accueil montre toujours des exemples de style OpenAI utilisant https://console.flatkey.ai/v1 et /v1/chat/completions, qui sont utiles pour les outils compatibles avec OpenAI mais ne correspondent pas au modèle d'URL de base de Claude Code.

La page actuelle du cas d'utilisation de Claude Code par Flatkey indique que Claude Code est configuré avec https://router.flatkey.ai et une clé API Flatkey. Elle indique également aux utilisateurs de créer ou de copier la clé sur https://console.flatkey.ai/keys avant d'exécuter le programme d'installation. Utilisez cette racine de routeur spécifique à Claude Code pour la configuration manuelle ci-dessous, à moins que votre compte Flatkey ne vous fournisse une valeur plus récente.

La page de tarification de Flatkey, consultée le 29 juin 2026, publie les prix rendus côté serveur pour 635 modèles d'IA de 23 fournisseurs. Sa carte de points de terminaison inclut /v1/messages, /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/video/generations et /v1beta/models/{model}:generateContent. Cet article considère cela comme une preuve publique datée de la couverture des points de terminaison, et non comme une garantie que chaque compte peut appeler chaque modèle.

Configuration étape par étape avec Flatkey

Créez ou choisissez une clé Flatkey. Utilisez une clé appartenant à la bonne personne, équipe ou environnement. Ne l'incluez pas dans les captures d'écran, les invites, les dépôts et les commentaires de problèmes.
Commencez par des exports shell. Ne rendez pas les paramètres persistants tant que le test préliminaire (preflight) à un seul jeton ne fonctionne pas.
Utilisez la racine du routeur Claude Code. Pour la page actuelle de Claude Code par Flatkey, cette valeur est https://router.flatkey.ai.
Choisissez la variable d'identification. Utilisez ANTHROPIC_AUTH_TOKEN lorsque la clé doit être envoyée en tant que Authorization: Bearer. Utilisez ANTHROPIC_API_KEY uniquement lorsque la passerelle attend x-api-key.
Définissez un modèle pour le premier test. Utilisez un ID de modèle Claude actuel activé pour votre compte Flatkey. Si le modèle n'est pas visible dans le sélecteur de Claude Code, utilisez la découverte de la passerelle ou ajoutez une option de modèle personnalisé après que le test préliminaire fonctionne.
Exécutez le test préliminaire (preflight) curl. Une requête à un seul jeton sépare le routage Flatkey de l'état de l'interface utilisateur de Claude Code.
Démarrez Claude Code depuis le même shell. Cela permet à l'interface de ligne de commande (CLI) d'hériter des variables que vous venez de tester.
Exécutez /status. Confirmez que la ligne de l'URL de base Anthropic affiche le routeur Flatkey et que la ligne des informations d'identification nomme la variable que vous avez définie.
Envoyez une petite invite. Vérifiez ensuite l'utilisation de Flatkey et toute télémétrie Claude Code que vous avez activée.

Configuration du shell

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_AUTH_TOKEN="fk_replace_with_your_flatkey_key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

Si les instructions de votre passerelle indiquent explicitement x-api-key, remplacez ANTHROPIC_AUTH_TOKEN par ANTHROPIC_API_KEY et mettez à jour l'en-tête du test préliminaire. Ne définissez pas les deux pour le premier test ; des sources d'identification mixtes rendent les échecs plus difficiles à isoler.

Paramètres persistants après la réussite du test

Une fois que le test shell fonctionne, vous pouvez placer les mêmes variables dans le bloc env de ~/.claude/settings.json. Ne mettez pas d'informations d'identification dans un fichier .claude/settings.json d'un projet versionné (commit).

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_AUTH_TOKEN": "fk_replace_with_your_flatkey_key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

Test préliminaire (preflight) de la route Messages avant de lancer Claude Code

La vérification la plus rapide du routeur API Claude Code est une requête Messages à un seul jeton. Si cela échoue, corrigez la clé Flatkey, l'URL de base, le chemin réseau ou le modèle avant de modifier les paramètres de Claude Code.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1,
    "messages": [
      {"role": "user", "content": "."}
    ]
  }'

Une réponse JSON qui commence par un ID de message et inclut un champ de contenu signifie que la route et les informations d'identification fonctionnent. La documentation officielle note également qu'une erreur de modèle inconnu prouve tout de même que la passerelle a authentifié la requête avant de rejeter le nom du modèle. Un code 401 signifie que les informations d'identification ont été rejetées ou envoyées dans le mauvais en-tête.

Surveillez attentivement l'URL résolue. Avec ANTHROPIC_BASE_URL=https://router.flatkey.ai, le test atteint https://router.flatkey.ai/v1/messages. Si votre commande crée /v1/v1/messages, vous avez copié une URL de base de SDK client dans un champ de passerelle Claude Code.

Noms des modèles : alias, découverte et entrées personnalisées

Les noms de modèles sont la deuxième source courante d'échecs du routeur API Claude Code. L'URL de base envoie le trafic à Flatkey, mais Claude Code a toujours besoin d'une valeur de modèle à envoyer dans la requête.

La documentation sur la configuration des modèles indique que Claude Code prend en charge les paramètres de modèles intégrés tels que default, best, sonnet, opus, haiku, et les variantes à contexte long comme sonnet[1m] et opus[1m]. La même documentation indique que ANTHROPIC_MODEL ne s'applique qu'à la session que vous lancez avec, tandis que /model peut enregistrer un choix interactif pour les sessions ultérieures.

Pour une route Flatkey, la règle de sécurité est de commencer avec un ID de modèle Claude complet que Flatkey a activé pour votre clé, puis de décider de l'exposer ou non dans le sélecteur. Ne présumez pas qu'un nom de famille générique, une étiquette marketing ou un titre de ligne de fournisseur soit accepté comme ID de modèle pour la requête.

Besoin de configuration du modèle	Mécanisme Claude Code	Vérification Flatkey
Test sur une seule session	`ANTHROPIC_MODEL` ou `claude --model`	Utilisez un ID de modèle Claude compatible avec Flatkey et limitez la taille du test.
Sélection interactive	`/model`	Confirmez que le nom sélectionné est l'ID réel attendu par Flatkey.
Liste de modèles fournie par la passerelle	`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`	La passerelle doit servir `/v1/models` rapidement à l'URL de base configurée.
Saisie manuelle dans le sélecteur	`ANTHROPIC_CUSTOM_MODEL_OPTION`	Utilisez cette option lorsque la découverte est désactivée ou ne renvoie pas le modèle dont vous avez besoin.
Solution de repli en cas d'indisponibilité	`--fallback-model` ou `fallbackModel`	La solution de repli ne corrige pas les erreurs d'authentification, de facturation, de limite de débit, de taille de requête ou de transport.

Découverte de modèles par la passerelle

Claude Code peut interroger le point de terminaison /v1/models d'une passerelle au démarrage lorsque ANTHROPIC_BASE_URL pointe vers une passerelle Anthropic Messages et que la découverte est activée. La documentation du protocole indique que la requête est GET /v1/models?limit=1000 avec un délai d'attente de 3 secondes, et que Claude Code lit l'id ainsi que le display_name optionnel de la réponse.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude --debug

La découverte est désactivée par défaut afin qu'une clé partagée n'expose pas tous les modèles accessibles à chaque utilisateur. Si la découverte échoue, Claude Code se rabat sur le sélecteur mis en cache ou intégré. Si votre compte Flatkey sert un modèle sous un alias que la découverte n'affiche pas, ajoutez plutôt une option personnalisée.

Option de modèle personnalisé

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet via Flatkey"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Claude model routed through the Flatkey API router"

L'option de modèle personnalisé ignore la validation côté client pour cet ID de modèle, ce qui la rend utile pour un pilote contrôlé. Elle ne remplace pas la requête preflight. Si une liste d'autorisation d'organisation est active, incluez-y également l'ID du modèle personnalisé.

Journaux d'utilisation : que vérifier après la première invite

Une configuration fiable du routeur API Claude Code se termine par une preuve d'utilisation, et pas seulement par une réponse réussie. Le positionnement public de Flatkey indique qu'il unifie la facturation, l'analyse de l'utilisation et les contrôles opérationnels ; la documentation de la passerelle Claude Code présente également le suivi de l'utilisation et le contrôle des coûts comme des avantages de la passerelle. Utilisez les deux couches intentionnellement.

Source du journal	Éléments à inspecter	Pourquoi c'est important
Utilisation de Flatkey	Propriétaire de la clé, horodatage, modèle, famille de points de terminaison, utilisation des jetons et enregistrement des coûts si disponible	Confirme que la requête a atteint le compte de passerelle prévu et peut être rapprochée par les opérations ou la finance.
Claude Code `/status`	URL de base Anthropic et source d'identification active	Confirme que la session en cours utilise la route Flatkey au lieu d'une connexion claude.ai enregistrée.
Métriques OpenTelemetry	`claude_code.cost.usage`, `claude_code.token.usage`, nombre de sessions, temps d'activité et point d'entrée	Crée une observabilité au niveau de l'équipe pour les sessions Claude Code.
Journaux/événements OpenTelemetry	Événements d'invite, résultats d'outils, erreurs d'API et champs de coût lorsqu'ils sont configurés	Aide à déboguer les échecs au niveau de la requête, mais doit être contrôlé car les journaux détaillés peuvent exposer du contenu sensible.
En-têtes de la passerelle	`x-claude-code-session-id`, ID d'agent et en-têtes de routage personnalisés	Permet de regrouper les requêtes par session ou sous-agent sans analyser l'intégralité du corps des requêtes.

Pour la télémétrie de Claude Code, n'activez OpenTelemetry qu'avec un paramètre de confidentialité délibéré. La documentation de surveillance indique que le texte de l'invite est expurgé par défaut, tandis que des paramètres tels que OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 et OTEL_LOG_RAW_API_BODIES ajoutent des détails sensibles. N'incluez pas la journalisation brute du corps des requêtes dans la configuration par défaut des développeurs, à moins que votre revue de sécurité ne l'approuve.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Utilisez OTEL_RESOURCE_ATTRIBUTES pour les champs de propriété à faible cardinalité tels que le département, l'ID d'équipe ou le centre de coûts. Évitez les noms de projet ou les ID de ticket saisis par l'utilisateur comme étiquettes, à moins que votre backend d'observabilité ne puisse gérer la cardinalité et l'impact sur la confidentialité.

Modes d'échec à déboguer en premier

Symptôme	Cause probable	Première solution
`401` ou jeton invalide	La clé a été rejetée, a expiré, a été copiée dans la mauvaise variable ou a été envoyée dans un en-tête que la passerelle ne lit pas.	Basculez entre `ANTHROPIC_AUTH_TOKEN` et `ANTHROPIC_API_KEY` uniquement après avoir confirmé quel en-tête Flatkey attend.
Connexion refusée ou délai d'attente dépassé	URL de base incorrecte, chemin réseau bloqué, problème de VPN ou point de terminaison de routeur non accessible depuis la machine du développeur.	Exécutez la pré-vérification curl et vérifiez l'URL avec les instructions de votre compte Flatkey.
Réponse malformée avec HTTP 200	Un proxy ou une page de connexion a renvoyé du HTML au lieu du JSON de l'API.	Inspectez le corps de la réponse de pré-vérification et corrigez la route de la passerelle qui renvoie autre chose que du JSON.
`400` nommant `context_management` ou des champs supplémentaires	La passerelle a transmis des champs de requête au format Anthropic à un service en amont qui les rejette.	Transmettez correctement la paire en-tête/corps bêta ou définissez `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` comme atténuation temporaire.
`400` nommant `thinking` ou `adaptive`	La version du modèle en amont n'accepte pas le raisonnement adaptatif demandé pour les modèles Claude plus récents.	Mettez à niveau la route en amont ou utilisez l'indicateur de désactivation du raisonnement adaptatif documenté uniquement là où il s'applique.
Modèle manquant dans `/model`	Le modèle ne se trouve pas dans le sélecteur intégré de Claude Code et la découverte est désactivée ou échoue.	Activez la découverte de modèles par la passerelle ou ajoutez `ANTHROPIC_CUSTOM_MODEL_OPTION`.
Claude Code demande une connexion après la réussite de curl	La CLI n'a pas reçu d'identifiant là où la configuration initiale peut le lire.	Définissez l'identifiant dans le shell, `~/.claude/settings.json`, ou les paramètres gérés avant le démarrage.
L'utilisation ne peut pas être rapprochée	La configuration manque le propriétaire de la clé, le nom du modèle, l'environnement, l'ID de session ou les étiquettes de télémétrie.	Ajoutez une ligne au guide opérationnel avant que d'autres développeurs n'utilisent la route.

Check-list de production pour les équipes

Avant de standardiser un routeur API Claude Code au sein d'une équipe, consignez les faits opérationnels dont un futur incident ou un examen financier aura besoin.

Élément de la check-list	À consigner
URL de base	La valeur exacte enregistrée dans le shell, les paramètres gérés, les paramètres de VS Code, la CI ou la configuration du SDK de l'agent.
Source des identifiants	Propriétaire de la clé Flatkey, environnement, propriétaire de la rotation, et si elle est statique ou provient d'un `apiKeyHelper`.
Noms des modèles	ID du modèle demandé, étiquette du sélecteur, chaîne de secours, règle de la liste d'autorisation et date du test.
Preuve du point de terminaison	Résultat `/v1/messages` à un jeton, horodatage de la requête et tout ID de requête renvoyé par la passerelle.
Examen de l'utilisation	Vue d'utilisation de Flatkey, backend de télémétrie de Claude Code, étiquettes et propriétaire du tableau de bord.
Portes de confidentialité	Indique si les invites, les détails des outils, les corps bruts de l'API ou le contenu des outils sont autorisés dans la télémétrie.
Restauration	Connexion ou chemin du fournisseur Claude Code précédent, modèle précédent et qui peut annuler la définition des variables de la passerelle.

Chemin de migration interne

Si Flatkey devient la route partagée pour plusieurs outils de développement, maintenez la configuration de Claude Code alignée avec le reste du cluster d'intégration. Utilisez le guide de migration de l'API compatible OpenAI pour les modèles d'URL de base du SDK, mais n'oubliez pas que Claude Code utilise la route Anthropic Messages au lieu de /v1/chat/completions.

Pour la configuration du client de bureau, comparez le guide de configuration de l'API Cherry Studio. Pour les modèles de routage sur la machine du développeur adjacents à Claude Code, consultez la configuration cc-switch de Claude Code. Une fois que la première invite fonctionne, examinez les tarifs des modèles Flatkey, puis obtenez une clé pour tout environnement supplémentaire nécessitant une limite d'identifiants distincte.

FAQ

Quelle URL de base dois-je utiliser pour un routeur API Claude Code avec Flatkey ?

Utilisez la racine du routeur Flatkey spécifique à Claude Code indiquée pour votre compte. Le 29 juin 2026, la page du cas d'utilisation de Claude Code de Flatkey indiquait que Claude Code est configuré avec https://router.flatkey.ai. La pré-vérification doit atteindre exactement un chemin /v1/messages.

Dois-je utiliser `ANTHROPIC_AUTH_TOKEN` ou `ANTHROPIC_API_KEY` ?

Utilisez ANTHROPIC_AUTH_TOKEN lorsque la passerelle attend un jeton de porteur dans l'en-tête Authorization. Utilisez ANTHROPIC_API_KEY lorsqu'elle attend x-api-key. Si vous avez deviné et que vous obtenez 401, changez de variable et testez à nouveau.

Puis-je utiliser une URL de base Flatkey compatible avec OpenAI pour Claude Code ?

Pas directement en tant que champ copié. Les outils compatibles avec OpenAI utilisent souvent une URL de base se terminant par /v1, tandis que Claude Code ajoute /v1/messages à ANTHROPIC_BASE_URL. Utilisez la valeur du routeur Claude Code de Flatkey et vérifiez l'URL finale.

Comment ajouter des modèles Flatkey au sélecteur de modèles de Claude Code ?

Activez CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 lorsque la passerelle dessert /v1/models, ou ajoutez une ligne de sélection manuelle avec ANTHROPIC_CUSTOM_MODEL_OPTION. Dans les deux cas, confirmez que l'ID de modèle exact est activé pour votre clé Flatkey.

Quels journaux d'utilisation dois-je vérifier après la configuration ?

Vérifiez l'utilisation de Flatkey pour la clé, le modèle, la famille de points de terminaison, l'horodatage, les jetons et le coût, le cas échéant. Utilisez également /status de Claude Code et les métriques OpenTelemetry telles que claude_code.cost.usage et claude_code.token.usage lorsque la télémétrie de l'organisation est activée.

Conclusion

Une configuration fiable du routeur API Claude Code repose sur quatre points de preuve : l'URL de base de Flatkey Claude Code, l'en-tête d'identification correct, un nom de modèle testé et une piste d'utilisation que les équipes financières et de plateforme peuvent examiner. Commencez par une pré-vérification /v1/messages à un jeton, confirmez /status, puis mettez la route à l'échelle uniquement après que les journaux et la restauration ont été documentés. Lorsque vous êtes prêt à router Claude Code via une passerelle partagée, obtenez une clé et testez d'abord le plus petit prompt.