Ce dont vous avez besoin
- Une clé API depuis la page clé. Inscrivez-vous avec Google ou e-mail et mot de passe, puis réclamez le crédit d'essai de 0,50 $ en un clic.
- Python 3.9 ou version ultérieure, pour installer le proxy.
- Claude Code installé et fonctionnant sur votre machine.
Pourquoi un proxy ? Claude Code utilise le format Messages d'Anthropic, et notre API utilise le format Chat Completions d'OpenAI avec l'ID de modèle uncensored. Le proxy fait la traduction entre les deux. Si vous voulez d'abord comprendre le principe, lisez le guide de dépannage du proxy. Le modèle est un modèle à poids ouverts, pas Claude, donc attendez-vous à un comportement différent sur les tâches multi-étapes complexes.
Étape 1 : installer le proxy
Utilisez un environnement virtuel afin que les dépendances du proxy restent séparées de vos projets :
python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'
LiteLLM est un logiciel open source tiers. Les commandes et les clés de configuration ci-dessous correspondent à sa documentation publique au moment de la rédaction, mais vérifiez sa documentation actuelle si un indicateur a changé.
Étape 2 : rédiger la configuration
Créez config.yaml. Le model_name est le nom envoyé par le client. Le bloc litellm_params indique où le transférer. Le préfixe openai/ indique à LiteLLM de parler à un serveur compatible OpenAI.
cat > config.yaml <<'EOF'
model_list:
- model_name: claude-sonnet
litellm_params:
model: openai/uncensored
api_base: https://api.claudecodeproxyapi.com/v1
api_key: os.environ/UPSTREAM_KEY
EOF
L'alias claude-sonnet est un exemple, pas une obligation. Claude Code peut envoyer plusieurs noms de modèles différents, par exemple un modèle principal et un plus petit pour les tâches en arrière-plan. Ajoutez une entrée model_list par nom que vous voyez dans le journal du proxy, toutes pointant vers le même amont. Pointer tous les alias vers uncensored est correct, car il n'y a qu'un seul modèle.
La clé est lue depuis une variable d'environnement afin qu'elle n'apparaisse jamais dans un fichier que vous pourriez valider.
Étape 3 : démarrer le proxy
export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000
Laissez ce terminal ouvert. Vous devriez voir le serveur écouter sur le port 4000. Maintenant, vérifiez le chemin amont du côté du proxy avec une requête de test au format Anthropic, qui est ce que Claude Code enverra :
curl http://localhost:4000/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: sk-local-anything" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet",
"max_tokens": 200,
"messages": [{"role": "user", "content": "Reply with the word ready."}]
}'
Une réponse JSON dont le contenu inclut le mot « ready » signifie que la traduction fonctionne de bout en bout : format Anthropic entrant, format OpenAI vers https://api.claudecodeproxyapi.com/v1, et retour. Si vous définissez une clé maître dans la configuration LiteLLM, utilisez-la à la place de sk-local-anything.
Étape 4 : pointer Claude Code vers le proxy
Claude Code lit son adresse API et son jeton depuis des variables d'environnement. Définissez-les dans le shell où vous démarrez l'interface en ligne de commande :
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude
Utilisez l'adresse du proxy sans suffixe /v1 ici, car l'interface CLI ajoute son propre chemin. Le token doit seulement satisfaire le proxy, car la véritable clé amont est celle que vous avez exportée en tant que UPSTREAM_KEY. Si vous utilisez le fichier de paramètres de l'interface CLI pour les valeurs d'environnement au lieu du shell, mettez les mêmes trois noms ici. Les noms de variables d'environnement pour Claude Code peuvent changer entre les versions, donc vérifiez-les par rapport à la documentation actuelle de Claude Code si quelque chose est ignoré.
Étape 5 : lancer une première tâche et surveiller le journal
Commencez petit. Demandez à l'interface CLI d'expliquer un fichier ou d'ajouter un commentaire à une fonction. Dans le terminal du proxy, vous devriez voir une requête par étape. Notez chaque nom de modèle qui apparaît ; si l'un d'eux n'est pas dans votre model_list, le proxy répondra avec une erreur, alors ajoutez-le et redémarrez.
L'appel de fonctions est important ici, car l'interface CLI lit des fichiers et modifie du code via des outils. L'API prend en charge tools, tool_choice et le streaming de tool_calls, et le proxy les convertit. Une adhésion plus faible à un schéma d'outil se manifeste par une modification échouée ou une étape répétée. Lorsque cela se produit, réduisez la tâche et réessayez avant de décider que la configuration est cassée.
La fenêtre de contexte est de 100 000 tokens, prompt et complétion confondus. Les longues sessions qui dépassent cette limite échoueront, donc commencez une nouvelle session pour une nouvelle tâche. Les coûts sont minimes à 0,15 $ par 1M de tokens d'entrée et 0,50 $ par 1M de tokens de sortie : une requête avec 20 000 tokens entrants et 800 sortants coûte 0,003 $ + 0,0004 $ = 0,0034 $. Voir la page tarifs pour les recharges, qui sur ce site sont payées par crypto (USDT sur TRC20, USDC sur Base).
Dépannage
| Ce que vous voyez | Cause | Correction |
|---|---|---|
| Connexion refusée | Le proxy ne s'exécute pas ou le port est différent | Démarrez-le et faites correspondre le port dans ANTHROPIC_BASE_URL |
| Proxy 404 ou « modèle introuvable » | Le nom de modèle envoyé par l'interface en ligne de commande n'est pas dans la configuration | Ajoutez ce nom à model_list |
| Amont 401 | UPSTREAM_KEY incorrect ou vide | Réexportez la clé dans le shell du proxy et redémarrez |
429 avec concurrency | Plus de 8 requêtes simultanées (2 sur l'essai) | Réduisez les agents parallèles |
429 avec rate_limited | Plus de 300 requêtes par minute (60 en essai) | Reculez et réessayez |
429 avec Retry-After: 5 | Surcharge temporaire | Réessayez après cinq secondes |
| Streaming bloqué | Une requête en streaming occupe son emplacement jusqu'à sa fin | Annulez-la dans l'interface en ligne de commande pour libérer l'emplacement |
Pour tout ce qui n'est pas couvert ici, incluez l'en-tête de réponse X-Request-Id lorsque vous écrivez au support. La documentation liste tous les paramètres pris en charge.
Rendre permanent
Taper des exports à chaque fois devient lassant. Placez le démarrage du proxy dans un petit script et les variables client dans un alias, afin qu'une seule commande lance tout :
cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh
alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'
Comme les variables sont définies uniquement pour cette commande unique, votre commande claude normale continue de fonctionner avec ses paramètres par défaut. Ajoutez l'alias à votre profil de shell. Protégez le script avec des permissions de fichier telles que chmod 700, car il contient votre clé.
Revenir en arrière
Si vous avez exporté les variables dans le shell actuel, exécutez unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL et redémarrez l'interface CLI. Rien n'est modifié du côté de l'API, donc il n'y a rien à annuler.
Surveiller votre solde et vos dépenses
Chaque réponse de l'API porte X-Balance-USD, le crédit restant sur votre clé. LiteLLM peut transmettre les en-têtes amont dans certaines configurations, mais le moyen le plus sûr de voir votre solde est d'appeler l'amont directement de temps en temps :
curl -i https://api.claudecodeproxyapi.com/v1/models \
-H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd
Les sessions d'agent grandissent silencieusement. Chaque étape renvoie le contexte de travail, donc une longue session coûte plus cher par requête qu'une courte. Commencer une nouvelle session pour chaque tâche garde l'entrée petite et la facture basse. Aux tarifs publiés (0,15 $ par 1M d'entrée et 0,50 $ par 1M de sortie), une requête avec 50 000 tokens entrants et 1 000 sortants coûte 50 000 x 0,15 $ / 1M = 0,0075 $ plus 0,0005 $, ce qui fait 0,008 $. Vingt de ces requêtes s'élèvent à 0,16 $.
Les recharges vont de 20 $ à 500 $ en montants entiers et sont payées par en USDT sur TRC20 ou USDC sur Base sur ce site. Le crédit n'expire jamais, donc une recharge plus importante avec le bonus de +5 %, +10 % ou +15 % ne met pas de limite de temps à votre solde.
