Aviso de independencia: DeepSeek Español es un sitio informativo independiente operado por Ahmed Aly. No pertenece a DeepSeek ni a Anthropic y no está afiliado ni respaldado por ninguna de las dos empresas. Esta guía usa el cliente oficial de Anthropic contra el endpoint compatible que publica DeepSeek; no afirma que DeepSeek sea un modelo Claude ni que exista paridad completa entre ambos servicios.
Última verificación documental: 25 de julio de 2026. Los ejemplos se han contrastado con la documentación oficial y no contienen una clave real. Deben probarse con una cuenta propia antes de utilizarlos en producción.
Respuesta rápida
Para usar DeepSeek con Anthropic SDK, crea el cliente con una clave de DeepSeek y la Base URL https://api.deepseek.com/anthropic. El SDK añade la ruta de Messages, por lo que no debes añadir /v1 a la Base URL. En llamadas directas utiliza deepseek-v4-pro o deepseek-v4-flash, sin el sufijo [1m]. La compatibilidad cubre Messages, texto, streaming, thinking y herramientas estándar, pero varios campos y tipos de contenido de Anthropic se ignoran o no están admitidos.
| Elemento | Valor verificado |
|---|---|
| Base URL del cliente | https://api.deepseek.com/anthropic |
| Ruta resultante de Messages | /anthropic/v1/messages |
| Credencial | Clave API de DeepSeek |
| Modelos actuales | deepseek-v4-pro y deepseek-v4-flash |
| Node.js | @anthropic-ai/sdk; Node.js 20 LTS o posterior no EOL |
| Python | anthropic; Python 3.9 o posterior |
| Formato | Anthropic Messages compatible, con diferencias documentadas |
| Proveedor y facturación | DeepSeek Open Platform |
Qué significa la compatibilidad con Anthropic SDK
El SDK de Anthropic actúa como cliente HTTP. Al cambiar su Base URL, construye solicitudes con el formato Messages y las envía al host de DeepSeek. DeepSeek autentica la clave, elige el modelo, ejecuta la inferencia y registra el consumo en la cuenta de DeepSeek API.
Esta compatibilidad facilita reutilizar una integración basada en Messages, pero no convierte el servicio en la API de Anthropic. Los modelos, precios, límites, tratamiento de datos, disponibilidad y soporte pertenecen a DeepSeek. Además, la tabla oficial identifica campos ignorados y bloques que provocan incompatibilidades; por eso una aplicación debe probar las funciones que realmente utiliza.
Requisitos y manejo de la clave
- Una cuenta de DeepSeek Platform con una clave API activa y saldo disponible.
- Node.js 20 LTS o posterior no EOL para el SDK TypeScript, o Python 3.9 o posterior para el SDK Python.
- Una variable de entorno privada llamada
DEEPSEEK_API_KEY. - Un entorno de prueba sin datos personales ni secretos innecesarios.
- Límites propios de tiempo, tamaño, concurrencia, reintentos y gasto.
DEEPSEEK_API_KEY es un nombre elegido por esta guía para que el origen de la credencial sea inequívoco. El constructor del SDK recibe ese valor mediante apiKey en TypeScript o api_key en Python. No expongas la clave en JavaScript del navegador, repositorios, registros, tickets o capturas de pantalla.
DeepSeek con Anthropic SDK en Node.js o TypeScript
Crea un proyecto, instala el paquete oficial y define la variable en la terminal:
npm install @anthropic-ai/sdk
export DEEPSEEK_API_KEY="sustituir-por-la-clave-real"Ejemplo mínimo de Messages con V4 Pro:
import Anthropic from "@anthropic-ai/sdk";
const apiKey = process.env.DEEPSEEK_API_KEY;
if (!apiKey) {
throw new Error("Falta la variable DEEPSEEK_API_KEY");
}
const client = new Anthropic({
apiKey,
baseURL: "https://api.deepseek.com/anthropic",
});
const message = await client.messages.create({
model: "deepseek-v4-pro",
max_tokens: 512,
system: "Responde en español y distingue hechos de suposiciones.",
messages: [
{
role: "user",
content: "Explica en tres puntos qué valida una prueba unitaria.",
},
],
});
const text = message.content
.filter((block) => block.type === "text")
.map((block) => block.text)
.join("");
console.log("stop_reason:", message.stop_reason);
console.log(text);No des por hecho que content[0] siempre es texto. Una respuesta puede incluir bloques de thinking o herramientas; filtrar por block.type evita interpretar otro tipo de bloque como salida visible.
DeepSeek con Anthropic SDK en Python
python3 -m venv .venv
source .venv/bin/activate
pip install anthropic
export DEEPSEEK_API_KEY="sustituir-por-la-clave-real"import os
from anthropic import Anthropic
api_key = os.environ.get("DEEPSEEK_API_KEY")
if not api_key:
raise RuntimeError("Falta la variable DEEPSEEK_API_KEY")
client = Anthropic(
api_key=api_key,
base_url="https://api.deepseek.com/anthropic",
)
message = client.messages.create(
model="deepseek-v4-pro",
max_tokens=512,
system="Responde en español y distingue hechos de suposiciones.",
messages=[
{
"role": "user",
"content": "Explica en tres puntos qué valida una prueba unitaria.",
}
],
)
text = "".join(
block.text
for block in message.content
if block.type == "text"
)
print("stop_reason:", message.stop_reason)
print(text)El SDK añade /v1/messages a la Base URL configurada. Si escribes https://api.deepseek.com/anthropic/v1 como base, puedes construir una ruta duplicada. Conserva exactamente https://api.deepseek.com/anthropic.
Modelos V4 y nombres retirados
Valor enviado en model | Comportamiento documentado |
|---|---|
deepseek-v4-pro | Selecciona V4 Pro directamente. |
deepseek-v4-flash | Selecciona V4 Flash directamente. |
Nombre que empieza por claude-opus | El endpoint lo mapea a V4 Pro. |
Nombre que empieza por claude-sonnet o claude-haiku | El endpoint lo mapea a V4 Flash. |
| Nombre no admitido | Fallback documentado a V4 Flash. |
Usa IDs explícitos de DeepSeek para que una migración sea auditable y para evitar que una errata active el fallback. El sufijo [1m] es una convención de Claude Code, no parte del ID de API; no lo añadas a solicitudes realizadas directamente con el SDK.
DeepSeek fijó el 24 de julio de 2026 a las 15:59 UTC como límite para retirar por completo deepseek-chat y deepseek-reasoner. El plazo ya ha vencido y el ejemplo actual de GET /models solo enumera deepseek-v4-flash y deepseek-v4-pro. No uses los aliases antiguos en código nuevo ni atribuyas un error HTTP concreto sin una prueba autenticada.
Parámetros y bloques compatibles
La matriz oficial de compatibilidad Anthropic de DeepSeek documenta estos elementos:
| Área | Elementos admitidos |
|---|---|
| Autenticación | Cabecera x-api-key, gestionada por el SDK a partir de la clave configurada. |
| Messages | max_tokens, stop_sequences, stream, system, temperature de 0 a 2 y top_p. |
| Metadatos | metadata.user_id; el resto de metadatos se ignora. |
| Herramientas | name, description, input_schema y tool_choice con none, auto, any o una herramienta concreta. |
| Contenido | text, thinking, tool_use, tool_result, server_tool_use y web_search_tool_result. |
Compatible no significa idéntico en todos los valores. Por ejemplo, temperature acepta hasta 2 en DeepSeek, y cuando Thinking está activo temperature y top_p no producen efecto. Valida el comportamiento con el modelo y modo concretos que utilizará tu aplicación.
Campos aceptados pero ignorados
Un campo ignorado puede no generar error, pero tampoco activa la función esperada. La documentación enumera:
- Cabeceras
anthropic-betayanthropic-version. container,mcp_servers,service_tierytop_k.cache_controlen mensajes y herramientas.disable_parallel_tool_useytool_result.is_error.citationsy los campos demetadatadistintos deuser_id.
No utilices una cabecera beta como prueba de que una función de Anthropic quedó habilitada. Aunque cache_control se ignora, DeepSeek mantiene por separado su caché automática de prefijos en modo best effort; no prometas un acierto de caché para una solicitud concreta.
Contenido y funciones no compatibles
| Elemento | Estado | Implicación |
|---|---|---|
Bloques image y document | No admitidos | Envía texto compatible; no presentes el endpoint como multimodal. |
search_result | No admitido | No lo sustituyas por web_search_tool_result sin adaptar el flujo. |
redacted_thinking | No admitido | No esperes el mismo tratamiento de bloques de razonamiento redactados. |
code_execution_tool_result | No admitido | Gestiona cualquier ejecución en tu propia aplicación y con permisos explícitos. |
mcp_tool_use y mcp_tool_result | No admitidos | La compatibilidad con herramientas estándar no equivale a compatibilidad MCP administrada por la API. |
container_upload | No admitido | No envíes archivos mediante este tipo de bloque. |
La guía no documenta paridad para Message Batches, Files API, recuento previo de tokens, computer use, helpers beta u output estructurado mediante JSON Schema. Si una función no aparece en la matriz, trátala como no confirmada hasta que exista documentación oficial o una prueba controlada; no la anuncies como compatible.
Thinking, esfuerzo y caché
DeepSeek activa Thinking por defecto en este endpoint. En formato Anthropic documenta output_config.effort: high y max se aplican directamente; low y medium se mapean a high, y xhigh se mapea a max. budget_tokens se ignora. Estas reglas impiden prometer que cada nivel de otro proveedor conserva su semántica exacta.
Cuando una respuesta con thinking solicita herramientas, conserva y vuelve a enviar todos los bloques del mensaje del asistente, no solo el bloque tool_use. Esto mantiene el contexto que el endpoint necesita para continuar el turno. No muestres ni registres razonamiento interno como si fuera una explicación revisada para el usuario.
La caché de prefijos de DeepSeek está activada automáticamente y no requiere cache_control. Mantener idéntico el comienzo de las solicitudes puede permitir un acierto, pero el servicio la describe como best effort; mide los contadores de uso reales y no la presupuestes como garantía.
Streaming con el SDK
El endpoint admite Server-Sent Events y los SDK proporcionan utilidades para consumirlos. Ejemplo en Python:
with client.messages.stream(
model="deepseek-v4-pro",
max_tokens=512,
messages=[
{"role": "user", "content": "Resume qué es una API en dos frases."}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
final_message = stream.get_final_message()
print("\nstop_reason:", final_message.stop_reason)No concatentes todos los eventos como si fueran texto: también pueden aparecer eventos de inicio, delta, thinking, uso o herramientas. Utiliza el parser del SDK, gestiona cortes de conexión y no presentes una respuesta parcial como completa si no recibes el final del mensaje.
Uso seguro de herramientas
- Declara cada herramienta con un nombre estable, una descripción precisa y un
input_schemarestrictivo. - Cuando llegue un bloque
tool_use, valida su nombre y argumentos contra una lista permitida. - Solicita autorización para acciones sensibles, aplica límites de tiempo y ejecuta con los privilegios mínimos.
- Devuelve el resultado como
tool_resultasociado al ID correcto. - Reenvía el historial completo necesario y continúa hasta una respuesta final o un límite de iteraciones definido por tu aplicación.
La API propone una llamada; no ejecuta por sí sola una función local. Nunca conviertas argumentos generados en comandos de shell, consultas destructivas, pagos o escrituras de producción sin validación determinista y autorización explícita. Establece un máximo de pasos para evitar bucles.
Uso correcto de metadata.user_id
DeepSeek admite metadata.user_id con un máximo de 512 caracteres y los caracteres a-z, A-Z, 0-9, guion y guion bajo, según su guía de Rate Limit & Isolation. Usa un identificador seudónimo interno; no envíes correo, teléfono, nombre, dirección ni otro dato personal. Los demás campos de metadata se ignoran según la matriz publicada.
Errores, diagnóstico y reintentos
| Estado | Causa documentada habitual | Respuesta recomendada |
|---|---|---|
| 400 | Formato incorrecto. | Revisar cuerpo, Base URL, bloques y tipos; no repetir sin corregir. |
| 401 | Autenticación fallida. | Comprobar que la clave procede de DeepSeek y sigue activa. |
| 402 | Saldo insuficiente. | Revisar saldo y facturación en DeepSeek Platform. |
| 422 | Parámetros inválidos. | Comparar modelo y campos con la matriz vigente. |
| 429 | Demasiadas solicitudes. | Reducir concurrencia, poner en cola y esperar. |
| 500 o 503 | Fallo temporal del servidor. | Aplicar reintentos limitados con espera exponencial y aleatoria. |
Registra un ID interno, estado HTTP, modelo, duración, stop_reason y uso, pero elimina la clave, el prompt sensible y los datos personales. Define un máximo de intentos y evita reintentar automáticamente un 400, 401 o 422 que requiere corrección. Consulta la guía de códigos de error de DeepSeek API y el estado oficial del servicio.
Seguridad, privacidad y coste
- Envía solo el contexto necesario y elimina secretos antes de construir el mensaje.
- Mantén la clave en el servidor o en un gestor de secretos; rota cualquier clave expuesta.
- Valida la salida antes de mostrarla, ejecutarla o guardarla.
- Separa los permisos de lectura, escritura, red y ejecución de herramientas.
- Controla tokens de entrada, salida, thinking, caché y búsquedas para limitar el gasto.
- No prometas retención cero, ausencia de entrenamiento o residencia en España si no está garantizado por las condiciones y el contrato aplicables.
El paquete de Anthropic es el cliente, pero la Base URL dirige el contenido a DeepSeek y el consumo se factura según las tarifas de DeepSeek API. Consulta las tarifas explicadas en español, confirma el precio vigente en la tabla oficial y revisa las condiciones de Open Platform y la política de privacidad antes de enviar datos de terceros.
Anthropic SDK, Claude Code o FIM: cuál elegir
| Opción | Úsala cuando | No la confundas con |
|---|---|---|
| Anthropic SDK | Tu aplicación ya utiliza el formato Messages o sus utilidades de streaming y tools. | Paridad completa con la plataforma de Anthropic. |
| DeepSeek con Claude Code | Necesitas un agente de terminal que inspeccione un proyecto y coordine herramientas bajo permisos. | Una integración respaldada por Anthropic para modelos no Claude. |
| FIM Completion | Debes completar un hueco exacto entre un prefijo y un sufijo. | Messages o un agente que modifique archivos por sí solo. |
Preguntas frecuentes
¿Necesito una clave de Anthropic?
No para este endpoint. Configura el SDK con una clave creada en DeepSeek Platform y la Base URL de DeepSeek. No mezcles credenciales de proveedores distintos.
¿Debo añadir /v1 a la Base URL?
No. Utiliza https://api.deepseek.com/anthropic. El SDK construye la ruta de Messages a partir de esa base.
¿Debo escribir deepseek-v4-pro[1m]?
No en una llamada directa con Anthropic SDK. Usa deepseek-v4-pro. [1m] es una convención documentada para determinadas configuraciones de Claude Code.
¿Puedo enviar imágenes o PDF?
No mediante los bloques Anthropic image o document de este endpoint, porque DeepSeek los marca como no admitidos.
¿Funciona cache_control?
El campo se ignora. DeepSeek utiliza una caché automática de prefijos en modo best effort; comprueba el uso devuelto en vez de asumir un acierto.
¿Puedo usar deepseek-chat o deepseek-reasoner?
No en una integración actual. El plazo oficial de retirada ya terminó y la lista vigente solo muestra deepseek-v4-flash y deepseek-v4-pro.
Fuentes oficiales verificadas
- DeepSeek: Anthropic API compatibility.
- DeepSeek: List Models.
- DeepSeek V4 Preview Release y retirada de aliases.
- DeepSeek: Thinking Mode.
- DeepSeek: Context Caching.
- DeepSeek: Rate Limit & Isolation.
- DeepSeek: Error Codes.
- Anthropic: SDK oficial para TypeScript.
- Anthropic: SDK oficial para Python.
- DeepSeek Open Platform Terms of Service.
Guías relacionadas: DeepSeek con Claude Code · FIM Completion · DeepSeek API en español · Precios de DeepSeek API.