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 actualización documental: 24 de agosto de 2026. Los ejemplos no contienen una clave real. Esta actualización no ejecutó una prueba nueva; la captura del 25 de julio se conserva como registro histórico.
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; no añadas /v1. Declara deepseek-v4-flash, deepseek-v4-pro o deepseek-v4-flash-vision-exp. Las imágenes funcionan únicamente con Vision Exp y los bloques document 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-flash, deepseek-v4-pro y deepseek-v4-flash-vision-exp |
| 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 |
Captura histórica — 25 de julio de 2026. La imagen siguiente conserva la matriz publicada ese día. Es anterior a Pro-0813 y Vision Exp, no representa por sí sola la compatibilidad vigente y no valida funciones añadidas después.
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 en model | Estado y entrada |
|---|---|
deepseek-v4-flash | DeepSeek-V4-Flash-0731; texto |
deepseek-v4-pro | DeepSeek-V4-Pro-0813; GA desde el 13/08/2026; texto |
deepseek-v4-flash-vision-exp | Experimental desde el 21/08/2026; texto e imágenes |
Los tres admiten 1M de contexto, hasta 384K de salida, JSON, Tool Calls, Responses, Anthropic y Codex. Usa IDs explícitos para que una migración sea auditable; el sufijo [1m] no forma parte del ID directo de API.
A 24 de agosto de 2026, deepseek-chat y deepseek-reasoner están fuera del catálogo oficial actual y ya pasó la fecha de retirada anunciada. Las fuentes vigentes no documentan qué respuesta devuelven hoy; no afirmamos que funcionen ni que fallen sin una llamada autenticada actual. Utiliza los IDs explícitos Flash, Pro o Vision Exp en código nuevo y migra cualquier configuración heredada.
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; image únicamente con deepseek-v4-flash-vision-exp. |
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:
- En
/messages,anthropic-versionse ignora yanthropic-betano activa funciones beta de forma general. Existe una excepción documentada para imágenes referenciadas mediante Files API, explicada en la sección siguiente. 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. La excepción files-api-2025-04-14 sirve únicamente para el flujo de Files API documentado; no habilita por sí sola otros tipos de contenido. 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 compatible y no compatible
| Elemento | Estado | Implicación |
|---|---|---|
Bloques image | Admitidos de forma condicional | Solo deepseek-v4-flash-vision-exp procesa imágenes. source.type puede ser base64, url o file; la variante file requiere anthropic-beta: files-api-2025-04-14. Flash y Pro son modelos de texto. |
Bloques document | No admitidos | Extraiga el texto necesario o convierta páginas autorizadas en imágenes; no presente un PDF como bloque documental compatible. |
search_result | No admitido | Adapte el flujo antes de sustituir otro tipo de resultado |
redacted_thinking | No admitido | No espere paridad con bloques redactados |
code_execution_tool_result | No admitido | Ejecute código en su propia aplicación y con permisos explícitos |
mcp_tool_use y mcp_tool_result | No admitidos | Tools estándar no implican MCP administrado |
container_upload | No admitido | No envíe archivos mediante este tipo |
Si una función no aparece en la matriz vigente, trátela como no confirmada hasta que exista documentación oficial o una prueba controlada.
Imágenes, Files API y documentos
Compatibilidad documental revisada el 24 de agosto de 2026; no se realizó una carga ni una llamada nueva. La matriz Anthropic vigente incluye image entre los bloques admitidos. La entrada visual funciona únicamente con deepseek-v4-flash-vision-exp; source.type puede ser base64, url o file. Flash y Pro son modelos de texto, y el bloque document continúa sin estar admitido.
En un mensaje user, image.source.type puede ser base64, url o file. Los dos primeros envían la imagen inline o mediante una URL HTTP/HTTPS. file referencia un file_id creado previamente con Files API bajo la misma API key.
{
"type": "image",
"source": {
"type": "file",
"file_id": "file-api-..."
}
}Cuando source.type es file, la solicitud a /messages debe incluir anthropic-beta: files-api-2025-04-14. La variante Anthropic de Files API utiliza endpoints bajo /anthropic/v1/files y exige la misma cabecera. No se documenta esa cabecera como requisito para texto ni para imágenes enviadas mediante base64 o url.
Files API admite JPEG, PNG, GIF y WebP para Vision Exp; no convierte un PDF en contenido compatible. Los bloques Anthropic document siguen sin estar admitidos. Para un PDF, extrae el texto fuera de DeepSeek o convierte únicamente las páginas autorizadas a imágenes compatibles, aplicando límites, permisos y una política de eliminación.
Consulta la guía oficial de Vision y la guía oficial de Files API antes de desplegar este flujo.
Thinking, esfuerzo y caché
Los niveles nativos actuales son low, high y max. El mapeo es low→low, medium→high, high→high, xhigh→high y max→max. budget_tokens se ignora; no prometa que otra escala conserva exactamente su semántica.
Cuando una respuesta con thinking solicita herramientas, conserva y reenvía todos los bloques del mensaje del asistente. No muestres ni registres razonamiento interno como si fuera una explicación revisada.
La caché de prefijos se activa automáticamente y funciona en modo best effort. Mide los contadores reales; no presupongas un acierto garantizado.
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?
Puedes enviar imágenes únicamente con deepseek-v4-flash-vision-exp: mediante base64, una URL HTTP/HTTPS o un file_id de Files API. El último método requiere anthropic-beta: files-api-2025-04-14. Flash y Pro no admiten entrada visual. Los bloques document, incluidos los PDF enviados como documento, no están 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 los utilices en una integración nueva. Están fuera del catálogo oficial actual y ya pasó la fecha de retirada anunciada, pero las fuentes vigentes no documentan su respuesta operativa de hoy. Usa deepseek-v4-flash, deepseek-v4-pro o deepseek-v4-flash-vision-exp.
Fuentes oficiales verificadas
- DeepSeek: Anthropic API compatibility.
- DeepSeek: Updates.
- DeepSeek: Vision.
- DeepSeek: Files API.
- 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.
Registro de actualización — 23 de agosto de 2026: se añadieron Pro-0813 y Vision Exp, se corrigió el soporte de imágenes y se actualizó el mapeo de razonamiento. No se realizó una prueba nueva.
Registro de actualización — 24 de agosto de 2026: se documentaron Files API, source.type=file y la excepción específica de anthropic-beta; también se matizó el estado operativo no verificado de los aliases antiguos. No se realizó una llamada API.