Las DeepSeek API Docs oficiales están en api-docs.deepseek.com. Allí encuentras la configuración inicial, los modelos disponibles, los parámetros de cada endpoint y las referencias de precios, límites y errores. Para administrar tu acceso, utiliza la plataforma oficial de DeepSeek.
Esta guía independiente explica cómo orientarte en esa documentación y enviar una primera solicitud con cURL o Python. El recorrido utiliza la API alojada por DeepSeek: los ejemplos conectan una aplicación con el servicio mediante una clave, sin depender del chat del navegador.
Encuentra la documentación que necesitas
Empieza por la tarea que quieres resolver. El inicio rápido muestra una llamada mínima; la referencia de una interfaz permite comprobar sus campos y respuestas. Leer ambas páginas evita copiar un parámetro válido para otro formato.
| Necesitas | Referencia oficial |
|---|---|
| Configurar tu primera solicitud | Your First API Call |
| Elegir un modelo o consultar tarifas | Models & Pricing |
| Revisar mensajes, parámetros y respuestas de chat | Chat Completions API |
| Trabajar con el formato Responses | Using the Responses API |
| Integrar un cliente del ecosistema Anthropic | Using the Anthropic API |
| Diagnosticar una solicitud fallida | Error Codes |
| Revisar concurrencia y cambios recientes | Rate Limit & Isolation y Change Log |
Comprueba también quién opera el servicio que vas a usar. Una guía de un proveedor externo puede requerir su propia cuenta, clave y dirección de conexión. Para este recorrido, utiliza los enlaces oficiales anteriores y conserva la misma configuración durante la primera prueba.
Prepara tu clave y los datos de conexión
Obtén una API key y guárdala fuera del código
Inicia sesión o crea una cuenta en la plataforma oficial y accede a la sección de API keys enlazada desde la documentación. Genera una clave para tu integración y comprueba que dispones de saldo para utilizar el servicio. Una clave válida identifica tu acceso, pero no sustituye el saldo necesario para las solicitudes facturables.
La API emplea autenticación Bearer: la clave viaja en el encabezado Authorization. Guárdala en una variable de entorno o en el gestor de secretos de tu infraestructura. Evita incluirla en repositorios, capturas, registros o código JavaScript enviado al navegador.
Los comandos de terminal de esta guía están escritos para Bash en Linux, macOS o WSL, con cURL instalado. Si tu terminal usa otro intérprete, abre Bash antes de ejecutarlos. Introduce la clave sin mostrarla en pantalla:
read -r -s -p "Pega tu API key de DeepSeek: " DEEPSEEK_API_KEY
printf '\n'
export DEEPSEEK_API_KEYPresiona Enter después de pegarla. La variable queda disponible para los procesos que ejecutes desde esa terminal. Si abres otra sesión, vuelve a configurarla. El ejemplo de Python comprobará su presencia antes de intentar conectarse.
Distingue la URL base del endpoint
Para el recorrido con Chat Completions, la configuración oficial de conexión utiliza estos valores:
- URL base del SDK:
https://api.deepseek.com. - Endpoint HTTP completo:
https://api.deepseek.com/chat/completions, con el métodoPOST. - Autenticación:
Authorization: Bearerseguido de tu clave. - Modelo del ejemplo:
deepseek-flash.
En Python, configura el cliente con la URL base. En cURL, escribe la dirección completa de la operación. Separar ambos conceptos ayuda a evitar rutas duplicadas o solicitudes dirigidas a la página de documentación en lugar de al servicio.
Envía tu primera solicitud con cURL o Python
Los dos ejemplos realizan la misma tarea: pedir una explicación breve en español. Puedes empezar con cURL para revisar la comunicación HTTP y usar Python cuando quieras incorporar la llamada a una aplicación. Ejecutar cada ejemplo envía una solicitud y puede consumir saldo.
Primera solicitud con cURL
Ejecuta el siguiente comando en la misma terminal donde configuraste la clave:
curl --include --silent --show-error \
https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
--data '{
"model": "deepseek-flash",
"messages": [
{
"role": "user",
"content": "Responde en español: explica en dos frases qué permite hacer una API."
}
],
"thinking": {"type": "disabled"},
"max_tokens": 256,
"stream": false
}'La opción --include muestra el estado HTTP junto con la respuesta. Busca el código de estado y, después de los encabezados, el cuerpo JSON. Si hay un error, conserva su código y mensaje para consultar la tabla de diagnóstico más abajo, sin compartir tu clave.
El ejemplo desactiva expresamente el modo de razonamiento, que está activado por defecto cuando no se configura lo contrario. Así se mantiene una primera solicitud sencilla. max_tokens: 256 es el límite de salida elegido para esta demostración; no representa el máximo del servicio ni una recomendación para todas las tareas.
Con stream: false recibes una respuesta completa en lugar de procesar fragmentos. Si necesitas modificar otros campos, contrástalos con la referencia de Chat Completions antes de agregarlos.
El mismo ejemplo con Python
La versión actual del SDK oficial de OpenAI para Python requiere Python 3.10 o superior. Desde una carpeta de trabajo, crea un entorno virtual e instala la biblioteca:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade openaiUsar la biblioteca openai en este ejemplo no cambia el destino de la solicitud: base_url apunta a DeepSeek y api_key contiene una clave de DeepSeek. Guarda el siguiente código como deepseek_inicio.py, con codificación UTF-8:
import os
from openai import OpenAI
api_key = os.getenv("DEEPSEEK_API_KEY", "").strip()
if not api_key:
raise SystemExit("Falta DEEPSEEK_API_KEY en esta terminal.")
with OpenAI(
api_key=api_key,
base_url="https://api.deepseek.com",
timeout=60.0,
max_retries=0,
) as cliente:
respuesta = cliente.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": (
"Responde en español: explica en dos frases "
"qué permite hacer una API."
),
}
],
extra_body={"thinking": {"type": "disabled"}},
max_tokens=256,
stream=False,
)
opcion = respuesta.choices[0]
print(opcion.message.content or "")
print("Motivo de finalización:", opcion.finish_reason)
if respuesta.usage is not None:
print("Tokens de entrada:", respuesta.usage.prompt_tokens)
print("Tokens de salida:", respuesta.usage.completion_tokens)Ejecútalo desde la misma terminal, con el entorno virtual activo:
python deepseek_inicio.pyEl parámetro propio thinking se envía mediante extra_body, como indica la guía de DeepSeek para el SDK de Python. Mantén este patrón cuando necesites transmitir ese ajuste.
En este ejemplo, timeout=60.0 configura el tiempo de espera del cliente y max_retries=0 desactiva sus reintentos automáticos. Son decisiones de la demostración, no garantías de latencia de DeepSeek. El SDK documenta cómo ajustar ambos comportamientos.
Comprueba el texto, la finalización y el consumo
En Chat Completions, revisa estos datos de la respuesta documentada:
choices[0].message.content: contiene el texto final del asistente.choices[0].finish_reason: indica por qué terminó la generación.stopseñala una finalización normal o una secuencia de parada;lengthpuede indicar que la salida quedó cortada por el límite.usage: informa el consumo de tokens. En el ejemplo de Python se imprimen los de entrada y salida.
Después, evalúa la respuesta con el objetivo que pediste: ¿está en español?, ¿explica la función de una API?, ¿respeta aproximadamente las dos frases? El estado HTTP y el motivo de finalización describen la ejecución; la revisión del contenido determina si te sirve. La redacción puede variar entre solicitudes.
Si aparece length, revisa la extensión solicitada y el límite que configuraste. Para una explicación breve, primero simplifica el pedido; aumenta el presupuesto de salida cuando la tarea lo justifique. No des por completo un texto solo porque alcanzaste a imprimirlo.
Elige el modelo y la interfaz sin mezclar formatos
Comprueba el identificador actual del modelo
La documentación vigente de modelos presenta deepseek-flash y deepseek-v4-pro. El primero se sirve actualmente mediante DeepSeek-V4.1-Flash-1017. Escribe en el campo model el identificador de API admitido, no un nombre de versión deducido del anuncio de lanzamiento.
El registro de cambios también explica la evolución de los nombres antiguos. Algunos aliases pueden seguir aceptándose aunque el modelo que originalmente identificaban se haya retirado. Antes de reutilizar un tutorial viejo, comprueba el identificador, la versión que lo atiende y las condiciones actuales.
Para consultar el catálogo desde una integración, la referencia de GET /models describe los modelos disponibles y sus metadatos. Un nombre reconocido no basta para elegir: verifica que el modelo admita el tipo de entrada y las funciones que necesita tu aplicación.
Usa el formato que espera tu aplicación
| Formato | Cuándo resulta útil | Qué debes distinguir |
|---|---|---|
| Chat Completions | Tu aplicación organiza la conversación en messages o quieres seguir los ejemplos de esta guía. | El texto del ejemplo está en choices[0].message.content. |
| Responses API | Tu integración utiliza client.responses.create(). | Trabaja con input; el ejemplo oficial de Python lee response.output_text. |
| Formato Anthropic | Tu cliente utiliza el SDK o la estructura de mensajes de Anthropic. | La URL base es https://api.deepseek.com/anthropic; revisa sus bloques de contenido y su tabla de compatibilidad. |
La compatibilidad tiene límites concretos. Por ejemplo, la guía de Responses indica que previous_response_id no está soportado para conservar una conversación en el servidor. La guía de Anthropic identifica parámetros que se ignoran, como top_k. Que una solicitud no produzca error no demuestra que todos los ajustes enviados estén actuando.
Si necesitas mantener una conversación, sigue las reglas de historial de la interfaz elegida. En Chat Completions, tu aplicación envía los mensajes previos con cada solicitud. Si incorporas herramientas y razonamiento, revisa además qué contenido exige conservar la guía correspondiente.
Consulta el costo y los límites antes de ampliar el uso
¿La API de DeepSeek es gratis?
La API tiene tarifas de uso. La página Models & Pricing explica la facturación y la deducción del saldo. El acceso al chat no acredita por sí mismo que dispongas de uso gratuito de API; comprueba las condiciones y el saldo de tu cuenta antes de ejecutar pruebas.
Para calcular el costo de una llamada al modelo, distingue la entrada recuperada de caché, la entrada sin caché y la salida. La tabla expresa los precios por un millón de tokens e incluye condiciones de horario. Por eso, multiplicar total_tokens por una sola tarifa puede producir un cálculo incorrecto.
Un token es una unidad de procesamiento de texto y no equivale necesariamente a una palabra. La guía Token & Token Usage recomienda tomar como referencia el consumo devuelto por la API. Úsalo para medir tus solicitudes reales en lugar de estimarlas únicamente por el número de caracteres.
La caché de contexto puede reutilizar partes coincidentes bajo las reglas del servicio. Comprueba los campos de consumo asociados; no presupongas un acierto de caché solo porque dos prompts se parecen. Si agregas Search o Fetch, revisa también su facturación por solicitudes exitosas.
Diferencia concurrencia, contexto y salida
La referencia de límites establece concurrencia por cuenta y modelo. Cada solicitud ocupa una conexión desde su envío hasta que termina la respuesta. Crear otra API key dentro de la misma cuenta no convierte ese límite en una cuota independiente.
La concurrencia cuenta solicitudes simultáneas; la ventana de contexto y el límite de salida se refieren a tokens. Son restricciones distintas. Antes de procesar un lote, revisa la capacidad del modelo, controla cuántas solicitudes mantienes abiertas y registra el consumo de cada tarea.
Qué revisar cuando una solicitud falla
Identifica primero el estado HTTP y el mensaje devuelto. La tabla siguiente resume los códigos de error oficiales más relevantes para comenzar:
| Código | Qué indica | Primera comprobación |
|---|---|---|
| 400 | Formato de solicitud incorrecto. | Revisa el JSON y los campos mencionados en el mensaje de error. |
| 401 | Fallo de autenticación. | Comprueba la variable de entorno, la clave y su envío al endpoint correcto. |
| 402 | Saldo insuficiente. | Revisa el saldo en la plataforma antes de repetir la solicitud. |
| 422 | Parámetros no válidos. | Contrasta tipos, valores y restricciones con la referencia de la interfaz. |
| 429 | Límite de solicitudes o concurrencia alcanzado. | Reduce el ritmo de envío y el número de solicitudes simultáneas. |
| 500 | Error del servidor. | Espera y realiza un reintento limitado; da seguimiento si persiste. |
| 503 | Servicio sobrecargado. | Espera antes de un nuevo intento y evita aumentar la carga. |
Para aislar el problema, vuelve al ejemplo pequeño de esta guía con texto ficticio. Si funciona, agrega tus mensajes y parámetros de uno en uno hasta localizar qué cambio introduce el fallo. Si también falla, revisa primero la conexión, la autenticación y el estado de la cuenta.
Evita bucles de reintento sin límite. Corregir una clave, añadir saldo o cambiar un parámetro requiere una acción específica. Para errores transitorios, define un máximo de intentos y una espera creciente; conserva los datos necesarios para investigar sin registrar secretos.
Si necesitas pedir ayuda, comparte el endpoint, el código HTTP y una versión del cuerpo de la solicitud sin datos sensibles. Retira el encabezado de autorización. Indica también el modelo utilizado y si llamas directamente por HTTP o mediante un SDK.
Continúa con la función que necesita tu integración
Una vez que el ejemplo básico funciona, amplíalo según la tarea. Estas rutas permiten avanzar sin incorporar varias funciones nuevas al mismo tiempo:
- Mostrar texto mientras se genera: consulta el streaming de tu interfaz. La guía de Responses describe sus propios eventos de finalización; usa un lector de eventos compatible con ese formato.
- Obtener datos estructurados: JSON Output explica cómo solicitar JSON y orientar su estructura en el prompt. Valida también campos y valores en tu aplicación, y contempla respuestas vacías o truncadas.
- Consultar funciones de tu sistema: Tool Calls describe cómo devolver al modelo los resultados de herramientas. Para funciones propias, tu aplicación valida los argumentos y ejecuta la operación; no basta con declarar su nombre.
- Analizar imágenes: la guía Vision documenta la entrada visual de
deepseek-flash. Revisa formatos, tamaños y estructura de la solicitud antes de enviar archivos. - Buscar o recuperar contenido web: Search & Fetch explica esas operaciones, sus respuestas y sus condiciones de uso.
Guarda el ejemplo mínimo que hayas conseguido ejecutar y consulta el registro de cambios antes de modificar modelos o interfaces. Así tendrás una referencia concreta para comparar cuando incorpores una nueva capacidad o aparezca un comportamiento diferente.
Documentación oficial revisada el 10 de noviembre de 2026. Ejemplos comprobados mediante revisión documental y de sintaxis, sin solicitudes autenticadas.