Cómo usar la API DeepSeek V4

DeepSeek V4 se lanzó con la API en vivo desde el primer día. Los ID de modelo son deepseek-v4-pro y deepseek-v4-flash, el endpoint es compatible con OpenAI y la URL base es https://api.deepseek.com. Esto significa que cualquier cliente que ya uses con GPT-5.5 u otras APIs con formato OpenAI funciona con V4 con un simple cambio de URL base.

Esta guía cubre la autenticación, cada parámetro importante, ejemplos en Python y Node, matemáticas en modo de pensamiento, llamadas a herramientas, streaming y un flujo de trabajo basado en Apidog que mantiene el costo visible mientras iteras.

Para la descripción general a nivel de producto, consulta qué es DeepSeek V4. Para la ruta sin costo, consulta cómo usar DeepSeek V4 gratis.

En resumen

• DeepSeek V4 se distribuye en el endpoint compatible con OpenAI en https://api.deepseek.com/v1/chat/completions y el endpoint compatible con Anthropic en https://api.deepseek.com/anthropic.
• IDs de modelo: deepseek-v4-pro (1.6T total, 49B activos) y deepseek-v4-flash (284B total, 13B activos).
• Ambas variantes admiten un contexto de 1M tokens y tres modos de razonamiento: non-thinking (sin pensamiento), thinking (pensamiento), thinking_max (pensamiento máximo).
• Usa temperature=1.0, top_p=1.0 como recomienda DeepSeek; no importes los valores predeterminados de GPT-5.5 o Claude.
• Los IDs heredados deepseek-chat y deepseek-reasoner se deprecian el 24 de julio de 2026; migra antes de esa fecha.
• Descarga Apidog para reproducir solicitudes, comparar modos de pensamiento y mantener la clave fuera de tu historial de shell.

Requisitos previos

Antes de la primera solicitud, ten listos cuatro elementos.

• Una cuenta de desarrollador de DeepSeek en platform.deepseek.com con al menos una recarga de $2. Sin saldo, las llamadas devuelven 402 Insufficient Balance.
• Una clave API con alcance al proyecto al que se le facturará. Las claves con alcance a proyectos son más seguras que las claves de cuenta para cualquier entorno de producción.
• Un SDK que pueda acceder a una URL base compatible con OpenAI. Python openai>=1.30.0 y Node openai@4.x funcionan sin modificaciones.
• Un cliente API que pueda reproducir solicitudes sin saturar la terminal. Curl funciona para una llamada; después de eso, usa Apidog.

Exporta la clave una vez:

export DEEPSEEK_API_KEY="sk-..."

Endpoint y autenticación

Dos URL base cubren dos formatos de solicitud.

POST https://api.deepseek.com/v1/chat/completions # Formato OpenAI
POST https://api.deepseek.com/anthropic/v1/messages # Formato Anthropic

Elige el formato compatible con OpenAI a menos que tengas un codebase existente con formato Anthropic. El resto de esta guía utiliza el formato OpenAI.

La autenticación es un token de portador en el encabezado estándar Authorization. La solicitud mínima viable:

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Explain MoE routing in two sentences."}
    ]
  }'

Las respuestas exitosas devuelven un cuerpo JSON con un array choices, un bloque usage desglosado en tokens de entrada y salida (y reasoning_tokens si el modo de pensamiento estaba activado), y un id que puedes usar para el seguimiento. Los fallos devuelven el sobre estándar de OpenAI con error.code y error.message.

Parámetros de solicitud

Cada campo se asigna a costo o comportamiento. Aquí está el mapa para deepseek-v4-pro y deepseek-v4-flash.

thinking_mode es la palanca de costo más grande. non-thinking omite completamente el rastreo de razonamiento y devuelve tokens aproximadamente a la velocidad de V3.2. thinking habilita un bloque de razonamiento que cuesta tokens adicionales pero mejora la precisión en código y matemáticas. thinking_max produce las puntuaciones en la tabla principal de DeepSeek; también consume la mayor cantidad de tokens y es el único modo que requiere un presupuesto de contexto de 384K+.

Cliente Python

El SDK oficial de openai funciona con una anulación de la URL base. Todos los envoltorios existentes compatibles con OpenAI, incluidos LangChain, LlamaIndex y DSPy, también funcionan.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Content:", choice.message.content)
print("Reasoning tokens:", response.usage.reasoning_tokens)
print("Total tokens:", response.usage.total_tokens)

El truco de extra_body es cómo pasas los parámetros específicos de DeepSeek a través del SDK de OpenAI sin parchear la biblioteca.

Cliente Node

Misma estructura en Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Explain the Muon optimizer in plain English." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);

El SDK de Node acepta campos desconocidos de forma silenciosa, por lo que thinking_mode se pasa al nivel superior sin extra_body.

Respuestas en streaming

Establece stream: true e itera los fragmentos SSE. La forma coincide exactamente con OpenAI.

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Stream a 300-word essay on MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Los rastreos de razonamiento se transmiten por separado cuando el modo de pensamiento está activado; el campo delta.reasoning_content los transporta y puedes mostrarlos en la interfaz de usuario o descartarlos.

Llamadas a herramientas

V4 admite el esquema estándar de llamada a herramientas de OpenAI. Las funciones definidas en el array tools se vuelven invocables, y el modelo decide cuándo invocarlas.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "¿Clima en Lagos en Celsius?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

A partir de ahí, llama a la función, añade el resultado como un mensaje role: "tool" y vuelve a llamar a la API para continuar el bucle. El patrón es idéntico a los bucles de uso de herramientas de OpenAI y Anthropic.

Modo JSON

Para la salida estructurada, solicita JSON explícitamente y establece el formato de respuesta.

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object."},
        {"role": "user", "content": "Summarize this release note as {title, date, bullets}: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

El modo JSON fuerza un JSON válido, pero no impone un esquema específico. Para la validación del esquema, combínalo con Pydantic o Zod en el lado del cliente.

Crea la colección en Apidog

Reproducir solicitudes desde la terminal consume créditos y oculta las diferencias entre ejecuciones. El flujo de trabajo que sobrevive al uso real:

1. Descarga Apidog y crea un proyecto.
2. Agrega un entorno con {{DEEPSEEK_API_KEY}} almacenado como una variable secreta.
3. Guarda una solicitud POST a {{BASE_URL}}/chat/completions con el encabezado Authorization: Bearer {{DEEPSEEK_API_KEY}}.
4. Parametriza model y thinking_mode para que puedas hacer pruebas A/B entre variantes sin duplicar solicitudes.
5. Usa el visor de respuestas para inspeccionar usage.reasoning_tokens en cada ejecución. Esa es la señal más clara de si estás pagando por un modo de pensamiento que no necesitas.

Los equipos que ya ejecutan la colección de API GPT-5.5 correspondiente en Apidog pueden duplicarla, cambiar la URL base a https://api.deepseek.com/v1, cambiar el ID del modelo y ejecutar prompts de comparación entre ambos proveedores en minutos.

Manejo de errores

El sobre sigue exactamente a OpenAI. Los que te encontrarás primero:

Envuelve las llamadas en un ayudante de reintento que maneje los códigos 429 y 5xx con retroceso exponencial. No reintentes los errores 4xx automáticamente; son errores de lógica, no fallos transitorios.

Patrones de control de costos

Cuatro patrones mantienen el gasto predecible.

1. Predetermina a V4-Flash. Cambia a V4-Pro solo para prompts donde hayas medido una mejora de calidad.
2. Protege thinking_max con un indicador. Es el modo más caro por un amplio margen; solo dirígete a él cuando la corrección supere la latencia.
3. Limita max_tokens. La mayoría de las respuestas caben en 2.000 tokens de salida. El contexto de 1M es para la entrada, no para la salida.
4. Registra usage en cada llamada. Envía los recuentos de entrada, salida y razonamiento a tu pila de observabilidad; una alerta sobre un pico repentino de tokens de razonamiento detecta prompts que se desviaron.

Migración desde modelos DeepSeek más antiguos

Los IDs antiguos deepseek-chat y deepseek-reasoner se deprecian el 24 de julio de 2026. La migración requiere una línea de diferencia por cada sitio de llamada; las formas de solicitud y respuesta no cambian.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

Antes de lanzar la producción, realiza comparaciones A/B paralelas en Apidog. El salto en la calidad de la respuesta generalmente compensa el cambio; la fecha límite de deprecación lo fuerza de cualquier manera.

Preguntas frecuentes

¿La API de DeepSeek V4 está lista para producción?Sí. La API se lanzó el 23 de abril de 2026 junto con los pesos. DeepSeek V3 y V3.2 funcionaron en la misma infraestructura a escala durante más de un año, por lo que la superficie de la API es madura.

¿V4 es compatible con el formato de mensaje de Anthropic?Sí. Apunta a https://api.deepseek.com/anthropic/v1/messages y envía la carga útil con formato Anthropic. Ambos formatos acceden al mismo modelo subyacente.

¿Cuál es la ventana de contexto?1 millón de tokens tanto en V4-Pro como en V4-Flash. Ten en cuenta que el modo Think Max recomienda una ventana de trabajo mínima de 384K.

¿Cómo cuento los tokens de entrada antes de enviarlos?Usa el tokenizador estándar de OpenAI para aproximaciones; DeepSeek publica recuentos exactos en el bloque usage en cada respuesta. Para la presupuestación de producción, confía en el recuento del lado de la respuesta.

¿Puedo ajustar (fine-tune) a través de la API?No en el lanzamiento. El ajuste fino actualmente se realiza a través de los checkpoints Base autoalojados en Hugging Face.

¿Es la API gratuita para probar?No hay una capa gratuita a nivel de cuenta, pero los nuevos registros ocasionalmente reciben un crédito de prueba.