SDK Python Anthropic : installation, configuration de base_url, streaming et gestion des erreurs

Le anthropic est le client Python officiel d’Anthropic pour l’API Claude. Ce paquet gère l’authentification, les nouvelles tentatives, le streaming et les erreurs typées, et fonctionne sans modification avec tout point de terminaison compatible avec Anthropic : définissez base_url (ou ANTHROPIC_BASE_URL) et le reste de votre code reste identique.

Installation

pip install anthropic

Les versions 1.x fonctionnent avec httpx2 et nécessitent Python 3.10 ou une version ultérieure. Si vous fournissez votre propre client HTTP, utilisez celui du SDK DefaultHttpxClient afin de conserver ses délais d’expiration et ses limites de connexion par défaut.

Créer un client

import anthropic

client = anthropic.Anthropic(
    api_key="your_key",   # default: ANTHROPIC_API_KEY
    base_url="https://aiprimetech.io",    # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com
)

base_url est l’URL racine de l’hôte. Le SDK ajoute /v1/messages lui-même, donc https://aiprimetech.io/v1 produirait /v1/v1/messages et un 404 page not found. Lorsque les deux variables sont définies dans l’environnement, anthropic.Anthropic() ne nécessite aucun argument :

export ANTHROPIC_API_KEY=your_key
export ANTHROPIC_BASE_URL=https://aiprimetech.io

Envoyer un message

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

print(message.usage.input_tokens, message.usage.output_tokens)
print(message._request_id)   # log this with any failure report

content est une liste de blocs (texte, réflexion, utilisation d’outils) ; vérifiez donc block.type au lieu de lire content[0].text sans vérification.

Recevoir les réponses en streaming

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Write a short story about a lighthouse."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

Utilisez le streaming pour toute requête avec une entrée longue, une sortie longue ou une valeur élevée de max_tokens : une requête sans streaming doit se terminer avant le délai d’expiration, contrairement à un flux. messages.create(..., stream=True) vous donne l’itérateur d’événements brut si vous n’avez pas besoin de l’utilitaire.

Client asynchrone

import asyncio, anthropic

client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io")
limit = asyncio.Semaphore(3)   # stay within your key's concurrency

async def ask(question: str) -> str:
    async with limit:
        msg = await client.messages.create(
            model="claude-haiku-4-5",
            max_tokens=512,
            messages=[{"role": "user", "content": question}],
        )
        return next(b.text for b in msg.content if b.type == "text")

async def main():
    answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"]))
    print(answers)

asyncio.run(main())

Le sémaphore est important. Lancer des centaines de requêtes simultanément avec asyncio.gather est la cause la plus fréquente des erreurs Concurrency limit exceeded que nous observons avec les clients Python.

Délais d’attente et nouvelles tentatives

Valeurs par défaut : un délai d’expiration de 10 minutes par requête et 2 nouvelles tentatives automatiques avec temporisation exponentielle. Le SDK réessaie en cas d’erreurs de connexion et de réponses 408, 409, 429 et 5xx. Comme les dépassements de délai déclenchent aussi de nouvelles tentatives, la durée totale dans le pire des cas correspond au délai d’expiration multiplié par le nombre de tentatives.

client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4)

# override for one call only
client.with_options(timeout=300.0).messages.create(
    model="claude-opus-5-5",
    max_tokens=4000,
    messages=[{"role": "user", "content": "Review this design doc..."}],
)

Gestion des erreurs

try:
    message = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
                                      messages=[{"role": "user", "content": "Hi"}])
except anthropic.NotFoundError as e:
    print("Bad model ID or URL:", e.message)
except anthropic.RateLimitError as e:
    print("Rate limited, retry after", e.response.headers.get("retry-after"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.type, e.message)
except anthropic.APIConnectionError:
    print("Network problem")

Interceptez d’abord les classes spécifiques et APIStatusError en dernier ; un seul except générique masque la différence entre les erreurs qui méritent une nouvelle tentative et celles qui nécessitent une modification du code. e.type fournit la chaîne du type d’erreur de l’API, par exemple rate_limit_error ou overloaded_error.

Identifiants des modèles

client.models.list() renvoie les modèles proposés par un point de terminaison, ce qui vous permet de vérifier un identifiant avant de l’utiliser. Utilisez les identifiants exactement tels qu’ils sont écrits, sans suffixes de date.

Résolution des problèmes sur une passerelle

Pour en savoir plus sur les erreurs côté modèle : le guide des erreurs de l’API Claude.

Questions fréquentes

AI Prime Tech est une passerelle API indépendante. Elle n’est ni affiliée à Anthropic, ni approuvée par Anthropic, ni revendeuse d’Anthropic. Claude et les noms de modèles associés sont des marques de leurs propriétaires respectifs.