API de DeepSeek V4 para programación: Enrutamiento de deepseek-v4-pro y deepseek-v4-flash

Enviar cada paso de una sesión de programación a un solo modelo es la política de enrutamiento más sencilla y, por lo general, la más costosa. Este tutorial muestra cómo utilizar la API de DeepSeek V4 para programar en TokenLab dividiendo el trabajo entre deepseek-v4-pro y deepseek-v4-flash. Leímos ambos registros de modelos desde la API en vivo el 03-10-2026, y todo lo que aparece a continuación proviene de esos registros y de la documentación de TokenLab. Obtendrá una tabla comparativa, una estimación de costos detallada, una solicitud de llamada a herramientas, código de reintento y respaldo, y una verificación previa al vuelo (preflight check).

Puntos clave

• Ambos modelos enumeran un límite de entrada de 1,000,000 de tokens, un límite de salida de 384,000 tokens y los mismos tres formatos de solicitud. El precio es la principal diferencia entre ellos.
• A precios de lista, deepseek-v4-pro cuesta 4.4 veces más que deepseek-v4-flash por token de entrada y 3.3 veces más por token de salida.
• En nuestro ejemplo de 20 llamadas, enrutar 4 llamadas a pro y 16 a flash cuesta alrededor de $0.18 en horario de baja demanda (off-peak). Enviar las 20 a pro cuesta alrededor de $0.46.
• Reintente el código 429 después de Retry-After. Reintente los códigos 500–504 solo cuando retryable sea true. Nunca reintente los códigos 400, 401, 402, 403, 404 o 413 sin cambios.
• El catálogo enumera deepseek-v4.1-flash como activo. Ni deepseek-v4-pro ni deepseek-v4-flash nombran un modelo de reemplazo.
• Lea los límites, formatos y precios desde GET /v1/models/:model antes de enrutar. No codifique de forma rígida una tabla copiada.

La API de DeepSeek V4 para programación: Lo que dice el catálogo

Obtuvimos ambos registros el 03-10-2026. La siguiente tabla los compara lado a lado. Los precios están en USD por 1 millón de tokens, y los precios del catálogo se actualizaron por última vez el 2026-10-02T16:53:30.068Z.

Elemento	deepseek-v4-pro	deepseek-v4-flash	Fuente, observado el 03-10-2026
Límite de contexto (máx. tokens de entrada)	1,000,000	1,000,000	pro, flash
Límite de salida (máx. tokens de salida)	384,000	384,000	pro, flash
Formatos de solicitud aceptados	anthropic_messages, openai_chat_completions, openai_responses	anthropic_messages, openai_chat_completions, openai_responses	pro, flash
Capacidades	json-mode, prompt-cache, tool-use	json-mode, prompt-cache, tool-use	pro, flash
Entrada off-peak	$0.66	$0.15	pro, flash
Salida off-peak	$1.98	$0.60	pro, flash
Lectura de caché off-peak	$0.022	$0.003	pro, flash
Escritura de caché off-peak	$0.66	no listado	pro, flash
Entrada peak	$1.32	$0.30	pro, flash
Salida peak	$3.96	$1.20	pro, flash
Lectura de caché peak	$0.044	$0.006	pro, flash
Etapa del ciclo de vida	activo, lanzado el 24-04-2026	activo, lanzado el 24-04-2026	pro, flash

El bloque de precios predeterminado en cada registro coincide con la entrada off-peak. El horario de demanda alta (peak) difiere según el registro. Para deepseek-v4-pro, los precios peak se aplican de 09:00 a 12:00 y de 14:00 a 18:00, hora de Pekín. Para deepseek-v4-flash, el registro indica que las ventanas peak se aplican en días laborables, excluyendo los días festivos de China. Dice que el horario off-peak incluye fines de semana y esos días festivos, pero no especifica horas. Consulte el endpoint de precios antes de presupuestar en torno a la ventana flash.

Ciclo de vida y modelos DeepSeek más nuevos

Ambos registros muestran lifecycle stage active, con replacement model, deprecated_at y retired_at vacíos. Por lo tanto, el catálogo no programa la eliminación de ninguno de los modelos y no nombra sucesor para ninguno.

El catálogo también enumera deepseek-v4.1-flash. Su registro, observado el 03-10-2026, está activo sin fecha de lanzamiento y sin reemplazo. Tiene los mismos límites, formatos y precios de lista que deepseek-v4-flash. Agrega reasoning y vision a la lista de capacidades y muestra un precio de escritura de caché de $0.15 off-peak.

Ese es un ID de modelo separado, por lo que este artículo mantiene su tema. Le recomendamos probar deepseek-v4.1-flash en sus propias tareas antes de cambiarlo. El catálogo también enumera deepseek-v4-flash-vision-exp, pero no leímos su registro. Verifíquelo en la página de Modelos si lo necesita.

Enrutamiento de deepseek-v4-pro y deepseek-v4-flash por tarea

Imagine una sesión de agente que planifica un cambio en cinco módulos, escribe las ediciones y luego genera una docena de stubs de prueba. El primer paso necesita la mayor cantidad de contexto y cuidado. El último es repetitivo y barato de rehacer. El catálogo no puede decirle dónde se encuentra la línea de calidad. La guía de TokenLab sobre modelos de agentes de codificación, observada el 03-10-2026, dice que los resultados de las tablas de clasificación no predicen cómo un modelo sigue sus propias instrucciones y herramientas.

Nuestra heurística inicial asume que el modelo más caro justifica su costo en el trabajo entre archivos. Trátelo como una hipótesis a probar, no como un hallazgo:

+-------------------------------------------------------------+
|                      Tarea entrante                         |
+-------------------------------------------------------------+
                               |
         [¿La tarea implica contexto de múltiples archivos,
          compatibilidad hacia atrás o revisión de seguridad?]
                               |
               +---------------+---------------+
               |                               |
             [Sí]                            [No]
               |                               |
               v                               v
       deepseek-v4-pro                 deepseek-v4-flash

Criterios que envían un paso a deepseek-v4-pro:

• Modificar lógica en múltiples archivos importados.
• Evaluaciones de seguridad o vulnerabilidad.
• Compatibilidad estricta hacia atrás en interfaces públicas.
• Trabajo de múltiples turnos donde la precisión importa más que el tiempo de respuesta.

El andamiaje de pruebas independiente, el formato de esquemas, los docstrings y la finalización de sintaxis van a deepseek-v4-flash.

Para probar la heurística, siga la misma guía. Proporcione a cada modelo el mismo estado de repositorio, instrucciones, herramientas y límite de tiempo. Luego compare la exactitud, las pruebas superadas, los cambios innecesarios, el total de tokens, el costo final y la frecuencia con la que una persona tuvo que intervenir. Mantenga los resultados por tipo de tarea, ya que un modelo puede revisar bien e implementar mal.

Estimación del costo de un bucle de agente de codificación

Los agentes reenvían instrucciones, historial, código y resultados de herramientas en cada llamada. La guía de costos, observada el 03-10-2026, señala que las sesiones largas pueden costar mucho más que una sola solicitud de chat. Calculamos la aritmética a continuación a partir de los precios de lista. El resultado es una estimación, no una factura medida.

Suposiciones (nuestras, no medidas): un bucle de 20 llamadas al modelo, cada una con 30,000 tokens de entrada y 1,500 tokens de salida. Eso da 600,000 tokens de entrada y 30,000 tokens de salida en total.

La fórmula es tokens_entrada / 1M × precio_entrada + tokens_salida / 1M × precio_salida. Los precios provienen de la tabla anterior.

Las 20 llamadas a deepseek-v4-pro:

• Off-peak: 0.6 × $0.66 = $0.396 entrada, más 0.03 × $1.98 = $0.0594 salida, para un total de $0.4554.
• Peak: 0.6 × $1.32 = $0.792, más 0.03 × $3.96 = $0.1188, para un total de $0.9108.

Las 20 llamadas a deepseek-v4-flash:

• Off-peak: 0.6 × $0.15 = $0.09, más 0.03 × $0.60 = $0.018, para un total de $0.108.
• Peak: 0.6 × $0.30 = $0.18, más 0.03 × $1.20 = $0.036, para un total de $0.216.

Mixto: 4 llamadas a pro, 16 a flash. Pro conlleva 120,000 tokens de entrada y 6,000 de salida. Flash conlleva 480,000 tokens de entrada y 24,000 de salida.

• Off-peak: pro es 0.12 × $0.66 + 0.006 × $1.98 = $0.0792 + $0.01188 = $0.09108. Flash es 0.48 × $0.15 + 0.024 × $0.60 = $0.072 + $0.0144 = $0.0864. El total es $0.17748.
• Peak: pro es 0.12 × $1.32 + 0.006 × $3.96 = $0.1584 + $0.02376 = $0.18216. Flash es 0.48 × $0.30 + 0.024 × $1.20 = $0.144 + $0.0288 = $0.1728. El total es $0.35496.

Escenario	Estimación off-peak	Estimación peak
20 llamadas en deepseek-v4-pro	$0.4554	$0.9108
20 llamadas en deepseek-v4-flash	$0.1080	$0.2160
4 pro + 16 flash	$0.1775	$0.3550

Estimaciones a partir de los precios de lista observados el 03-10-2026 (pro, flash).

Variante de caché (off-peak, suposición: el 80% de los tokens de entrada son lecturas de caché). Eso significa 480,000 tokens de lectura de caché y 120,000 tokens sin caché por bucle.

• Pro: 0.48 × $0.022 = $0.01056, más 0.12 × $0.66 = $0.0792, más $0.0594 de salida, para un total de $0.14916.
• Flash: 0.48 × $0.003 = $0.00144, más 0.12 × $0.15 = $0.018, más $0.018 de salida, para un total de $0.03744.

Esta variante factura los tokens sin caché al precio de entrada normal e ignora los cargos de escritura de caché en flash, que el registro no enumera. Confirme los recuentos de tokens en caché en la respuesta o en Uso antes de contar con este descuento. La guía de facturación también advierte que el precio más bajo por token no siempre es el costo más bajo por tarea completada, porque los reintentos se suman.

Una solicitud de llamada a herramientas para un agente de codificación

Ambos registros enumeran tool-use y ambos aceptan openai_chat_completions. La solicitud a continuación utiliza solo campos de la guía de llamada a herramientas (observada el 03-10-2026): model, messages y tools con type: "function". Agregamos max_tokens, que la guía de facturación enumera como una forma de limitar la longitud de la respuesta. Omitimos tool_choice, porque esa guía solo lo documenta para el formato Responses.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 2000,
    "messages": [
      {"role": "system", "content": "You are a software engineering assistant."},
      {"role": "user", "content": "The pagination test in tests/test_api.py fails. Find the cause."}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "read_file",
          "description": "Read a file from the repository",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "run_tests",
          "description": "Run the test suite for one path",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      }
    ]
  }'

El modelo devuelve un nombre de función y argumentos en tool_calls. Su backend ejecuta la herramienta. El bucle se ejecuta entonces en cinco pasos:

1. Enviar mensajes más definiciones de herramientas.
2. Leer la respuesta para tool_calls.
3. Ejecutar la herramienta en su propio backend.
4. Adjuntar el resultado de la herramienta en el mismo formato de API.
5. Continuar hasta que el modelo devuelva una respuesta final.

La guía no muestra la forma del mensaje de resultado de la herramienta en línea. Tómela de la referencia de Create Chat Completion (/api-reference/chat/create-completion) en lugar de adivinar.

Antes de ejecutar cualquier llamada, valide los argumentos y aplique sus propias verificaciones de permisos. Haga que la ejecución sea idempotente, porque un reintento del cliente puede repetir la misma llamada a la herramienta. Mantenga un formato de API para todo el intercambio, ya que los formatos representan el estado de la herramienta de manera diferente.

Reintentos, retroceso y respaldo entre los dos modelos

La guía de errores y la guía de límites de tasa, ambas observadas el 03-10-2026, establecen la política. Bifurque según el estado HTTP y el code, nunca según el message.

Estado	¿Repetir la misma solicitud?	Acción
400, 401, 402, 403, 404, 413	No	Corrija la solicitud, clave, saldo, permisos o entrada
429	Sí	Espere por Retry-After; si está ausente, use retroceso exponencial con jitter
500–504	Solo si retryable es true	Respete retry_after y limite los intentos
Conexión cerrada antes de una respuesta	A veces	Reintente con cuidado si una llamada a herramienta podría repetir un efecto secundario
Flujo interrumpido después de que llegó la salida	No	Trátelo como incompleto; una repetición puede producir una salida diferente o un segundo cargo

Dos casos necesitan cuidado adicional. Un 503 all_channels_failed o 503 delivery_tier_unavailable no siempre es temporal. Cuando retryable es false y falta retry_after, no repita la solicitud. Consulte GET /v1/models antes de elegir otro modelo. Además, context_length_exceeded no se solucionará cambiando entre estos dos modelos, ya que ambos enumeran el mismo límite de entrada de 1,000,000 de tokens.

El código a continuación aplica esa política. Establece max_retries=0 para que el SDK no reintente a sus espaldas. Cada modelo obtiene cuatro intentos, y el respaldo se ejecuta solo después de que el primer modelo agota los errores reintentables.

import os
import random
import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

FALLBACK = {
    "deepseek-v4-pro": "deepseek-v4-flash",
    "deepseek-v4-flash": "deepseek-v4-pro",
}

def error_fields(exc):
    body = getattr(exc, "body", None)
    if isinstance(body, dict):
        return body.get("error", body)
    return {}

def backoff(attempt):
    return min(30, 2 ** attempt + random.random())

def retry_delay(exc, attempt):
    """Segundos a esperar, o None cuando la solicitud no debe repetirse."""
    if isinstance(exc, APIConnectionError):
        return backoff(attempt)
    fields = error_fields(exc)
    header = exc.response.headers.get("Retry-After")
    if exc.status_code == 429:
        return float(header) if header else backoff(attempt)
    if exc.status_code >= 500 and fields.get("retryable") is True:
        wait = fields.get("retry_after") or header
        return float(wait) if wait else backoff(attempt)
    return None

def chat_with_fallback(model, messages, tools=None, attempts=4):
    last_exc = None
    for candidate in (model, FALLBACK[model]):
        kwargs = {"model": candidate, "messages": messages}
        if tools:
            kwargs["tools"] = tools
        for attempt in range(attempts):
            try:
                return candidate, client.chat.completions.create(**kwargs)
            except (APIStatusError, APIConnectionError) as exc:
                delay = retry_delay(exc, attempt)
                if delay is None:
                    raise  # 4xx o 5xx no reintentable: no repetir ni respaldar
                last_exc = exc
                if attempt < attempts - 1:
                    time.sleep(delay)
        print(f"{candidate} agotó los reintentos, intentando {FALLBACK[candidate]}")
    raise last_exc

def pick_model(is_complex):
    return "deepseek-v4-pro" if is_complex else "deepseek-v4-flash"

used, response = chat_with_fallback(
    pick_model(is_complex=False),
    [{"role": "user", "content": "Write a pytest case: an empty list returns 0 for sum_items()."}],
)
print(used, response.choices[0].message.content)

Registre siempre qué modelo respondió. La guía del agente de codificación advierte que un respaldo puede cambiar el precio, el límite de contexto, el formato de la herramienta o el estilo de salida, así que informe al usuario cuando el modelo cambie. Volver de flash a pro aproximadamente cuadruplica el costo de entrada a precios de lista, así que alerte sobre ello. Guarde el ID de solicitud de los encabezados de respuesta con cada llamada para que el soporte pueda rastrear una falla.

Lea límites, formatos y precios antes de enrutar

La referencia Get a Model, observada el 03-10-2026, describe GET /v1/models/:model. La respuesta lleva un objeto tokenlab con capabilities, pricing, max_input_tokens, max_output_tokens, accepted_request_formats y lifecycle. Un modelo desconocido devuelve 404 model_not_found. La guía de facturación también apunta a GET /v1/models/:model/pricing para el precio actual.

import json
import urllib.request

def read_model(model_id):
    url = f"https://api.tokenlab.sh/v1/models/{model_id}"
    with urllib.request.urlopen(url, timeout=10) as resp:
        meta = json.load(resp)["tokenlab"]
    return {
        "max_input_tokens": meta.get("max_input_tokens"),
        "max_output_tokens": meta.get("max_output_tokens"),
        "formats": meta.get("accepted_request_formats"),
        "capabilities": meta.get("capabilities"),
        "lifecycle": meta.get("lifecycle"),
        "pricing": meta.get("pricing"),
    }

def preflight(model_id, input_tokens):
    info = read_model(model_id)
    problems = []
    if "openai_chat_completions" not in (info["formats"] or []):
        problems.append("chat completions not accepted")
    if "tool-use" not in (info["capabilities"] or []):
        problems.append("no tool-use capability")
    if info["max_input_tokens"] and input_tokens > info["max_input_tokens"]:
        problems.append("input exceeds max_input_tokens")
    return info, problems

for model_id in ("deepseek-v4-pro", "deepseek-v4-flash"):
    info, problems = preflight(model_id, input_tokens=30_000)
    print(model_id, json.dumps(info, indent=2), problems)

Imprimimos lifecycle y pricing sin procesar porque la evidencia de este artículo no muestra su diseño JSON exacto dentro de esa respuesta. Inspeccione la salida una vez, luego analice los campos que necesita. La documentación desaconseja codificar tablas de precios copiadas, así que realice la verificación al inicio o en un horario programado. Los endpoints de descubrimiento público como GET /v1/models tienen sus propios límites de tasa, así que almacene el resultado en caché en lugar de llamarlo por solicitud.

Para los límites de tasa, el nivel de Usuario estándar permite 1,000 solicitudes por minuto por clave de API, según lo observado el 03-10-2026. La guía dice que la configuración activa puede diferir. En un 429, confíe en los valores devueltos X-RateLimit-Limit y Retry-After sobre cualquier número copiado.

Preguntas frecuentes

¿Puedo llamar a deepseek-v4-pro a través del formato Anthropic Messages?

Sí. Ambos registros enumeran anthropic_messages entre los formatos aceptados, observado el 03-10-2026. La guía de agentes de codificación da la URL base de Anthropic Messages como https://api.tokenlab.sh, sin el sufijo /v1 que usa Chat Completions. Los esquemas de herramientas difieren según el formato, así que mantenga un formato para toda la conversación.

¿Debo reintentar un 503 de deepseek-v4-pro o deepseek-v4-flash?

Solo si el cuerpo del error dice que retryable es true, y luego espere por retry_after. Un 503 all_channels_failed con retryable: false significa que la solicitud no tiene suministro en el nivel de entrega seleccionado. Repetirlo no ayudará. Consulte GET /v1/models antes de elegir otro modelo, como describe la guía de errores.

¿deepseek-v4.1-flash reemplaza a deepseek-v4-flash?

El catálogo no lo dice. El 03-10-2026 el registro de deepseek-v4-flash no mostraba ningún modelo de reemplazo, y deepseek-v4.1-flash mostraba estado activo. Los dos comparten límites y precios de lista, y el más nuevo agrega capacidades de reasoning y vision. Pruébelo en sus tareas y cambie deliberadamente por ID de modelo.

¿Los tokens en caché hacen que deepseek-v4-flash sea más barato en un bucle de agente?

Pueden hacerlo. El registro enumera un precio de lectura de caché off-peak de $0.003 por 1M de tokens, frente a $0.15 para la entrada simple. La guía de costos dice que confirme el uso de tokens en caché en la respuesta o en Uso antes de contar con un descuento. El comportamiento y los precios de la caché difieren según el modelo.

¿Enrutar a deepseek-v4-flash elevará mi límite de tasa?

No. La guía de límites de tasa dice que un modelo más rápido no eleva el límite de solicitudes de su cuenta. La velocidad del modelo, los límites de tokens y los límites de tasa de la cuenta son restricciones separadas, y los límites se aplican por clave de API.

Consulte las entradas actuales de deepseek-v4-pro y deepseek-v4-flash en la página de modelos de TokenLab antes de conectar su enrutador.