DeepSeek Anthropic API: Python, límites y Claude Code

DeepSeek Anthropic API es la interfaz de DeepSeek compatible con el formato Anthropic Messages. Permite utilizar el SDK de Anthropic para enviar solicitudes a modelos DeepSeek, con una clave de DeepSeek y la URL base https://api.deepseek.com/anthropic.

La guía oficial de compatibilidad documenta esta conexión. El SDK actúa como cliente; DeepSeek recibe la solicitud, ejecuta el modelo y factura su consumo. En este tutorial completarás una primera llamada con Python y revisarás los cambios que necesita una aplicación antes de migrarla.

URL, clave y endpoint: la configuración correcta

Elemento	Valor para conectar directamente con DeepSeek
Cliente Python	Paquete `anthropic`.
URL base del SDK	`https://api.deepseek.com/anthropic`.
Endpoint HTTP completo	`POST https://api.deepseek.com/anthropic/v1/messages`.
Credencial	Una clave de DeepSeek Platform.
Modelo del ejemplo	`deepseek-flash`.
Cuenta que paga el uso	La cuenta de DeepSeek asociada a esa clave.

Endpoint de Messages y URL base de DeepSeek para utilizar el SDK de Anthropic.

La referencia de Messages explica que el SDK añade /v1/messages. Introduce únicamente la URL base en base_url; reservar la ruta completa para un cliente HTTP directo evita duplicarla.

DeepSeek acepta autenticación mediante x-api-key o Authorization: Bearer. Si envías ambos encabezados, Authorization tiene prioridad. Deja que el SDK gestione la autenticación del ejemplo; no añadas otro encabezado con una credencial diferente.

Si utilizas una pasarela de terceros, comprueba su dirección, su clave y su facturación. Un tutorial que apunta al dominio de esa pasarela describe una conexión distinta de la conexión directa mostrada aquí.

Primera solicitud con Anthropic SDK en Python

Prepara el entorno y la clave

Necesitas Python 3.10 o posterior, según los requisitos actuales del SDK oficial de Anthropic, una clave de DeepSeek y saldo suficiente. Abre una terminal en una carpeta de trabajo y crea un entorno virtual.

En macOS o Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade anthropic
export ANTHROPIC_API_KEY="TU_CLAVE_DEEPSEEK"

En PowerShell de Windows:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade anthropic
$env:ANTHROPIC_API_KEY="TU_CLAVE_DEEPSEEK"

Aunque la variable se llama ANTHROPIC_API_KEY, su valor debe ser tu clave de DeepSeek. Reemplaza el texto ilustrativo en la terminal y mantén el secreto fuera del código y del repositorio. Estas asignaciones se aplican a esa sesión de terminal y a los procesos que inicies desde ella.

Ejemplo completo para enviar y leer un mensaje

Guarda este archivo como probar_deepseek_anthropic.py. La URL se fija explícitamente en el cliente, y la clave se lee desde el entorno. La tarea utiliza un aviso breve cuyo contenido puedes comprobar sin depender de información externa.

"""Prueba DeepSeek con el SDK de Anthropic. Requiere Python 3.10+ y anthropic."""

import os

from anthropic import APIError, APIStatusError, Anthropic


def final_text(message):
    reason = getattr(message, "stop_reason", None)
    if reason == "max_tokens":
        raise ValueError("La respuesta quedó truncada por el límite de tokens.")
    if reason != "end_turn":
        raise ValueError(f"La respuesta no terminó con end_turn: {reason}.")
    blocks = getattr(message, "content", None)
    if not isinstance(blocks, list):
        raise ValueError("La respuesta no contiene una lista de bloques.")
    parts = []
    for block in blocks:
        if getattr(block, "type", None) == "text":
            text = getattr(block, "text", None)
            if not isinstance(text, str):
                raise ValueError("La respuesta contiene un bloque de texto inválido.")
            parts.append(text)
    text = "\n".join(parts)
    if not text.strip():
        raise ValueError("La API no devolvió texto.")
    return text


def main():
    api_key = os.getenv("ANTHROPIC_API_KEY", "")
    if not api_key or any(ord(c) < 33 or ord(c) > 126 for c in api_key):
        raise SystemExit("Define ANTHROPIC_API_KEY con tu clave de DeepSeek.")
    try:
        # El timeout y los cero reintentos son decisiones de este ejemplo.
        with Anthropic(api_key=api_key, base_url="https://api.deepseek.com/anthropic",
                       timeout=90.0, max_retries=0) as client:
            message = client.messages.create(
                model="deepseek-flash", max_tokens=800, stream=False,
                thinking={"type": "disabled"},
                system="Responde en español latinoamericano sin inventar información.",
                messages=[{"role": "user", "content": (
                    "Resume en tres viñetas este aviso: Abrimos el viernes a las 10:00. "
                    "Preparamos pedidos hasta las 16:00. El sábado no hay entregas.")}],
            )
    except APIStatusError as exc:
        raise SystemExit(f"Error de la API: HTTP {exc.status_code}.") from None
    except APIError as exc:
        raise SystemExit(f"Error de conexión o SDK ({type(exc).__name__}).") from None

    print(f"stop_reason: {getattr(message, 'stop_reason', None)}")
    usage = getattr(message, "usage", None)
    for name in ("input_tokens", "cache_read_input_tokens",
                 "cache_creation_input_tokens", "output_tokens"):
        value = getattr(usage, name, None)
        if value is not None:
            print(f"{name}: {value}")
    try:
        print("\n" + final_text(message))
    except ValueError as exc:
        raise SystemExit(str(exc)) from None


if __name__ == "__main__":
    main()

Ejecuta el programa con el entorno activado:

python probar_deepseek_anthropic.py

El ejemplo realiza una solicitud sin streaming, pide hasta 800 tokens de salida y desactiva el razonamiento mediante thinking={"type": "disabled"}. En este SDK, thinking es un argumento normal de Messages; no necesitas colocarlo en extra_body.

El cliente de Python permite configurar reintentos y timeout. Aquí los reintentos automáticos están desactivados y el timeout se establece en 90 segundos. Ese valor no es una garantía de duración máxima total del programa.

Cómo interpretar la respuesta

Messages devuelve una lista en content. El programa reúne las partes cuyo type es text, en lugar de asumir que el primer bloque contiene la respuesta visible. También imprime los campos de consumo disponibles y revisa stop_reason.

Motivo de finalización	Interpretación práctica
`end_turn`	El modelo terminó su turno. Revisa el contenido antes de utilizarlo.
`max_tokens`	La generación alcanzó el límite de salida; la respuesta puede estar incompleta.
`tool_use`	El modelo solicita una herramienta del cliente; falta continuar el flujo.
`stop_sequence`	Se encontró una secuencia de parada configurada.
`refusal`	La generación terminó por filtrado de contenido.

Como esta prueba no declara herramientas ni secuencias de parada, solo acepta un turno terminado con end_turn y texto no vacío. Después comprueba que el resumen conserve los horarios y la condición del sábado.

Qué modelo se ejecuta al utilizar nombres de Claude

Para una integración nueva, declara el modelo DeepSeek que quieres utilizar. El mapeo de nombres de Messages también acepta determinados nombres que comienzan con claude:

Nombre enviado	Modelo DeepSeek que atiende la solicitud
`deepseek-flash`	Flash, actualmente DeepSeek-V4.1-Flash-1017.
`deepseek-v4-pro`	DeepSeek-V4-Pro-0813.
Nombre compatible que empieza por `claude-opus`	`deepseek-v4-pro`.
Otros nombres aceptados que empiezan por `claude`, incluidos Sonnet y Haiku	`deepseek-flash`.

Mapeo de nombres de Claude a modelos DeepSeek en la API compatible con Anthropic.

Los nombres no admitidos que tampoco empiezan por claude generan un error 400. Además, el campo model de la respuesta puede conservar el alias solicitado. Por eso, ver una cadena con el nombre Claude no demuestra que Claude haya procesado la petición.

La página de modelos y precios es la referencia para la versión y la tarifa. Los nombres anteriores de Flash siguen aceptándose como alias, pero el ejemplo utiliza el identificador actual para facilitar la revisión de la configuración.

Qué debes adaptar al migrar una aplicación

Razonamiento y límites de salida

DeepSeek activa el razonamiento por defecto. La guía de Thinking Mode distingue el interruptor thinking del esfuerzo, que en el formato Anthropic se configura con output_config.effort.

Control	Comportamiento que debes considerar
`thinking.type`	`enabled` lo activa y `disabled` lo desactiva. `adaptive` se trata como `enabled`.
`thinking.budget_tokens`	Se ignora; no fija un presupuesto de tokens de razonamiento.
`output_config.effort`	Permite seleccionar el esfuerzo. Los niveles principales son `low`, `high` y `max`; el valor predeterminado es `high`.
`temperature`	No ajusta el muestreo en modo de razonamiento, donde queda fijada en 1.
`max_tokens`	El SDK exige indicarlo, aunque el endpoint HTTP lo hace opcional. Incluye los tokens de razonamiento.

Si tu aplicación ajusta top_p, revisa también el modelo y el modo: Flash lo aplica en razonamiento, con un rango efectivo de 0.95 a 1; Pro aplica el valor proporcionado en modo sin razonamiento. No traslades una configuración de muestreo suponiendo que producirá el mismo comportamiento.

La referencia advierte una excepción para ciertas solicitudes del agente principal de Claude Code u OpenCode en modo de razonamiento: la compatibilidad puede elevar el límite efectivo por encima del max_tokens solicitado. No utilices ese parámetro como único control de gasto de un agente.

Campos y capacidades que requieren cambios

La matriz de compatibilidad distingue campos admitidos, ignorados y no compatibles. Estas diferencias afectan decisiones habituales de una migración:

Elemento	Estado y consecuencia
`system`	Se admite como campo de nivel superior. No lo conviertas en un mensaje con `role: "system"` dentro de `messages`.
`output_config.format`	Se ignora. No garantiza que la respuesta cumpla un JSON Schema.
`cache_control`	Se ignora. La caché de DeepSeek tiene su propio funcionamiento automático.
`top_k`, `container`, `mcp_servers` y `service_tier`	Se ignoran; su presencia no activa esas funciones.
Bloques `document`	No están admitidos. Un PDF no se puede trasladar directamente como documento de Anthropic.
Bloques `redacted_thinking`	No están admitidos; revisa esos bloques si reutilizas historiales de otro proveedor.
Bloques `image`	Flash admite imágenes; Pro no las procesa. Usa la estructura `image` con `source` del formato Anthropic.

Compatibilidad de DeepSeek con los bloques de mensajes image, document y redacted_thinking.

Si necesitas datos estructurados, valida la salida en tu aplicación. También puedes evaluar el JSON Output de Chat Completions, cambiando al contrato de ese endpoint. Un esquema de argumentos de herramientas y un esquema de respuesta final resuelven necesidades distintas.

Para imágenes previamente subidas, la Files API compatible con Anthropic exige anthropic-beta: files-api-2025-04-14, incluido al referenciarlas en Messages. Esta capacidad permite reutilizar imágenes; no habilita la recepción general de documentos PDF.

Cómo conservar el historial y continuar llamadas a herramientas

Messages no conserva por sí solo la conversación entre solicitudes. Tu aplicación envía el historial necesario en cada turno. Cuando intervienen herramientas, debe conservar también los bloques completos de la respuesta que devuelve DeepSeek, incluidos los de razonamiento y de uso de herramientas.

Para declarar una herramienta del cliente, proporciona name, input_schema y, si corresponde, description. Este objeto ilustra una entrada del arreglo tools:

{
  "name": "consultar_estado",
  "description": "Consulta el estado de un envío por su identificador.",
  "input_schema": {
    "type": "object",
    "properties": {"envio_id": {"type": "string"}},
    "required": ["envio_id"]
  }
}

Omite type en esta declaración de herramienta del cliente. En DeepSeek, ese campo selecciona una herramienta del servidor; añadir type: "custom" produce un error 422.

Recibe los bloques tool_use y conserva el mensaje completo del asistente.
Valida los argumentos y ejecuta la función correspondiente en tu aplicación.
Agrega inmediatamente un mensaje de usuario con un tool_result por cada llamada. Cada tool_use_id debe coincidir con el id recibido; coloca los resultados antes de cualquier texto adicional.
Envía el historial actualizado para que el modelo continúe con el resultado real.

Hay dos diferencias especialmente útiles al depurar: tool_choice: {"type": "any"} se comporta como auto y no fuerza una llamada; seleccionar una herramienta por nombre requiere desactivar el razonamiento. Si una función falla, describe el error en el contenido del resultado: tool_result.is_error se ignora.

La búsqueda web del servidor sigue otro flujo. Los bloques server_tool_use y web_search_tool_result representan una búsqueda ejecutada por el servicio; el cliente no debe repetirla como si fuera una función propia. Conserva esos bloques al continuar la conversación.

Streaming: cómo reconocer una respuesta terminada

Para recibir la salida por partes puedes utilizar client.messages.stream() y sus utilidades de texto, descritas en el SDK de Python. Si implementas tu propio lector de eventos, sigue el contrato de streaming de Messages:

El flujo utiliza eventos SSE con nombre y termina normalmente con message_stop; no envía data: [DONE].
El consumo final de message_delta.usage es acumulado. No lo sumes al consumo inicial de message_start.
Si recibes argumentos de una herramienta por fragmentos, reúne el JSON del bloque antes de analizarlo.
Una conexión cerrada antes de message_stop deja una respuesta incompleta, aunque ya hayas mostrado texto.

Los fallos durante el flujo pueden cerrar la conexión sin un evento de error de Anthropic. Separa en tu aplicación el texto provisional de una respuesta confirmada como terminada, para evitar que una interrupción se guarde como éxito.

Configuración específica para Claude Code

DeepSeek publica una receta de integración con Claude Code. Por su parte, Anthropic indica en su documentación de gateways que no ofrece soporte para dirigir Claude Code a modelos ajenos a Claude. Evalúa esta conexión como un procedimiento documentado por DeepSeek y comprueba las funciones que necesites con tu versión del cliente.

Si ya tienes Claude Code instalado, estas variables reproducen la configuración publicada por DeepSeek para usar Flash. A diferencia del ejemplo Python, aquí la credencial se asigna a ANTHROPIC_AUTH_TOKEN.

En macOS o Linux:

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="TU_CLAVE_DEEPSEEK"
export ANTHROPIC_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"
export CLAUDE_CODE_EFFORT_LEVEL="max"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW="786432"

En PowerShell de Windows:

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="TU_CLAVE_DEEPSEEK"
$env:ANTHROPIC_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"
$env:CLAUDE_CODE_AUTO_COMPACT_WINDOW="786432"

Configuración de Claude Code para usar DeepSeek en Linux, macOS y Windows.

La receta dirige también las selecciones Opus y Sonnet del cliente hacia Flash. Es una configuración explícita distinta del mapeo del servidor, que dirige un nombre claude-opus* recibido a Pro. La indicación [1m] pertenece a esta configuración de Claude Code; el ejemplo SDK usa deepseek-flash.

Abre una carpeta de prueba, ejecuta claude desde esa terminal y consulta /status. La guía de comprobación de conexiones permite revisar la URL base y la fuente de autenticación. Si aparece una credencial anterior, corrige la configuración que realmente está utilizando el cliente antes de enviar trabajo.

Empieza con una tarea pequeña y revisa el consumo en DeepSeek. El SDK, la terminal y los nombres de selección no convierten estas solicitudes en uso incluido en una suscripción de Claude.

Consumo, caché y costo de las solicitudes

Los cargos corresponden al modelo DeepSeek y a sus tarifas. Para interpretar usage en Messages, distingue estas cantidades:

Campo	Qué representa
`input_tokens`	Entrada que no se atendió desde la caché.
`cache_read_input_tokens`	Entrada atendida desde la caché.
`cache_creation_input_tokens`	Actualmente es 0 en este servicio.
`output_tokens`	Salida generada, incluidos los tokens de razonamiento cuando está activo.

La entrada total se obtiene sumando los tres campos de entrada. No interpretes input_tokens como el total incluyendo aciertos de caché. La caché de contexto de DeepSeek funciona automáticamente y no garantiza un acierto en cada repetición.

La tabla oficial de precios publica estos importes en USD por un millón de tokens:

Modelo y periodo	Entrada con caché	Entrada sin caché	Salida
Flash, fuera de pico	0.003	0.15	0.60
Flash, horario pico	0.006	0.30	1.20
Pro, fuera de pico	0.022	0.66	1.98
Pro, horario pico	0.044	1.32	3.96

Precios de DeepSeek Flash y Pro por millón de tokens en horarios pico y fuera de pico.

El horario pico es de lunes a viernes, de 01:00 a 04:00 y de 06:00 a 10:00 UTC, salvo los feriados oficiales de China. El resto del tiempo se aplica la tarifa fuera de pico.

Como ejemplo hipotético, 10000 tokens de entrada sin caché, 10000 con caché y 2000 de salida en Flash durante horario pico darían:

(10000 × 0.30 + 10000 × 0.006 + 2000 × 1.20) / 1000000 = 0.00546 USD

El cálculo ilustra cómo separar las categorías; no es una medición del programa anterior. Si activas búsqueda web, considera además su facturación y las solicitudes de modelo que pueda generar el flujo. Revisa esos cargos antes de extrapolar el costo de una conversación a un agente con varias herramientas.

Errores frecuentes y comprobación de la migración

Utiliza el estado HTTP y el mensaje que corresponda al fallo. La referencia de errores de DeepSeek distingue estas causas generales:

Error o síntoma	Comprobación y acción
Ruta incorrecta o error 404	Revisa la URL base del SDK y evita añadir otra vez `/v1/messages`.
`401`	Comprueba la credencial que envía el proceso y que pertenezca a DeepSeek.
`402`	Revisa el saldo de la cuenta; cambiar el nombre de la variable no añade crédito.
`400` o `422`	Revisa el modelo, la estructura de `messages`, los bloques y las herramientas.
Fallo después de una llamada a herramienta	Conserva el mensaje completo del asistente y devuelve un resultado por cada ID, en el orden de mensajes requerido.
`429`	Reduce el ritmo o la concurrencia; limita los reintentos y añade espera.
`500` o `503`	El servicio informa un fallo o sobrecarga. Espera antes de repetir y acota los intentos.
Texto vacío, truncado o streaming interrumpido	Revisa los bloques, `stop_reason` y la finalización del flujo antes de registrar un resultado correcto.

El cuerpo de error utiliza la estructura de DeepSeek {"error": {...}}, sin exigir el campo superior type: "error" de Anthropic. Si escribes un adaptador HTTP propio, evita depender de ese campo para detectar todos los fallos.

Antes de trasladar la aplicación completa, comprueba estos resultados observables:

Texto: una entrada conocida produce una salida legible y conserva los datos que necesitas.
Finalización: tu aplicación distingue una respuesta completa de una truncada, vacía o interrumpida.
Herramientas: los argumentos se validan, la función se ejecuta en el lugar correcto y el resultado vuelve al ID correspondiente.
Estado y costos: mantienes el historial necesario, confirmas el modelo configurado y registras el consumo real.

Amplía la integración después de comprobar estos casos con tus propias tareas. Así podrás identificar qué cambios proceden del formato de la API, cuáles dependen del modelo y cuáles pertenecen a la lógica de tu aplicación.

Verificación documental: 10 de noviembre de 2026. Se comprobó la sintaxis del ejemplo y su lectura de respuestas mediante casos locales simulados. No se ejecutó una solicitud autenticada contra la API de DeepSeek.