Instalación y configuración del SDK de Python de Anthropic

El paquete oficial de Python anthropic es la forma recomendada de llamar a la API de Claude desde Python.

Se encarga de los encabezados de autenticación, la serialización de solicitudes, los reintentos y el análisis de respuestas para que no tengas que construir esa infraestructura tú mismo.

Esta página cubre su instalación, la configuración de un cliente y la realización de tu primera llamada real.

Resumen

El paquete anthropic se instala con un solo comando pip install anthropic en cualquier entorno Python 3.8+.

Una instancia de cliente, anthropic.Anthropic(), es el objeto que configuras una vez y reutilizas para cada llamada en tu aplicación.

Por defecto, lee tu clave API de ANTHROPIC_API_KEY, pero puedes anular la clave, el tiempo de espera, el número de reintentos e incluso la URL base a través de los argumentos del constructor.

También hay un cliente asíncrono, anthropic.AsyncAnthropic, con la misma interfaz para usar dentro de aplicaciones asyncio.

Obtener la configuración correcta una vez, en un solo lugar, evita la dispersión de instancias de cliente ad hoc con configuraciones inconsistentes en una base de código.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=200,
    messages=[{"role": "user", "content": "Confirma que el SDK está instalado correctamente."}],
)
print(response.content[0].text)

Cuándo usar esto:

• Al iniciar cualquier proyecto nuevo de Python que llame a Claude.
• Quieres reintentos automáticos, respuestas tipadas y soporte de streaming sin escribir código HTTP sin procesar.
• Estás creando un script síncrono o un servicio basado en asyncio (usa AsyncAnthropic para este último).

Ejemplo de trabajo

import os
import anthropic
 
# Primero, un entorno virtual recomendado:
#   python -m venv .venv && source .venv/bin/activate
#   pip install anthropic
 
def build_client() -> anthropic.Anthropic:
    return anthropic.Anthropic(
        api_key=os.environ["ANTHROPIC_API_KEY"],
        timeout=30.0,       # segundos, por solicitud
        max_retries=2,      # reintentos automáticos para respuestas 429/5xx
    )
 
 
def main() -> None:
    client = build_client()
    response = client.messages.create(
        model="claude-sonnet-5-20260630",
        max_tokens=150,
        messages=[
            {"role": "user", "content": "Enumera tres usos para el SDK de Python de Anthropic."}
        ],
    )
    print(response.content[0].text)
    print(f"Tokens utilizados: {response.usage.input_tokens} entrada / {response.usage.output_tokens} salida")
 
 
if __name__ == "__main__":
    main()

Lo que esto demuestra:

• Construir el cliente una vez, en una función dedicada, en lugar de construirlo en línea dondequiera que se use.
• Establecer timeout y max_retries explícitos en lugar de depender de los valores predeterminados, lo que importa una vez que superas una prueba rápida.
• Leer usage de la respuesta para rastrear el consumo de tokens junto con el texto generado.

Inmersión profunda

Cómo funciona

• pip install anthropic descarga el paquete (y sus dependencias HTTP) de PyPI; soporta Python 3.8 y versiones posteriores.
• Gestores de paquetes como poetry add anthropic o uv add anthropic funcionan de manera idéntica y se recomiendan para proyectos que fijan dependencias.
• anthropic.Anthropic() es un cliente síncrono: client.messages.create(...) se bloquea hasta que se recibe la respuesta (o el stream completo).
• anthropic.AsyncAnthropic() refleja los mismos nombres de método pero devuelve "awaitables", para usar dentro de funciones async def.
• Cada cliente es seguro para construir una vez y reutilizar en muchas llamadas; no hay necesidad de construir un nuevo cliente por solicitud.

Opciones útiles del constructor

El cliente asíncrono

import asyncio
import anthropic
 
async def main() -> None:
    client = anthropic.AsyncAnthropic()
    response = await client.messages.create(
        model="claude-haiku-4-5-20260601",
        max_tokens=100,
        messages=[{"role": "user", "content": "Saluda asincrónicamente."}],
    )
    print(response.content[0].text)
 
asyncio.run(main())

Notas de Python

# Reutiliza una instancia de cliente en un módulo o aplicación en lugar de
# construir una nueva por llamada de función: las conexiones y
# la configuración de reintentos se establecen una vez, en el momento de la importación o el inicio.
import anthropic
 
client = anthropic.Anthropic()  # a nivel de módulo, creado una vez
 
def summarize(text: str) -> str:
    response = client.messages.create(
        model="claude-haiku-4-5-20260601",
        max_tokens=200,
        messages=[{"role": "user", "content": f"Resume: {text}"}],
    )
    return response.content[0].text

Errores comunes

• Instalar en el Python del sistema en lugar de en un entorno virtual. Esto causa conflictos de versiones entre proyectos no relacionados con el tiempo. Solución: crea un entorno virtual (venv, poetry o uv) por proyecto antes de instalar.
• Construir un nuevo cliente en cada llamada de función. Esto es un desperdicio y puede omitir la reutilización de conexiones. Solución: construye el cliente una vez, al inicio del módulo o de la aplicación, y pásalo o reutiliza una instancia a nivel de módulo.
• Usar el cliente síncrono dentro de una función async def. client.messages.create(...) bloquea el bucle de eventos durante la llamada, lo que puede detener otro trabajo asíncrono concurrente. Solución: usa anthropic.AsyncAnthropic con await dentro de funciones asíncronas.
• No fijar la versión del SDK en producción. Una dependencia anthropic no fijada puede introducir cambios que rompan en una instalación nueva. Solución: fija un rango de versión específico en requirements.txt o en tu archivo de bloqueo, y actualiza deliberadamente.
• Anular base_url accidentalmente al copiar la configuración de ejemplo. Apuntar a la URL incorrecta causa errores de conexión confusos que parecen no relacionados con la configuración. Solución: establece base_url solo intencionalmente (por ejemplo, para un proxy) y elimínalo si se copió de un ejemplo no relacionado.
• Asumir que timeout cubre toda la respuesta en streaming. Para generaciones largas en streaming, un tiempo de espera demasiado corto puede cortar un stream legítimo en progreso. Solución: establece un tiempo de espera más largo para casos de uso de streaming, o utiliza anulaciones de tiempo de espera por solicitud.

Alternativas

Preguntas frecuentes

Relacionado

• Fundamentos de la API de Claude - Básico - tus primeras llamadas de trabajo.
• Autenticación de llamadas a la API de Claude con el encabezado x-api-key - configuración de claves en profundidad.
• Construcción de un envoltorio reutilizable para el cliente de la API de Claude - envolviendo el cliente con valores predeterminados para toda la aplicación.
• Manejo de límites de tasa con backoff exponencial - lo que max_retries hace internamente.

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.