DEV Community

Cover image for Cómo usar la API DeepSeek V4
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo usar la API DeepSeek V4

DeepSeek V4 se lanzó con 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 compatible con GPT-5.5 u otras APIs OpenAI puede usar V4 solo cambiando la URL base.

Prueba Apidog hoy

Cómo empezar con DeepSeek V4

Esta guía cubre autenticación, parámetros clave, ejemplos en Python y Node, matemáticas en modo de pensamiento, llamadas a herramientas, streaming y un flujo de trabajo con Apidog para visualizar costos mientras iteras.

Para una descripción general de producto, revisa qué es DeepSeek V4. Para usar sin costo, consulta cómo usar DeepSeek V4 gratis.

En resumen

  • DeepSeek V4 expone dos endpoints: OpenAI-compatible en https://api.deepseek.com/v1/chat/completions y Anthropic-compatible 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).
  • Ambos soportan contexto de 1M tokens y tres modos de razonamiento: non-thinking, thinking, thinking_max.
  • Usa temperature=1.0, top_p=1.0 como recomienda DeepSeek; no uses defaults de GPT-5.5 o Claude.
  • Los IDs antiguos deepseek-chat y deepseek-reasoner se deprecian el 24 de julio de 2026; migra antes.
  • Descarga Apidog para reproducir solicitudes, comparar modos y mantener tu clave fuera del historial de shell.

Captura de pantalla de Apidog mostrando una configuración de solicitud HTTP para DeepSeek V4

Requisitos previos

Antes de tu primera solicitud, ten listos:

  • Cuenta de desarrollador DeepSeek en platform.deepseek.com y recarga de $2 mínimo (sin saldo, todas las llamadas devuelven 402 Insufficient Balance).
  • Clave API con alcance a proyecto (más seguro que clave general).
  • SDK con soporte de URL base OpenAI (Python openai>=1.30.0, Node openai@4.x funcionan sin cambios).
  • Cliente API que pueda repetir solicitudes fácilmente. Usa curl solo para pruebas rápidas; para iteraciones y comparación, usa Apidog.

Exporta la clave:

export DEEPSEEK_API_KEY="sk-..."
Enter fullscreen mode Exit fullscreen mode

Endpoint y autenticación

Tienes dos URL base:

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

Elige OpenAI a menos que ya utilices Anthropic. El resto de ejemplos usa formato OpenAI.

Autenticación: token tipo Bearer en el header Authorization. Ejemplo mínimo 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."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Respuestas exitosas devuelven un JSON con choices, usage (tokens de entrada, salida y reasoning_tokens si aplica), y id. Errores usan el formato estándar OpenAI (error.code y error.message).

Parámetros de solicitud

Cada campo impacta costo o comportamiento. Mapeo para deepseek-v4-pro y deepseek-v4-flash:

Parámetro Tipo Valores Notas
model string deepseek-v4-pro, deepseek-v4-flash Obligatorio.
messages array pares rol/contenido Obligatorio. Mismo esquema que OpenAI.
thinking_mode string non-thinking, thinking, thinking_max Default: non-thinking.
temperature float 0 a 2 DeepSeek recomienda 1.0.
top_p float 0 a 1 DeepSeek recomienda 1.0.
max_tokens int 1 a 131072 Límite de salida.
stream boolean true o false Activa streaming SSE.
tools array especificación OpenAI Para llamada a funciones.
tool_choice string/object auto, required, none, o específica Controla uso de herramientas.
response_format object {"type": "json_object"} Salida JSON.
seed int cualquier int Para reproducibilidad.
presence_penalty float -2 a 2 Penaliza temas repetidos.
frequency_penalty float -2 a 2 Penaliza tokens repetidos.

thinking_mode es la palanca de costo más relevante. non-thinking omite razonamiento y es más rápido/económico; thinking agrega razonamiento útil en código/matemáticas a cambio de más tokens; thinking_max maximiza precisión y costo (requiere contexto ≥384K).

Cliente Python

El SDK openai funciona usando base_url. Otros wrappers OpenAI (LangChain, LlamaIndex, 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)
Enter fullscreen mode Exit fullscreen mode

Pasa parámetros específicos de DeepSeek usando extra_body sin modificar la librería.

Cliente Node

Estructura similar 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);
Enter fullscreen mode Exit fullscreen mode

El SDK Node acepta campos adicionales directamente (no requiere extra_body).

Respuestas en streaming

Activa stream: true y recorre los chunks SSE. Compatible con la forma 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)
Enter fullscreen mode Exit fullscreen mode

Si usas modo de pensamiento, el razonamiento llega por delta.reasoning_content. Puedes mostrarlo o ignorarlo.

Llamadas a herramientas

V4 soporta el esquema estándar OpenAI para funciones. Define funciones en tools, 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)
Enter fullscreen mode Exit fullscreen mode

Después, llama la función, añade el output como role: "tool" y reenvía a la API. El flujo es idéntico a OpenAI/Anthropic.

Modo JSON

Para salida estructurada, fuerza formato JSON:

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"},
)
Enter fullscreen mode Exit fullscreen mode

Esto garantiza JSON válido, pero no esquema. Para validación estricta, usa Pydantic o Zod en cliente.

Crea la colección en Apidog

No repitas pruebas manuales en terminal; consume créditos y dificulta comparar. Hazlo así:

  1. Descarga Apidog y crea un proyecto.
  2. Crea un entorno con {{DEEPSEEK_API_KEY}} como variable secreta.
  3. Guarda una solicitud POST a {{BASE_URL}}/chat/completions con header Authorization: Bearer {{DEEPSEEK_API_KEY}}.
  4. Parametriza model y thinking_mode para pruebas A/B de variantes.
  5. Usa el visor de respuestas para monitorear usage.reasoning_tokens y ver si pagas razonamiento extra.

Si ya tienes la colección GPT-5.5 en Apidog, duplícala, cambia la URL base a https://api.deepseek.com/v1, actualiza el modelo y compara resultados en minutos.

Manejo de errores

El formato de error es igual a OpenAI. Principales códigos:

Código Significado Solución
400 Solicitud incorrecta Verifica el esquema JSON, sobre todo messages y tools.
401 Clave inválida Regenera desde platform.deepseek.com.
402 Saldo insuficiente Recarga la cuenta.
403 Modelo no permitido Revisa alcance de la clave y ortografía del modelo.
422 Parámetro fuera de rango Verifica max_tokens y thinking_mode.
429 Límite de tasa Implementa backoff exponencial y reintenta.
500 Error del servidor Reintenta una vez; si persiste, revisa status.
503 Sobrecarga Pasa a V4-Flash o espera 30 segundos.

Implementa un helper de reintentos para 429 y 5xx con backoff exponencial. No reintentes errores 4xx automáticamente: indican errores de lógica.

Patrones de control de costos

Para evitar sorpresas en facturación:

  1. Predetermina V4-Flash. Cambia a V4-Pro solo si mides mejora tangible.
  2. Protege thinking_max con flag. Es el modo más caro; úsalo solo si la corrección es crítica.
  3. Limita max_tokens. La mayoría de respuestas caben en 2.000 tokens. El contexto de 1M es para entrada, no salida.
  4. Registra usage en cada llamada. Monitorea tokens de entrada, salida y razonamiento para detectar picos.

Migración desde modelos DeepSeek antiguos

IDs deepseek-chat y deepseek-reasoner se deprecian el 24/07/2026. Migra cambiando solo el ID de modelo; la forma de requests/responses no cambia.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"
Enter fullscreen mode Exit fullscreen mode

Antes de producción, haz comparativas A/B en Apidog. La mejora de calidad suele justificar el esfuerzo.

Preguntas frecuentes

¿La API de DeepSeek V4 está lista para producción?

Sí. La API está disponible desde el 23 de abril de 2026. V3/V3.2 ya operaban a escala, la superficie es madura.

¿Soporta formato Anthropic?

Sí. Usa https://api.deepseek.com/anthropic/v1/messages y payload Anthropic. Acceso al mismo modelo.

¿Cuál es la ventana de contexto?

1 millón de tokens en V4-Pro y V4-Flash. thinking_max recomienda mínimo 384K.

¿Cómo cuento tokens de entrada antes de enviar?

Usa tokenizador OpenAI para estimar; el recuento exacto está en usage de la respuesta. Para presupuestos, confía en el output real.

¿Puedo ajustar (fine-tune) vía API?

No por ahora. Fine-tuning solo vía checkpoints base en Hugging Face.

¿Es gratis para probar?

No hay capa gratuita, pero nuevos registros a veces reciben crédito de prueba.

Top comments (0)