API de DeepSeek en español: modelos, precios y guía

Última actualización documental: 24 de agosto de 2026. La guía refleja los tres modelos actuales y su compatibilidad vigente. Las pruebas prácticas del 5 y 11 de agosto se conservan como registros históricos, sin repetir solicitudes, atribuir sus resultados a modelos posteriores ni recalcular sus costes.

La DeepSeek API permite integrar deepseek-v4-flash, deepseek-v4-pro y deepseek-v4-flash-vision-exp desde un servidor. Esta guía cubre autenticación, Chat Completions, Responses, Anthropic, Vision, thinking, FIM, streaming, JSON, herramientas, caché, costes y diagnóstico sin exponer la clave.

Aviso de independencia: DeepSeek Español es un sitio independiente operado por Ahmed Aly. No es la documentación oficial, no pertenece a DeepSeek y no está afiliado ni respaldado por la empresa. Esta página no vende API keys. Los enlaces para crear una cuenta o una clave conducen a la plataforma oficial de DeepSeek.

Respuesta rápida: cree la clave en la página oficial de API keys, guárdela solo en un backend o gestor de secretos y use https://api.deepseek.com como base URL. El catálogo actual documenta deepseek-v4-flash, deepseek-v4-pro y deepseek-v4-flash-vision-exp. La consulta autenticada del 11 de agosto que devolvió solo dos IDs es histórica y no describe el catálogo posterior.

Contenido de la guía

• Referencia rápida y modelos disponibles
• Cómo crear y proteger una API key
• Prueba real de la API key: modelos, error 401 y primera respuesta
• Primera solicitud con cURL
• Integración con Node.js
• Integración con Python
• Parámetros y corrección sobre penalties
• Thinking, razonamiento y conversaciones
• Streaming
• Responses API y compatibilidad
• Files API para imágenes reutilizables
• JSON Output
• Tool Calls
• FIM y Chat Prefix Completion (Beta)
• Context Caching y user_id
• Concurrencia y errores
• Precios actuales
• Formato Anthropic
• Migración de aliases antiguos
• Seguridad para producción
• Preguntas frecuentes

Referencia rápida de DeepSeek API

Elemento	Valor vigente
Base URL, formato OpenAI	https://api.deepseek.com
Endpoint de chat	https://api.deepseek.com/chat/completions
Base URL, formato Anthropic	https://api.deepseek.com/anthropic
Modelos actuales	deepseek-v4-flash, deepseek-v4-pro y deepseek-v4-flash-vision-exp
Versiones	DeepSeek-V4-Flash-0731; DeepSeek-V4-Pro-0813 GA desde el 13/08; Vision Exp experimental desde el 21/08
Responses API	Admitida por los tres modelos
Entrada	Flash y Pro: texto. Vision Exp: texto e imágenes
Contexto / salida máxima	1M / 384K en los tres modelos
Razonamiento	low, high y max
FIM	Flash y Pro en non-thinking; Vision Exp no
Files API	JPEG, PNG, GIF y WebP para Vision Exp mediante file_id
Autenticación	Authorization: Bearer API_KEY

Los tres modelos admiten JSON, Tool Calls, Responses API, la interfaz Anthropic y Codex. La compatibilidad de protocolo no implica paridad total de endpoints o comportamiento. Los bloques de imagen requieren Vision Exp; los bloques document de Anthropic no están admitidos.

Prueba real de Chat Completions en español

El 5 de agosto de 2026, una consulta autenticada a GET /models devolvió únicamente deepseek-v4-flash y deepseek-v4-pro. Después se ejecutaron 16 solicitudes a POST /chat/completions: cuatro tareas en español, dos modelos y dos ejecuciones independientes por combinación, con thinking desactivado y max_tokens=450.

• 16 de 16 solicitudes devolvieron HTTP 200 y finish_reason=stop.
• 12 resultados cumplieron completamente la rúbrica y cuatro fueron parciales.
• Flash consumió 1.365 tokens y Pro 1.339 tokens en el conjunto completo.
• En ese conjunto del 5 de agosto no se probaron thinking, aliases retirados, búsqueda web, archivos ni datos personales. Responses API se comprobó por separado el 11 de agosto, como se detalla más abajo.

La metodología completa, los prompts exactos y las limitaciones están publicados en la página principal. Nunca incluya una API key en una captura o en el contenido público.

¿Flash, Pro o Vision Exp?

Modelo	Cuándo evaluarlo	Modalidad
deepseek-v4-flash	Coste, volumen, razonamiento y agentes	Texto; Responses y Codex
deepseek-v4-pro	Cuando una evaluación propia justifique mayor capacidad o coste	Texto; Responses y Codex
deepseek-v4-flash-vision-exp	Cuando la entrada incluya imágenes	Texto e imágenes; experimental

No elija solo por el nombre. Compare precisión, latencia, tokens y coste con casos reales. Para capacidades y versiones, consulte la guía de DeepSeek V4.

Cómo crear y proteger una API key

1. Abra la página oficial de API keys de DeepSeek y cree o inicie sesión en su cuenta.
2. Pulse Create new API key, asigne un nombre que identifique el proyecto y copie el secreto en ese momento: la plataforma solo lo muestra una vez.
3. Guárdela en un gestor de secretos o variable de entorno; no la incluya en el código fuente.
4. Confirme que la cuenta dispone de saldo utilizable.
5. Haga las llamadas desde su backend. No exponga la clave en JavaScript del navegador, WordPress público, una aplicación móvil distribuida ni una captura de pantalla.

Ejemplos temporales para una sesión local; no los publique ni los guarde en el historial compartido:

# macOS o Linux
export DEEPSEEK_API_KEY="sustituir-por-la-clave-real"

# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sustituir-por-la-clave-real"

En producción, limite quién puede leer el secreto, rote la clave si se filtra y evite registrar cabeceras de autorización. El archivo .env tampoco debe subirse al repositorio.

Prueba real de una API key: modelos, error 401 y primera respuesta

El 11 de agosto de 2026 a las 11:58 UTC creamos una clave dedicada en la plataforma oficial. El secreto solo permaneció en memoria durante la sesión. No se escribió en archivos, código, capturas ni esta página. Antes y después se consultó GET /user/balance y el endpoint respondió HTTP 200; no publicamos los valores financieros de la cuenta.

Comprobación	Resultado observado	Tiempo de esta sesión
GET /models con la clave válida	HTTP 200; deepseek-v4-flash y deepseek-v4-pro	309 ms
GET /models con una clave ficticia	HTTP 401; authentication_error	272 ms
POST /chat/completions	HTTP 200; respuesta exacta OK; finish_reason=stop	1.078 ms

La solicitud de chat usó deepseek-v4-flash, thinking desactivado, temperature=0, max_tokens=8, stream=false y el prompt «Responde exactamente con la palabra OK». No hubo reintentos. La respuesta informó 20 tokens de entrada sin caché y un token de salida; con las tarifas publicadas ese día, el coste calculado fue US$0,00000308.

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "system", "content": "Responde exactamente con la palabra OK." },
    { "role": "user", "content": "Confirma que la API funciona." }
  ],
  "thinking": { "type": "disabled" },
  "max_tokens": 8,
  "temperature": 0,
  "stream": false,
  "user_id": "deepseek_espanol_api_test_20260811"
}

Límites: es una comprobación funcional de una cuenta, una clave, una ubicación de red y un momento concretos; no es un benchmark de calidad, disponibilidad ni latencia. La documentación revisada no ofrece un límite rígido de gasto por API key. Para producción, aplique cuotas y alertas en su backend, revise el uso por clave y detenga las solicitudes cuando alcancen su presupuesto.

Primera solicitud con cURL

Este ejemplo usa V4 Flash en modo non-thinking. Declarar el modo de forma explícita evita depender del valor predeterminado.

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "system",
        "content": "Responde en español de forma breve, precisa y verificable."
      },
      {
        "role": "user",
        "content": "Explica en dos frases qué devuelve una API REST."
      }
    ],
    "thinking": {
      "type": "disabled"
    },
    "max_tokens": 400,
    "stream": false
  }'

En una respuesta normal, el texto final se encuentra en choices[0].message.content. Revise también finish_reason: un valor length indica que la salida o el contexto alcanzaron un límite y el contenido puede estar incompleto.

Integración con Node.js

Instale el SDK de OpenAI, cuyo formato puede utilizarse con la base URL de DeepSeek:

npm install openai
npm pkg set type=module

Guarde el ejemplo como deepseek-example.js. El comando anterior declara el proyecto como ESM para que import funcione en Node.js:

import OpenAI from "openai";

const apiKey = process.env.DEEPSEEK_API_KEY;

if (!apiKey) {
  throw new Error("Falta la variable DEEPSEEK_API_KEY");
}

const client = new OpenAI({
  apiKey,
  baseURL: "https://api.deepseek.com",
  timeout: 60_000,
  maxRetries: 2,
});

async function main() {
  const response = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "system",
        content: "Eres un asistente técnico. Responde en español.",
      },
      {
        role: "user",
        content: "Resume tres ventajas de guardar secretos fuera del código.",
      },
    ],
    thinking: {
      type: "disabled",
    },
    max_tokens: 600,
    stream: false,
  });

  const choice = response.choices[0];
  const content = choice?.message?.content;

  if (!content) {
    throw new Error(`Respuesta sin contenido. finish_reason=${choice?.finish_reason}`);
  }

  console.log(content);
}

main().catch((error) => {
  console.error(error instanceof Error ? error.message : "Error desconocido");
  process.exitCode = 1;
});

En un servicio real, añada una cola, un límite de gasto por usuario y registros que excluyan prompts sensibles, la API key y el razonamiento. Los reintentos deben ser limitados y reservarse para fallos transitorios; no reenvíe indefinidamente una solicitud inválida.

Integración con Python

pip install openai

En el SDK de OpenAI para Python, la documentación de DeepSeek indica que thinking y user_id deben enviarse dentro de extra_body.

import os
from openai import OpenAI

api_key = os.environ.get("DEEPSEEK_API_KEY")

if not api_key:
    raise RuntimeError("Falta la variable DEEPSEEK_API_KEY")

client = OpenAI(
    api_key=api_key,
    base_url="https://api.deepseek.com",
    timeout=60.0,
    max_retries=2,
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {
            "role": "system",
            "content": "Eres un asistente técnico. Responde en español.",
        },
        {
            "role": "user",
            "content": "Propón una estrategia breve para probar una API antes de producción.",
        },
    ],
    reasoning_effort="high",
    extra_body={
        "thinking": {"type": "enabled"},
        "user_id": "tenant_42_user_781",
    },
    max_tokens=1200,
    stream=False,
)

choice = response.choices[0]
content = choice.message.content

if not content:
    raise RuntimeError(
        f"Respuesta sin contenido. finish_reason={choice.finish_reason}"
    )

print(content)

user_id debe ser un identificador interno pseudónimo. No use nombre, correo, teléfono, IP ni otro dato personal como identificador.

Parámetros principales y su efecto real

Corrección importante: frequency_penalty y presence_penalty están obsoletos y no producen efecto en ningún modo. No es una limitación exclusiva de thinking. En cambio, temperature y top_p siguen apareciendo como parámetros de muestreo para non-thinking, pero son aceptados sin efecto cuando thinking está activado.

Parámetro	Uso actual	Comportamiento
model	Obligatorio	Use deepseek-v4-flash, deepseek-v4-pro o deepseek-v4-flash-vision-exp.
messages	Obligatorio	Historial que la aplicación envía en la solicitud actual.
thinking	Admitido	enabled o disabled; el valor predeterminado es enabled.
reasoning_effort	Thinking	Valores nativos: low, high y max.
max_tokens	Admitido	Limita la generación; entrada y salida deben caber dentro del contexto.
temperature	Muestreo	Rango documentado de 0 a 2; no tiene efecto en thinking.
top_p	Muestreo	Alternativa a temperature; no tiene efecto en thinking.
frequency_penalty	Obsoleto	No tiene efecto en thinking ni en non-thinking.
presence_penalty	Obsoleto	No tiene efecto en thinking ni en non-thinking.
response_format	Admitido	{"type":"json_object"} activa JSON Output.
stream	Admitido	Envía deltas mediante Server-Sent Events.
tools	Admitido	Funciones que el modelo puede proponer; la aplicación las valida y ejecuta.
tool_choice	Admitido	none, auto, required o una función concreta.
user_id	Opcional	Aislamiento de seguridad de contenido, KVCache y programación; no es autenticación.

El mapeo vigente es low→low, medium→high, high→high, xhigh→high y max→max.

Thinking, esfuerzo y conversaciones

Flash, Pro y Vision Exp admiten los niveles nativos low, high y max. Declare el modo y el esfuerzo en cada flujo y compruebe el comportamiento de su cliente.

Valor solicitado	Nivel aplicado
low	low
medium	high
high	high
xhigh	high
max	max

El mapeo es low→low, medium→high, high→high, xhigh→high y max→max.

Activar thinking

{
  "thinking": {
    "type": "enabled"
  },
  "reasoning_effort": "high"
}

Desactivar thinking

{
  "thinking": {
    "type": "disabled"
  }
}

Cuando thinking está activo, el razonamiento se devuelve en reasoning_content y la respuesta final en content. No trate reasoning_content como una explicación verificable del funcionamiento interno ni lo registre o muestre automáticamente al usuario.

Conversación de varios turnos

La solicitud incluye los mensajes que el modelo debe considerar. La aplicación debe conservar y reenviar el historial útil; el endpoint no añade por sí solo los turnos anteriores. Esto describe la construcción del contexto y no demuestra ausencia de logs, cache o retención del proveedor.

• Si una solicitud no incluye el parámetro tools, el reasoning_content de respuestas anteriores no necesita formar parte del turno siguiente; si se reenvía, la API lo ignora.
• Si una solicitud incluye tools, conserve en el historial el mensaje completo del asistente, incluido reasoning_content, y reenvíelo en todas las solicitudes posteriores de la conversación, incluso cuando el modelo no haya producido una tool_call en esa ronda. Omitirlo puede devolver HTTP 400. Esta regla no obliga a mostrar ni conservar permanentemente el razonamiento en los registros de la aplicación.
• Recorte el historial con una estrategia comprobada para no superar la ventana de contexto ni conservar datos innecesarios.

Streaming con Node.js

Con stream: true, la API envía deltas mediante SSE y finaliza con data: [DONE]. Este ejemplo acumula por separado el razonamiento y la respuesta, pero solo muestra la respuesta final:

const stream = await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [
    {
      role: "user",
      content: "Propón un plan breve para migrar una API sin interrumpir el servicio.",
    },
  ],
  thinking: {
    type: "enabled",
  },
  reasoning_effort: "high",
  stream: true,
  stream_options: {
    include_usage: true,
  },
});

let reasoningContent = "";
let finalContent = "";

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;

  if (delta?.reasoning_content) {
    reasoningContent += delta.reasoning_content;
  }

  if (delta?.content) {
    finalContent += delta.content;
  }
}

// No registre reasoningContent ni lo envíe al cliente por defecto.
process.stdout.write(finalContent);

Mientras una solicitud espera, el servidor puede enviar líneas vacías en non-streaming o comentarios : keep-alive en streaming. Si implementa su propio parser, debe ignorarlos correctamente. DeepSeek también indica que el servidor puede cerrar la conexión si la inferencia no ha comenzado después de diez minutos; configure timeouts coherentes en cliente, proxy y balanceador.

Responses API de DeepSeek: soporte y ejemplo

Responses API utiliza la base https://api.deepseek.com y admite actualmente Flash, Pro y Vision Exp. Pro-0813 también admite Codex; Vision Exp acepta texto e imágenes mediante Responses y Codex.

Para configurar este endpoint como proveedor, consulta la guía de DeepSeek con Codex.

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
response = client.responses.create(
    model="deepseek-v4-flash",
    instructions="Responde en español de forma breve y verificable.",
    input="Explica dos diferencias entre autenticación y autorización.",
)
print(response.output_text)

Campo o función	Estado vigente	Implicación
Flash, Pro y Vision Exp	Admitidos	Use el ID explícito que corresponda
Imágenes	Solo con Vision Exp	Flash y Pro son modelos de texto
document	No admitido	No envíe PDF como bloque de documento Anthropic
previous_response_id y conversation	No admitidos	La aplicación conserva el historial necesario
store y background	No admitidos	No dependa de almacenamiento o ejecución diferida
Herramientas	Compatibilidad parcial	Las llamadas function y apply_patch se ejecutan en la aplicación; web_search y web_search_2025_08_26 se ejecutan en los servidores de DeepSeek

El streaming usa eventos semánticos y termina con response.completed, response.incomplete o response.failed. Un HTTP 200 no prueba que un campo no admitido haya tenido efecto.

Búsqueda web en Responses API

Responses API admite actualmente web_search y web_search_2025_08_26, ejecutadas en los servidores de DeepSeek. Pueden declararse dentro de tools y seleccionarse mediante tool_choice; no deben confundirse con una función local ni con las Tool Calls de Chat Completions. Los campos search_context_size y user_location se aceptan, pero se ignoran, y la continuación automática del lado del servidor está limitada a diez rondas.

La búsqueda no convierte el resultado en una fuente verificada. Limite el alcance, valide la información recuperada y controle tokens, tiempo y presupuesto. Actualización documental del 24 de agosto de 2026: no se ejecutó una búsqueda ni una nueva solicitud facturable para esta página.

Files API para imágenes reutilizables

Estado documental revisado el 24 de agosto de 2026; no se ejecutó una carga de archivos. Para una sola solicitud, Vision Exp admite una imagen mediante URL HTTPS o data URL en base64. Files API añade una tercera vía: subir JPEG, PNG, GIF o WebP con POST /files y purpose=user_data, y reutilizar después su file_id con deepseek-v4-flash-vision-exp. No es una vía documentada para enviar PDF ni bloques document.

Límites de imágenes en una solicitud

Elemento	Límite documentado
Cuerpo completo de la solicitud	48 MiB
Una imagen en base64 o mediante URL externa	32 MiB
Una imagen mediante file_id	64 MiB
Imágenes por solicitud	Hasta 600
Tamaño total de imágenes	64 MiB sin imágenes file_id; hasta 200 MiB cuando se incluyen
Dimensión máxima	8192 px por lado; 4096 px por lado cuando la solicitud contiene 15 imágenes o más

Las imágenes se facturan como tokens de entrada y cada una tiene un máximo de 384 tokens después del redimensionado automático. En entradas image_url, detail=low reduce la imagen a 512×512; high equivale a original, y auto equivale actualmente a original. Las imágenes solo se admiten en mensajes user; enviarlas en mensajes system o assistant devuelve un error 400.

Use file_id cuando reutilice una imagen o cuando supere el límite inline de 32 MiB; un archivo subido puede tener hasta 64 MiB y la carga debe completarse en 10 minutos. Los archivos pertenecen a la API key que los creó y pueden listarse, consultarse o eliminarse. Puede fijar una caducidad de 1 hora a 30 días; si omite expires_after, la documentación indica que el archivo permanece hasta eliminarlo. Revise retención, permisos y borrado antes de usar datos sensibles.

from openai import OpenAI

client = OpenAI(
    api_key="<DEEPSEEK_API_KEY>",
    base_url="https://api.deepseek.com",
)

with open("grafico.png", "rb") as image:
    uploaded = client.files.create(file=image, purpose="user_data")

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe el gráfico y cita las etiquetas visibles."},
            {"type": "file", "file_id": uploaded.id},
        ],
    }],
)

Elemento	Límite documentado
Formatos	JPEG, PNG, GIF y WebP
Tamaño máximo por archivo	64 MiB
Almacenamiento por usuario	25 GiB
Número máximo de archivos	10.000
Caducidad opcional	1 hora a 30 días; sin expires_after, permanece hasta eliminarlo

La variante compatible con Anthropic usa los endpoints bajo /anthropic/v1/files y requiere la cabecera anthropic-beta: files-api-2025-04-14. Consulte la guía oficial de Files API y la guía oficial de Vision antes de desplegar.

JSON Output: configuración y validación

Para pedir JSON válido, establezca response_format, incluya la palabra “json” en el prompt, muestre una estructura esperada y reserve suficientes tokens. No confunda JSON válido con datos correctos o autorizados.

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    {
      role: "system",
      content:
        'Devuelve solo un objeto json. Ejemplo: {"tema":"API","nivel":"básico"}.',
    },
    {
      role: "user",
      content: "Clasifica este tema: autenticación mediante tokens.",
    },
  ],
  response_format: {
    type: "json_object",
  },
  thinking: {
    type: "disabled",
  },
  max_tokens: 300,
});

const raw = response.choices[0]?.message?.content;

if (!raw) {
  throw new Error("JSON vacío: revisar el prompt antes de reintentar");
}

const data = JSON.parse(raw);

if (
  typeof data.tema !== "string" ||
  typeof data.nivel !== "string"
) {
  throw new Error("El JSON no cumple la estructura esperada");
}

console.log(data);

La documentación avisa de que JSON Output puede devolver contenido vacío ocasionalmente. Compruebe además finish_reason; si es length, el objeto puede estar truncado. Valide tipos, enumeraciones, tamaños, permisos y reglas de negocio antes de usar los datos. Nunca convierta una cadena generada directamente en SQL, comandos del sistema o acciones externas.

Tool Calls: el modelo propone, la aplicación decide

Tool Calls permite que el modelo proponga una función y sus argumentos. El modelo no ejecuta la función por sí mismo. Su backend debe validar la llamada, comprobar permisos, ejecutar la herramienta y devolver el resultado como mensaje con rol tool.

const tools = [
  {
    type: "function",
    function: {
      name: "buscar_pedido",
      description: "Busca un pedido autorizado por su identificador.",
      parameters: {
        type: "object",
        properties: {
          id_pedido: {
            type: "string",
            description: "Identificador interno del pedido.",
          },
        },
        required: ["id_pedido"],
        additionalProperties: false,
      },
    },
  },
];

1. Envíe las definiciones permitidas junto con los mensajes.
2. Compruebe si la respuesta contiene tool_calls.
3. Valide nombre, argumentos, esquema y permisos del usuario.
4. Ejecute la función con timeout, allowlist y límites propios.
5. Añada el resultado como mensaje tool asociado a tool_call_id.
6. Solicite al modelo la respuesta final.

El modo strict sigue marcado como Beta. Requiere https://api.deepseek.com/beta, strict: true en todas las funciones y un subconjunto compatible de JSON Schema. Aunque el esquema sea estricto, la aplicación debe continuar verificando autorización y reglas de negocio.

FIM y Chat Prefix Completion (Beta)

Fill-in-the-Middle (FIM) completa texto a partir de un prefijo y, opcionalmente, un sufijo mediante POST /beta/completions. Chat Prefix Completion fuerza el comienzo de una respuesta de chat marcando el último mensaje del asistente con prefix: true. Ambas funciones están en Beta y utilizan https://api.deepseek.com/beta. El endpoint FIM Beta admite como máximo 4K tokens de salida; el límite de 384K publicado para V4 corresponde a Chat Completions, no a FIM. Pruebe de nuevo estas funciones antes de utilizarlas como dependencia de producción.

Compatibilidad vigente: FIM está disponible con deepseek-v4-flash y deepseek-v4-pro únicamente en non-thinking. deepseek-v4-flash-vision-exp no admite FIM. El ejemplo conserva Pro, pero Flash también está admitido.

curl https://api.deepseek.com/beta/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-pro",
    "prompt": "def fibonacci(n):\n    ",
    "suffix": "\n\nprint(fibonacci(10))",
    "max_tokens": 160
  }'

• FIM está documentado para non-thinking; no añada parámetros de Thinking a esta solicitud.
• Trate la salida como texto no confiable: revise sintaxis, permisos, dependencias y pruebas antes de ejecutarla.
• Las funciones Beta pueden cambiar; registre el modelo y valide el comportamiento en cada actualización.

Context Caching y aislamiento con user_id

El Context Caching en disco está activado por defecto para los usuarios de la API. DeepSeek persiste unidades de prefijo en límites de solicitudes, al detectar prefijos comunes y en intervalos de tokens para textos largos. Una solicitud posterior consigue un hit cuando coincide por completo con una unidad ya persistida.

• usage.prompt_cache_hit_tokens: tokens de entrada recuperados del cache.
• usage.prompt_cache_miss_tokens: tokens de entrada que no produjeron un hit.
• El cache funciona con criterio best effort y no garantiza un porcentaje de hits.
• Su construcción puede tardar segundos.
• Cuando deja de utilizarse, la documentación indica que normalmente se elimina en unas horas o unos días.
• El cache reutiliza el prefijo de entrada; la salida vuelve a generarse.

Límite de esta afirmación: el plazo de horas o días se refiere al Context Caching en disco descrito en esa guía. No debe presentarse como una política general de retención para todos los logs, datos de cuenta u otros tratamientos de la API.

Cómo usar user_id

user_id admite los caracteres [a-zA-Z0-9\-_]+ y un máximo de 512 caracteres. DeepSeek lo documenta para aislamiento de seguridad de contenido, KVCache y programación.

• No incluya datos personales.
• No lo utilice como sustituto de autenticación, autorización o aislamiento de base de datos.
• Para cuentas API normales, todos los valores de user_id se combinan al calcular la concurrencia.
• En cuentas con concurrencia ampliada, pueden aplicarse además límites por user_id, sin eliminar el límite total de la cuenta.

Límites de concurrencia y códigos de error

Modelo	Límite de concurrencia por cuenta
deepseek-v4-flash	2.500
deepseek-v4-pro	500
deepseek-v4-flash-vision-exp	2.500

Una solicitud cuenta como conexión concurrente desde que se envía hasta que termina la respuesta. El cálculo se realiza a nivel de cuenta, independientemente de cuántas API keys existan. Superar el límite devuelve HTTP 429; crear más claves no multiplica la capacidad. Límites y comportamiento revisados el 24 de agosto de 2026 en la referencia oficial de rate limits.

Código	Causa documentada	Acción inicial
400	Formato inválido	Leer el mensaje y corregir el cuerpo.
401	Autenticación fallida	Comprobar API key y cabecera.
402	Saldo insuficiente	Revisar balance y facturación.
422	Parámetros inválidos	Corregirlos; no repetir la misma solicitud.
429	Límite alcanzado o solicitudes demasiado rápidas	Reducir concurrencia, poner en cola y esperar.
500	Error del servidor	Reintento limitado tras una espera breve.
503	Servidor sobrecargado	Esperar, reintentar de forma limitada o degradar el servicio.

Para 429, 500, 503 y fallos de red transitorios, aplique backoff exponencial con jitter, un máximo de intentos y un presupuesto total de tiempo. Evite duplicar operaciones con efectos secundarios; implemente idempotencia en su propia aplicación. Para diagnóstico detallado, consulte los códigos de error de DeepSeek API.

Precios de DeepSeek API

Tarifas vigentes en USD por 1 millón de tokens, revisadas el 24 de agosto de 2026:

Modelo	Periodo	Cache hit	Cache miss	Output
Flash / Vision Exp	Off-peak	$0.007	$0.22	$0.66
Flash / Vision Exp	Peak	$0.014	$0.44	$1.32
Pro	Off-peak	$0.022	$0.66	$1.98
Pro	Peak	$0.044	$1.32	$3.96

En días laborables, peak corresponde a 01:00–04:00 y 06:00–10:00 UTC; el resto es off-peak. Desde el 23 de agosto, sábados y domingos según la hora de Pekín son off-peak todo el día. Las imágenes de Vision se facturan como tokens de entrada.

coste =
  (prompt_cache_hit_tokens / 1.000.000 × tarifa_hit)
  + (prompt_cache_miss_tokens / 1.000.000 × tarifa_miss)
  + (completion_tokens / 1.000.000 × tarifa_output)

Los tokens de razonamiento ya están incluidos en completion_tokens; no los cobre de nuevo. Use la calculadora y guía de precios para comparar modelo y periodo.

Compatibilidad con el formato Anthropic

DeepSeek ofrece https://api.deepseek.com/anthropic para SDK y herramientas basados en el formato Anthropic. Las respuestas proceden de modelos DeepSeek, no de Claude.

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_API_KEY="${DEEPSEEK_API_KEY}"

• Declare deepseek-v4-flash, deepseek-v4-pro o deepseek-v4-flash-vision-exp explícitamente.
• Texto, system, streaming y tools tienen compatibilidad documentada.
• Los bloques image funcionan únicamente con Vision Exp; Flash y Pro son de texto.
• Los bloques document, incluidos PDF enviados como documento, no están admitidos.
• Los niveles nativos son low, high y max; el mapeo es low→low, medium→high, high→high, xhigh→high y max→max.

Consulte el mapeo de DeepSeek con Anthropic SDK antes de migrar una aplicación completa.

Migración de deepseek-chat y deepseek-reasoner

Registro histórico: DeepSeek anunció la retirada de deepseek-chat y deepseek-reasoner para el 24 de julio de 2026 a las 15:59 UTC. La prueba del 11 de agosto no llamó a esos aliases. El catálogo vigente documenta Flash, Pro y Vision Exp; no diseñe código nuevo alrededor de los nombres retirados.

Alias heredado	Ruta temporal documentada antes del retiro	Sustitución explícita
deepseek-chat	V4 Flash non-thinking	deepseek-v4-flash + thinking disabled
deepseek-reasoner	V4 Flash thinking	deepseek-v4-flash + thinking enabled

1. Busque los aliases en código, variables, paneles, tests, colas y documentación.
2. Seleccione Flash o Pro expresamente.
3. Configure thinking y, si procede, reasoning_effort.
4. Pruebe de nuevo JSON, tools, streaming, cache, calidad y costes.
5. Despliegue y supervise antes de eliminar el fallback.

Si consulta esta guía después del plazo, trate los aliases como retirados salvo que la documentación oficial anuncie un cambio posterior.

Lista de seguridad antes de producción

• API key almacenada solo en backend o gestor de secretos.
• Modelo V4 y modo thinking declarados explícitamente.
• Límites de entrada, salida, concurrencia, tiempo y gasto por usuario.
• Validación de JSON y argumentos de Tool Calls con esquemas propios.
• Allowlists y autorización independiente para herramientas y recursos.
• Logs sin API keys, prompts sensibles, datos personales innecesarios ni razonamiento.
• user_id pseudónimo y separado del control de acceso.
• Cola, backoff, circuit breaker e idempotencia para fallos transitorios.
• Aviso claro de que los mensajes se envían al proveedor de la API.
• Revisión humana en decisiones médicas, jurídicas, financieras, laborales o educativas de alto impacto.
• Identificación clara como contenido generado por IA cuando se publique o distribuya una respuesta.

La documentación pública revisada no especifica para los usuarios finales de aplicaciones de terceros la ubicación exacta de todo el tratamiento, el plazo general de conservación ni si los datos de la API se utilizan para entrenamiento. Verifique estas condiciones en el contrato y la configuración de su cuenta, minimice los datos y explique el flujo en su propia política. Consulte también nuestra guía de seguridad y la Política de privacidad.

Preguntas frecuentes sobre DeepSeek API

¿DeepSeek API es gratis?

La API se factura por tokens de entrada y salida y necesita saldo utilizable. Cualquier crédito promocional o concedido puede cambiar; compruebe su panel y la tabla oficial de precios.

¿DeepSeek API es compatible con OpenAI?

Admite un formato compatible con OpenAI Chat Completions usando https://api.deepseek.com. No implica que todos los endpoints, parámetros o comportamientos sean idénticos.

¿Qué modelo debo elegir?

Empiece evaluando V4 Flash para coste y volumen. Compare V4 Pro en tareas complejas de razonamiento, programación o agentes. Use un conjunto de pruebas propio; no existe una elección universal.

¿Thinking está activado por defecto?

Sí. V4 Flash y V4 Pro admiten ambos modos y el valor predeterminado documentado es enabled. Para evitar ambigüedad, declare el modo explícitamente.

¿presence_penalty y frequency_penalty funcionan en non-thinking?

No. La referencia actual marca los dos parámetros como obsoletos y afirma que no producen efecto al enviarlos. La limitación se aplica a thinking y non-thinking. temperature y top_p son un caso diferente: pueden utilizarse como parámetros de muestreo en non-thinking, pero no tienen efecto en thinking.

¿JSON Output garantiza mi esquema exacto?

Garantiza el objetivo de producir una cadena JSON válida, pero no garantiza que los campos cumplan su esquema o reglas de negocio. DeepSeek también advierte de respuestas vacías ocasionales. Valide siempre el resultado.

¿Puedo llamar a DeepSeek directamente desde el navegador?

No es una arquitectura segura porque expone la API key. Use un backend propio que autentique al usuario, limite el gasto, valide la entrada y reenvíe la solicitud.

¿La API garantiza almacenamiento o retención cero?

No debe afirmarse basándose en la documentación pública revisada. El Context Caching en disco está activado por defecto y su guía describe la eliminación del cache no utilizado normalmente en horas o días, pero esa afirmación no define la retención de todos los datos o logs.

¿Debo seguir usando deepseek-chat o deepseek-reasoner?

No. El plazo de retirada anunciado ya pasó y la documentación operativa solo enumera los IDs V4 explícitos. Migre a deepseek-v4-flash o deepseek-v4-pro y configure thinking de forma explícita. El comportamiento exacto de los aliases antiguos requiere una prueba autenticada todavía no realizada.

Fuentes oficiales verificadas

• DeepSeek: Change Log y Flash-0731
• DeepSeek: Responses API y matriz de compatibilidad
• DeepSeek: Vision
• DeepSeek: integración con Codex
• DeepSeek: Your First API Call
• DeepSeek: Create Chat Completion
• DeepSeek: Models & Pricing
• DeepSeek: Thinking Mode
• DeepSeek: Rate Limit & Isolation
• DeepSeek: JSON Output
• DeepSeek: Tool Calls
• DeepSeek: Chat Prefix Completion (Beta)
• DeepSeek: Create FIM Completion (Beta)
• DeepSeek: Context Caching
• DeepSeek: Anthropic API
• DeepSeek: Error Codes
• DeepSeek V4 Preview Release
• DeepSeek Open Platform Terms of Service
• DeepSeek Privacy Policy

Modelos, precios, modalidades y compatibilidad revisados el 24 de agosto de 2026. Las pruebas del 5 y 11 de agosto permanecen fechadas y no se presentan como verificaciones nuevas.

Registro de actualización — 23 de agosto de 2026: se añadieron Vision Exp y los precios peak/off-peak; se corrigieron Responses para Pro, imágenes en Anthropic y el mapeo de razonamiento.

Registro de actualización — 24 de agosto de 2026: se documentó Files API para imágenes, incluida su variante Anthropic, y se añadió el límite oficial de concurrencia de Vision Exp.