Conectar la API de DeepSeek no es complicado en sí; lo que suele atascarse son tres cosas: a qué plataforma pertenece la clave, si la URL base está escrita completa y si el nombre del modelo corresponde a la versión actual. Muchos casos de "no funciona" no tienen que ver con la capacidad del modelo, sino con credenciales y direcciones que no coinciden.
Este artículo empieza por el registro, la recarga y la creación de la clave, sigue en orden hasta la primera llamada con curl y Python, y luego explica la salida en streaming, el modo thinking, max_tokens y los errores más comunes. Si lo sigues paso a paso, deberías dejar operativo el circuito de conexión.
Nota: DeepSeek es una marca registrada de su titular; este artículo no tiene relación de afiliación con DeepSeek. Los nombres de modelo, parámetros y límites pueden cambiar según la versión. Aquí se usa como ejemplo la forma habitual de la documentación oficial de octubre de 2026; en última instancia, consulta la documentación oficial y los precios de modelos del sitio.
1. Antes de conectar, distingue cuatro elementos
La mayoría de los fallos de conexión no se deben a la capacidad del modelo, sino a que estos cuatro elementos no están alineados:
| Elemento | Función | Dónde se falla más |
|---|---|---|
| Cuenta | Determina el saldo, la facturación y a quién pertenece la clave | Usar una clave de la plataforma A con la dirección de la plataforma B |
| Clave de API | Credencial de identidad | Copiarla con espacios, saltos de línea o comillas |
| URL base | A qué entrada se envía la solicitud | Olvidar /v1 o mezclar la dirección oficial con la del gateway |
| Nombre del modelo | Campo model de la solicitud |
Reutilizar nombres vencidos de artículos antiguos |
La regla para recordarlo es simple: la clave y la URL base deben ir en pareja. Una clave oficial solo funciona con la entrada oficial; una clave del gateway solo con la entrada del gateway. Mezclarlas normalmente devuelve 401.
2. Registro, recarga y creación de la clave
Tomando como ejemplo la plataforma abierta oficial, el orden es el siguiente:
- Abre la plataforma abierta de DeepSeek, regístrate e inicia sesión.
- Completa las verificaciones que indique la página y entra a la página de recarga.
- La primera vez, recarga un monto pequeño; cuando confirmes que el saldo llegó, ejecuta tareas por lotes.
- Entra a la página de API Keys, crea una clave y ponle un nombre claro según su uso, por ejemplo
deepseek-testodeepseek-prod. - Copia la clave y guárdala de inmediato en un gestor de contraseñas o en una variable de entorno del servidor; por lo general, la página ya no la vuelve a mostrar completa.
- Crea claves separadas para pruebas y producción, y configura alertas de presupuesto o de consumo.
Si usas ZSQH AI Gateway, el proceso es similar: crea una cuenta en la página de registro, entra a la consola para crear la clave y recargar, y luego llama siguiendo el método compatible con OpenAI que se explica más adelante. No compartas la misma clave entre ambos servicios; de lo contrario, cuando algo falle será difícil saber si es saldo, límite de frecuencia o error de configuración.
3. URL base y nombre del modelo: confirma antes de escribir código
La documentación oficial indica actualmente la entrada compatible con OpenAI https://api.deepseek.com, con la ruta de chat completions /chat/completions. Algunos tutoriales antiguos usan https://api.deepseek.com/v1; la validez de esa forma depende de lo que diga la documentación oficial vigente. Si no estás seguro, primero haz funcionar la dirección del ejemplo oficial.
| Elemento | Conexión directa oficial | ZSQH AI Gateway |
|---|---|---|
| URL base | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| Ruta de chat | /chat/completions |
/v1/chat/completions |
| Origen de la clave | Plataforma abierta oficial | Consola del gateway |
| Nombre del modelo | Según la documentación oficial | Según los precios de modelos del sitio |
| Ideal para | Usar solo DeepSeek, con acceso y pago oficiales sin problemas | Necesitar una entrada unificada, varios modelos o facturación en yuanes |
A octubre de 2026, los nombres de modelo que aparecen en la documentación oficial son deepseek-flash y deepseek-v4-pro; los nombres deepseek-chat y deepseek-reasoner de artículos anteriores no necesariamente siguen disponibles. No escribas el nombre del modelo de memoria: compáralo con la documentación oficial o con la página de precios del sitio antes de llamar.
4. Primera llamada con curl: primero la solicitud mínima
Desactiva thinking para reducir variables. Ejemplo con la entrada oficial:
export DEEPSEEK_API_KEY="sk-tu-clave"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"messages": [{"role": "user", "content": "Responde solo OK"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
Si devuelve 200 y choices[0].message.content trae contenido, la clave, la URL base y el nombre del modelo están bien. Si usas el gateway, solo cambia la URL a https://ai.zhongshangqihang.com/v1/chat/completions y usa una clave del gateway.
Ten en cuenta que thinking es un parámetro extendido de DeepSeek y no todos los servicios compatibles con OpenAI lo admiten. Si el gateway no lo soporta, quita ese campo o usa el parámetro correspondiente según la documentación del gateway.
5. Primera llamada en Python: con el SDK de OpenAI
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # con el gateway, usa https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "Eres un asistente técnico; responde de forma concisa."},
{"role": "user", "content": "Explica en tres frases qué es una base de datos vectorial."},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
El SDK de OpenAI no reconoce el campo thinking, por eso se pasa mediante extra_body. Cuando funcione, revisa primero usage: cuántos tokens consumen la entrada y la salida, si se reportan aciertos de caché y si el contenido de razonamiento se cuenta por separado. Esos datos orientan mejor el costo y los tiempos de espera que la sensación de "si va rápido".
6. Streaming y reasoning_content
thinking está activado por defecto, con intensidad alta (high). Al activarlo, la respuesta incluye reasoning_content, al mismo nivel que el contenido final content; en streaming se devuelve por bloques en delta.reasoning_content.
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "Escribe un ejemplo en Python que lea un CSV"}],
stream=True,
max_tokens=4096,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
reasoning, answer = [], []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
reasoning.append(delta.reasoning_content)
if delta.content:
answer.append(delta.content)
print("Razonamiento:", "".join(reasoning))
print("Respuesta final:", "".join(answer))
En conversaciones de varios turnos, si la solicitud incluye tools, el reasoning_content del turno anterior debe devolverse completo; de lo contrario, puede responder 400. Sin tools, se puede omitir y el servidor lo ignora. Para el usuario final, conviene mostrar el razonamiento plegado, no desplegado por defecto.
7. Cómo combinar max_tokens, temperature y thinking
| Tarea | thinking | Punto de partida sugerido | Nota |
|---|---|---|---|
| Prueba de conectividad | Desactivado | max_tokens 32–128 | Solo se necesita una respuesta corta |
| Clasificación y extracción | Desactivado | 256–1024 | Salida estructurada, menos costo de razonamiento |
| Atención al cliente y redacción | Activado | 1024–4096 | Ajusta effort según el resultado |
| Código y razonamiento complejo | Activado | Más de 4096 | Deja presupuesto suficiente para el razonamiento |
La documentación oficial indica actualmente: contexto de 1M de tokens y rango de max_tokens de 1 a 384K; si no se define, el valor predeterminado es 8K sin thinking y 64K con thinking, y 128K cuando reasoning_effort es max. Estas cifras pueden cambiar; consulta la documentación oficial.
En modo thinking, temperature, presence_penalty y frequency_penalty no tienen efecto: ajustarlos no da error, pero tampoco cambia el resultado. Tampoco conviene dejar max_tokens demasiado bajo: el razonamiento consume presupuesto de salida y, si es muy pequeño, la respuesta puede cortarse antes de llegar al texto final.
8. Cómo diagnosticar 401, 402, 429 y tiempos de espera
| Síntoma | Causa común | Solución |
|---|---|---|
| 401 | Clave incorrecta, falta Bearer o clave y URL base de plataformas distintas | Vuelve a copiar la clave, revisa el encabezado y confirma que la entrada coincida |
| 402 | Saldo insuficiente en la cuenta | Recarga y reintenta; revisa el saldo antes de tocar el código |
| 429 | Demasiadas solicitudes, concurrencia o QPS excedido | Baja la concurrencia, aplica retroceso exponencial y separa claves por proyecto |
| 400/422 | Parámetros, nombre de modelo o contexto inválidos | Lee el mensaje de error y verifica el nombre del modelo y max_tokens |
| Tiempo de espera | Red, salida larga o demora del razonamiento | Configura por separado los tiempos de conexión y lectura, y limita la salida |
| 500/503 | Error o sobrecarga del servicio upstream | Espera un momento y reintenta con retroceso |
El límite de concurrencia de 429 se cuenta por cuenta, no se reparte entre cada clave. Varias claves de una misma cuenta comparten la cuota, así que "crear más claves" no evita el límite de concurrencia. La documentación oficial también indica que, si la inferencia no comienza en 10 minutos, la conexión se cierra; el cliente debe detectar esa situación y reintentar.
9. Seguridad de las claves: al menos cinco acciones antes de salir a producción
- Guarda la clave solo en variables de entorno del servidor o en un servicio de gestión de secretos; nunca en el frontend, el repositorio ni los registros.
- Usa una clave distinta para pruebas, preproducción y producción, para poder ubicar y desactivar rápido un problema.
- Configura alertas de saldo o límites de consumo para contener el gasto ante llamadas anómalas.
- En los registros, guarda solo el prefijo o la huella de la clave, nunca el valor completo.
- Si hay cambios de personal o sospechas de filtración, rota la clave de inmediato y revisa el consumo reciente.
10. Pasar de la conexión oficial al gateway: solo dos cambios
Al migrar, cambia primero base_url y api_key, vuelve a confirmar el nombre del modelo en la página de precios del gateway y mantén el resto del cuerpo de la solicitud igual en lo posible. Compara salida, latencia y usage con el mismo lote de prompts reales, observa de 3 a 7 días y luego pasa a producción. Conserva la conexión directa oficial como canal de respaldo para poder revertir rápido si algo falla.
Si necesitas una entrada unificada o facturación de varios modelos, puedes crear una clave de prueba en ZSQH AI Gateway; consulta precios y modelos disponibles en Precios de modelos.
Lecturas relacionadas:
- Cómo obtener una clave de API de DeepSeek
- Errores comunes y límites de frecuencia de la API de DeepSeek
- Precios y facturación de la API de DeepSeek
Preguntas frecuentes
¿Hay que agregar /v1 a la URL base?
Depende del ejemplo vigente en la documentación oficial. La entrada oficial compatible con OpenAI se escribe https://api.deepseek.com, con la ruta de chat /chat/completions; el gateway suele usar el prefijo /v1. No lo adivines con tutoriales antiguos: prueba primero la dirección completa con curl.
¿El 401 es por clave incorrecta o por saldo insuficiente?
El 401 es un fallo de autenticación: revisa primero si la clave es correcta, si incluye Bearer y si la clave y la URL base pertenecen a la misma plataforma. El saldo insuficiente suele devolver 402; no confundas ambos casos.
¿Conviene activar thinking en la primera llamada?
Se recomienda desactivarlo primero y confirmar la conexión con la solicitud más corta. Cuando verifiques clave, dirección y nombre del modelo, actívalo según la tarea y empieza con un reasoning_effort bajo.
¿Qué valor de max_tokens conviene usar?
Asigna al principio un valor suficiente para la tarea y ajústalo después. Para clasificación y extracción puedes empezar con unos cientos; para textos largos y código, deja algunos miles. En modo thinking hay que reservar presupuesto para el razonamiento; si es muy pequeño, el texto final puede truncarse.
¿Puedo usar una clave oficial con la dirección del gateway?
No. La clave oficial solo corresponde a la entrada oficial y la clave del gateway solo a la entrada del gateway; mezclarlas normalmente devuelve 401. Al cambiar de entrada, cambia la clave y la URL base en pareja.
