API Docs - DeepSeek

DeepSeek AI es una plataforma de inteligencia artificial avanzada orientada a hispanohablantes, comparable a los mejores modelos tipo GPT-4, pero con la ventaja de ser gratuita, abierta y sin registro para usuarios finales.

Esta plataforma ofrece a desarrolladores una API robusta que permite integrar las capacidades de DeepSeek en aplicaciones propias, ya sea para construir chatbots, asistentes virtuales, herramientas de traducción o cualquier solución impulsada por IA en español.

En este artículo te proporcionamos una guía detallada de la API de DeepSeek: qué es, cómo funciona, cómo autenticarse y ejemplos prácticos en varios lenguajes de programación.

¿Qué es la API de DeepSeek Español?

La API de DeepSeek es una interfaz de programación de aplicaciones que permite a los desarrolladores enviar solicitudes al modelo de IA de DeepSeek y obtener respuestas automatizadas.

En términos sencillos, una API actúa como un puente entre tu aplicación y el servicio de IA: tu aplicación envía una pregunta o solicitud en formato estructurado, y DeepSeek responde con un texto generado por sus modelos de IA.

Esta API ha sido diseñada para ser compatible con el formato de la API de OpenAI (la usada por servicios como ChatGPT), lo que significa que si estás familiarizado con la API de OpenAI, te resultará muy fácil adaptarte a DeepSeek.

Por ejemplo, los endpoints (puntos de acceso) y el formato de los datos (como mensajes de chat, parámetros de temperatura, etc.) son muy similares a los de OpenAI, facilitando la migración o uso simultáneo.

¿Por qué usar la API de DeepSeek? Principalmente por su potencia y ahorro de costes.

A diferencia de otras soluciones comerciales, DeepSeek ofrece acceso gratuito e ilimitado a sus modelos de IA en ciertos casos, y en general una estructura de precios sumamente competitiva para uso a gran escala.

Además, sus modelos son de código abierto, por lo que la comunidad puede auditarlos e incluso ejecutarlos localmente si se desea.

Esto garantiza transparencia y privacidad: puedes desplegar DeepSeek en tus propios servidores si necesitas mantener los datos en casa.

Para los desarrolladores hispanohablantes, DeepSeek Español destaca por entender y responder perfectamente en español, optimizado para nuestro idioma y cultura.

En resumen, la API de DeepSeek te da acceso a una IA tipo GPT en español, sin las barreras de pago por adelantado, cuotas estrictas ni cajas negras propietarias.

Cómo obtener una clave API y autenticarse

Para empezar a usar la API de DeepSeek, lo primero que necesitas es obtener una clave de API (API Key). Esta clave es un código único que identifica tu cuenta y te permite realizar llamadas a la API.

A continuación, se resumen los pasos básicos:

Crear una cuenta en DeepSeek Open Platform: Dirígete al sitio oficial de DeepSeek (por ejemplo, la plataforma abierta en platform.deepseek.com) y regístrate con tu correo electrónico o cuenta de Google/Apple. (Si ya usas DeepSeek desde la web gratuita, igual necesitas crear una cuenta para obtener claves de API.)
Generar una nueva clave API: Una vez dentro de tu panel, navega a la sección “API Keys” en el menú lateral. Haz clic en “Crear nueva clave” (Create new API Key). Ponle un nombre identificativo (por ejemplo, «ProyectoChatbot») y confirma. La plataforma te mostrará tu clave una sola vez – cópiala y guárdala de inmediato en un lugar seguro. (Por seguridad, no podrás volver a ver esa clave luego. Si la pierdes, deberás generar otra).

Interfaz de la plataforma DeepSeek mostrando la sección de creación de claves API.

Almacenar la clave de forma segura: No compartas tu clave públicamente ni la incluyas directamente en el código fuente que subas a repositorios. Lo ideal es guardarla en un gestor de contraseñas o usar variables de entorno en tus proyectos para cargarla en tiempo de ejecución. Recuerda que quien tenga tu API Key podrá hacer peticiones a tu nombre, pudiendo agotar tu cuota o generarte costes.

Una vez tengas tu API Key, todas las solicitudes a la API deben llevar esta clave para autenticación.

DeepSeek utiliza autenticación tipo Bearer en las cabeceras HTTP. En la práctica, esto significa que en cada petición HTTP debes incluir una cabecera Authorization con el formato:

Authorization: Bearer TU_CLAVE_API

Reemplazando «TU_CLAVE_API» por la cadena de tu clave.

Por ejemplo, si tu clave fuera 123abc..., la cabecera sería: Authorization: Bearer 123abc.... Sin una clave válida, la API rechazará tus llamadas con errores de autenticación (código 401 Unauthorized).

Endpoint principal: Chat Completions (conversaciones)

La API de DeepSeek ofrece varios endpoints (urls específicas para distintas funciones).

El más importante y utilizado es el endpoint de completado de chat, que funciona de forma muy parecida al de ChatGPT.

Este endpoint recibe un historial de mensajes (rol y contenido) y devuelve la siguiente respuesta del asistente de IA.

URL base (Base URL): https://api.deepseek.com – esta es la dirección principal para las llamadas. Opcionalmente, puedes usar https://api.deepseek.com/v1 para mayor compatibilidad con librerías de OpenAI (el sufijo /v1 aquí es solo para imitar la ruta de OpenAI, no indica versión de modelo).
Ruta del endpoint de chat: /chat/completions – a esta ruta se envían las conversaciones. En conjunto con la URL base, queda: https://api.deepseek.com/chat/completions.
Método HTTP: POST. Las interacciones se envían mediante peticiones POST con un cuerpo en formato JSON.
Cuerpo (payload): Debe incluir al menos dos campos:
- model: el nombre del modelo de DeepSeek que deseas usar (ver sección de modelos disponibles abajo). Por ejemplo "deepseek-chat".
- messages: una lista (array) de mensajes que forman la conversación. Cada mensaje es un objeto con la estructura {"role": "...", "content": "..."}. Los roles pueden ser:
  - "system": para dar contexto inicial o instrucciones al modelo (opcional pero útil).
  - "user": para mensajes enviados por el usuario (tu aplicación o el usuario final).
  - "assistant": para incluir, si lo deseas, alguna respuesta previa del asistente (al continuar una conversación existente).
  - (DeepSeek además soporta un rol "tool" especial para integraciones avanzadas, pero en casos básicos no se utiliza).

Un ejemplo mínimo de cuerpo JSON sería:

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "Eres un asistente útil y conciso."},
    {"role": "user", "content": "Hola, ¿qué puedes hacer?"}
  ]
}

Este payload le indica a la API que use el modelo deepseek-chat (el modelo genérico de conversación) y que inicie la conversación con un mensaje del sistema que define el comportamiento del asistente, seguido de una pregunta del usuario.

La API responderá con un mensaje de rol "assistant" que podrás mostrar en tu aplicación.

Respuesta: La respuesta de la API también será en formato JSON. Si la solicitud fue exitosa (código HTTP 200), obtendrás un objeto JSON con, entre otros, un campo choices que contiene las respuestas generadas.

El contenido de la respuesta del asistente típicamente se encuentra en response["choices"][0]["message"]["content"]. Además, incluye información de uso de tokens (usage) y otros detalles. Un ejemplo simplificado de respuesta podría ser:

{
  "id": "chatcmpl-abc123...",
  "object": "chat.completion",
  "created": 1690000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "¡Hola! Soy DeepSeek, un modelo de IA listo para ayudarte en lo que necesites. Puedo responder preguntas, brindar explicaciones, traducir textos y mucho más."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 32,
    "total_tokens": 53
  }
}

Como puedes ver, el contenido generado por la IA está en choices[0].message.content en este caso. Tu aplicación deberá extraer ese texto para presentarlo al usuario.

Parámetros adicionales: Al igual que la API de OpenAI, DeepSeek permite ajustar parámetros para afinar las respuestas. Algunos de los más utilizados son:

temperature: control de aleatoriedad en las respuestas (valor entre 0 y 2, por defecto 1). Un valor bajo (ej. 0.2) hace las respuestas más deterministas y repetibles, mientras que un valor alto (ej. 0.8) las hace más creativas.
max_tokens: número máximo de tokens que devolverá la respuesta. Puedes limitarlo para controlar la longitud de la salida; por defecto son 4096 tokens máximos para el modelo chat (o más si el modelo lo permite).
top_p: alternativa a temperature para muestreo por núcleo (nucleus sampling). Por defecto 1, pero si por ejemplo pones top_p: 0.5, el modelo solo considera las opciones que suman 50% de probabilidad total, limitando la diversidad.
frequency_penalty y presence_penalty: valores entre -2 y 2 que penalizan repetición de tokens ya vistos para fomentar contenido nuevo (presence) o penalizan frecuencia de aparición para reducir redundancia. Normalmente se dejan en 0.
stream: valor booleano (true/false) que indica si quieres la respuesta en streaming. Si stream: true, la API irá enviando fragmentos parciales de la respuesta conforme se genera (utilizando eventos server-sent), lo cual es útil para mostrar texto a medida que va saliendo (experiencia tipo stream de ChatGPT).

En la mayoría de casos básicos, no necesitas todos estos parámetros; con model, messages, y quizá ajustar temperature, es suficiente para empezar.

Pero ten en cuenta que están disponibles para afinar el comportamiento según tus necesidades.

Modelos disponibles en la API DeepSeek

Actualmente, la API de DeepSeek Español pone a disposición dos modelos principales de inteligencia artificial, cada uno con sus características:

deepseek-chat: Corresponde al modelo DeepSeek V3, orientado a conversación general. Es un modelo de gran tamaño (más de 600 mil millones de parámetros) entrenado con una arquitectura innovadora (Mixture of Experts). Destaca en comprensión de lenguaje, generación de textos, matemáticas y programación, ofreciendo respuestas coherentes y detalladas. Es el recomendado para la mayoría de usos conversacionales, ya que busca emular un asistente versátil al estilo ChatGPT.
deepseek-reasoner: Corresponde al modelo DeepSeek R1, enfocado en razonamiento avanzado. Está diseñado para sobresalir en tareas lógicas, resolución de problemas complejos y análisis de código, produciendo incluso explicaciones intermedias de su razonamiento (lo que se conoce como Cadena de pensamiento o CoT) antes de dar la respuesta final. DeepSeek-R1 tiene un costo computacional más bajo que V3 pero logra resultados excelentes en tareas difíciles gracias a su optimización en razonamiento. Si tu aplicación requiere explicaciones paso a paso (por ejemplo, depuración de código o resolver problemas matemáticos mostrando cómo se llegó a la solución), este modelo es ideal.

Ambos modelos aceptan entradas en español (y otros idiomas) y tienen una longitud de contexto muy amplia, de hasta 64,000 tokens.

Esto significa que puedes enviar conversaciones muy largas o documentos extensos como contexto en una sola solicitud, sin que el modelo «olvide» el comienzo.

En comparación, muchos modelos rivales manejan 4K o 8K tokens, por lo que DeepSeek destaca en este aspecto.

Por defecto, deepseek-chat genera hasta ~4K tokens de respuesta y deepseek-reasoner hasta ~32K tokens en una llamada, pero existen versiones ampliadas (beta) para salidas más largas si se necesita.

Para invocar cada modelo, simplemente especifica el nombre correspondiente en el parámetro model de tus solicitudes.

Por ejemplo, "model": "deepseek-chat" utilizará DeepSeek V3, mientras que "model": "deepseek-reasoner" utilizará R1.

Más adelante, en nuestros ejemplos de código, verás cómo elegir el modelo.

Ten en cuenta también que periódicamente DeepSeek lanza actualizaciones o nuevas versiones de estos modelos (V3-0324, R1-0528, etc., indicando fechas de versión), pero mantienen los alias deepseek-chat y deepseek-reasoner para siempre apuntar a la última versión estable de cada uno.

Ejemplos prácticos de uso de la API DeepSeek

A continuación, veremos ejemplos de cómo usar la API de DeepSeek en diferentes entornos y lenguajes de programación.

Incluiremos ejemplos con cURL (útil para probar rápidamente en terminal), Python (peticiones HTTP con la librería requests) y JavaScript (fetch en entorno navegador o axios/Node.js).

Todos los ejemplos asumen que ya cuentas con tu API Key y la has reemplazado en el código donde corresponda.

También usaremos el modelo deepseek-chat en los ejemplos, pero puedes cambiarlo por deepseek-reasoner si quieres probar el modelo de razonamiento.

Ejemplo con cURL (línea de comandos)

cURL es una herramienta de consola que permite realizar peticiones HTTP de forma sencilla.

Puedes usarla para probar la API directamente desde la terminal.

Aquí un ejemplo de uso de la API DeepSeek con cURL:

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY" \
  -d '{
        "model": "deepseek-chat",
        "messages": [
          {"role": "system", "content": "Eres un asistente útil."},
          {"role": "user", "content": "Hola, \u00bfpuedes presentarte?"}
        ],
        "stream": false
      }'

En este comando:

Usamos la URL base https://api.deepseek.com con la ruta /chat/completions.
Incluimos las cabeceras necesarias: Content-Type: application/json (porque enviamos JSON) y la cabecera de Autorización con nuestra API Key.
En -d mandamos el cuerpo JSON. Observa que hemos enviado dos mensajes: uno del sistema estableciendo contexto («Eres un asistente útil.») y la pregunta del usuario en español. stream está en false para obtener la respuesta completa de una vez (puedes ponerlo en true si deseas recibir en modo streaming).

Al ejecutar este comando, la respuesta será un JSON con la estructura explicada antes. Si todo fue bien, verás la respuesta del asistente en el campo choices -> message -> content.

Por ejemplo, podrías obtener algo así como: «¡Hola! Encantado de presentarme. Soy DeepSeek, un modelo de inteligencia artificial entrenado…» seguido del resto de la presentación.

Puedes ajustar los mensajes a tu gusto para probar diferentes preguntas.

Ejemplo con Python (petición HTTP con `requests`)

Python es uno de los lenguajes más populares para trabajar con APIs.

A continuación un ejemplo usando la librería requests para hacer una solicitud a la API DeepSeek y obtener la respuesta:

import requests
import json

API_KEY = "TU_API_KEY"  # Reemplaza con tu clave real
url = "https://api.deepseek.com/chat/completions"

# Cabeceras de la petición, incluyendo autenticación
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# Cuerpo de la petición con modelo y mensajes
data = {
    "model": "deepseek-chat",
    "messages": [
        {"role": "system", "content": "Eres un asistente de IA que responde en español de forma educada."},
        {"role": "user", "content": "¡Hola DeepSeek! \u00bfQu\u00e9 puedes hacer por m\u00ed?"}
    ],
    "stream": False  # cambiar a True si se desea streaming
}

# Realizar la petición POST a la API
response = requests.post(url, headers=headers, json=data)

# Verificar el código de estado HTTP
if response.status_code == 200:
    result = response.json()  # decodificar la respuesta JSON
    answer = result["choices"][0]["message"]["content"]
    print("Respuesta de DeepSeek:", answer)
else:
    print(f"Error {response.status_code}: {response.text}")

Explicación breve del código:

Establecemos la URL del endpoint y nuestras cabeceras, incluyendo la API Key.
Definimos el payload data con el modelo a usar, una lista de mensajes (aquí también uno de sistema y uno de usuario preguntando en español) y stream: False para una respuesta normal.
Hacemos la petición con requests.post.
Si la respuesta es exitosa (código 200), convertimos la respuesta JSON en un diccionario Python (response.json()) y extraemos el contenido de la respuesta del asistente. Luego la imprimimos.
Si ocurrió algún error (por ejemplo, 401 si la API Key es incorrecta, o 429 si se excedió algún límite), imprimimos el código y mensaje para depuración.

Este código imprimirá en consola la respuesta de DeepSeek a la pregunta dada.

Puedes modificar los mensajes o añadir varios mensajes de usuario-asistente para simular una conversación continua.

Recuerda manejar los errores en un entorno real (por ejemplo, reintentar o avisar al usuario si hay fallos de red o límite de velocidad).

Ejemplo con JavaScript (Fetch en navegador / Node.js con Axios)

En aplicaciones web o Node.js, también es muy sencillo utilizar la API. Veamos dos enfoques: usando fetch (disponible en navegadores modernos y en runtimes como Deno) y usando Axios (una popular librería HTTP para JS).

Usando fetch (nativo):

const apiKey = "TU_API_KEY";
const url = "https://api.deepseek.com/chat/completions";

const payload = {
  model: "deepseek-chat",
  messages: [
    { role: "system", content: "Eres un asistente de IA entrenado para ayudar." },
    { role: "user", content: "Hola, \u00bfme puedes explicar qu\u00e9 es DeepSeek?" }
  ],
  stream: false
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    const answer = data.choices[0].message.content;
    console.log("Respuesta de DeepSeek:", answer);
  })
  .catch(error => console.error("Error en la solicitud:", error));

En este snippet, construimos el payload similar a los ejemplos anteriores. Usamos fetch para enviar la petición POST con las cabeceras correspondientes.

Tras recibir la respuesta, la convertimos a JSON y extraemos data.choices[0].message.content para obtener la respuesta del asistente, que en este caso simplemente se imprime en consola.

En una aplicación real, podrías actualizar el DOM de la página para mostrar la respuesta al usuario.

Usando Axios (en Node.js o navegador):

import axios from 'axios';

const apiKey = "TU_API_KEY";
const url = "https://api.deepseek.com/chat/completions";

const payload = {
  model: "deepseek-chat",
  messages: [
    { role: "user", content: "Hola, quisiera saber c\u00f3mo integrarme con la API de DeepSeek." }
  ]
};

axios.post(url, payload, {
    headers: { "Authorization": `Bearer ${apiKey}` }
  })
  .then(res => {
    const answer = res.data.choices[0].message.content;
    console.log("Asistente:", answer);
  })
  .catch(err => {
    console.error("Error al llamar a la API:", err.response ? err.response.data : err.message);
  });

Con Axios, el código es muy parecido. Notar que no hace falta especificar Content-Type manualmente en Axios al enviar JSON, pues la librería lo asigna automáticamente.

El resto del flujo es igual: se envía la solicitud y luego se maneja la respuesta o el error.

Este ejemplo mostrará en consola la respuesta del asistente a la consulta dada.

Respuesta en streaming (opcional)

Tanto en fetch como en Axios (o cualquier otro método), si estableces stream: true en el payload, la API enviará las respuestas de forma parcial.

Manejar esto requiere trabajar con streams de red (por ejemplo, usando la API de EventSource, la función onmessage de fetch en entornos con soporte de streams, o en Node usando la respuesta como un stream legible).

Por simplicidad, nuestros ejemplos usan respuestas completas (stream: false), pero es bueno saber que la API de DeepSeek soporta streaming igual que la de OpenAI, lo cual mejora la experiencia de usuario al ver la respuesta formarse en tiempo real.

Consejos y mejores prácticas al usar la API

Para concluir, recopilamos algunos consejos útiles y prácticas recomendadas al trabajar con la API de DeepSeek Español:

Gestiona bien tu clave API: mantenla privada y segura. Considera rotarla periódicamente y revocar claves que ya no uses, tal como harías con cualquier clave secreta de un servicio en la nube.
Aprovecha la longitud de contexto: con hasta 64K tokens, puedes enviar documentos grandes o mantener conversaciones largas. Sin embargo, sé consciente de los tokens: textos muy extensos pueden implicar más tiempo de respuesta y, si aplica, mayor coste. Resume o depura el historial de mensajes si empieza a ser innecesariamente largo.
Experimenta con los parámetros de generación: si notas respuestas muy genéricas, prueba bajar la temperatura; si las notas muy aleatorias o dispersas, baja el top_p. Pequeños ajustes pueden mejorar la calidad según el caso de uso.
Utiliza el modelo adecuado: si tu aplicación requiere respuestas creativas y elaboración general, deepseek-chat (V3) es la mejor opción. Si en cambio buscas explicaciones paso a paso o resolver problemas complejos con transparencia en el proceso, prueba deepseek-reasoner (R1), que incluso puede devolver un razonamiento intermedio (chain-of-thought) antes de la respuesta final.
Ten en cuenta los límites y cuotas: aunque DeepSeek ha ofrecido acceso muy generoso (incluso gratuito) en sus inicios, si estás usando la API de forma intensiva es posible que existan límites de velocidad (requests por minuto) o costes por tokens. Consulta la documentación oficial para conocer límites actuales de rate limit y errores comunes. Maneja en tu código errores como 429 (Too Many Requests) implementando reintentos con backoff exponencial si fuera necesario.
Explora las funciones avanzadas: la API de DeepSeek incorpora características poderosas que puedes aprovechar. Por ejemplo, Function Calling, que permite que el modelo devuelva llamadas a funciones definidas para que tú las ejecutes (útil para construir agentes que interactúen con herramientas); JSON Output, donde puedes pedir al modelo que te dé la respuesta formateada estrictamente en JSON válido; o el ya mencionado modo streaming. Estas funciones están documentadas en la referencia oficial y pueden darle un plus de eficiencia a tu integración. Si no las necesitas de entrada, está bien, pero saber que existen te puede inspirar a implementarlas más adelante.

En resumen, la API de DeepSeek Español te abre las puertas a integrar en tus proyectos una de las IAs en español más potentes y accesibles del momento.

Con una documentación compatible con OpenAI, ejemplos claros y una comunidad activa, el camino para usar la API es bastante fluido.

Esperamos que esta guía te haya aclarado qué es la API de DeepSeek, cómo usarla y cómo empezar a crear aplicaciones inteligentes con ella.

¡Manos a la obra y a construir algo increíble con DeepSeek!