Para usar DeepSeek API con Python, necesitas una clave de DeepSeek, la biblioteca openai y un cliente configurado con https://api.deepseek.com. La guía oficial de primera llamada documenta esta integración. Aquí crearás un programa que redacta un recordatorio en español y después probarás una versión que muestra el texto mediante streaming.
El ejemplo utiliza deepseek-flash y la interfaz Chat Completions. Las solicitudes se envían al servicio alojado por DeepSeek: no necesitas descargar el modelo ni instalar una GPU para seguir estos pasos.
Prepara tu clave y el entorno de Python
Necesitas conexión a internet, una terminal y Python 3.10 o posterior, según los requisitos actuales de la biblioteca oficial de OpenAI para Python. Aunque el paquete se llama openai, en este tutorial usarás una clave y un servidor de DeepSeek.
- Abre la plataforma oficial de DeepSeek e inicia sesión o crea una cuenta.
- Entra en la sección de claves API, crea una clave y guárdala de forma privada.
- Revisa el saldo disponible antes de ejecutar el programa. La API tiene facturación por uso; consulta las condiciones y tarifas oficiales.
Usaremos un entorno virtual de Python para mantener las dependencias del proyecto separadas. Los comandos ejecutan directamente el Python de ese entorno, por lo que no necesitas activarlo.
En Windows con PowerShell
py -3 --version
mkdir deepseek-python
cd deepseek-python
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade openaiComprueba que la versión mostrada cumpla el requisito. Si tu instalación reconoce python en lugar de py, comprueba su versión y usa python -m venv .venv para crear el entorno.
En macOS o Linux
python3 --version
mkdir deepseek-python
cd deepseek-python
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade openaiConfigura DEEPSEEK_API_KEY
En la misma terminal, define la variable de entorno que leerá el programa. Sustituye PEGA_AQUI_TU_CLAVE por tu clave real. En PowerShell:
$env:DEEPSEEK_API_KEY = "PEGA_AQUI_TU_CLAVE"En macOS o Linux:
export DEEPSEEK_API_KEY="PEGA_AQUI_TU_CLAVE"Ejecuta los ejemplos desde esa terminal. El script usa os.getenv() para leer el entorno; no carga automáticamente un archivo .env. Si abres otra terminal, configura allí la variable también.
La clave puede quedar en el historial de comandos. Mantén privada la terminal y no incluyas el secreto en capturas, repositorios o mensajes de soporte. Para una aplicación desplegada, utiliza la configuración privada del servidor o un gestor de secretos, siguiendo prácticas como las de gestión de secretos de OWASP.
Haz tu primera llamada a DeepSeek desde Python
Crea un archivo llamado consulta_deepseek.py dentro de la carpeta deepseek-python y pega este programa completo. Pedirá un recordatorio breve con datos concretos que podrás comprobar al leer la respuesta.
import os
from openai import APIError, APIStatusError, OpenAI
clave = os.getenv("DEEPSEEK_API_KEY", "").strip()
if not clave:
raise SystemExit("Configura DEEPSEEK_API_KEY en esta terminal.")
mensajes = [
{"role": "system", "content": "Escribe en español latinoamericano neutro."},
{
"role": "user",
"content": (
"Redacta un recordatorio de máximo 60 palabras para una reunión "
"del equipo: jueves, 16:00, sala Azul, duración 30 minutos. "
"No inventes enlaces ni otros datos."
),
},
]
try:
with OpenAI(
api_key=clave,
base_url="https://api.deepseek.com",
timeout=60.0,
max_retries=0,
) as cliente:
respuesta = cliente.chat.completions.create(
model="deepseek-flash",
messages=mensajes,
max_tokens=512,
stream=False,
extra_body={"thinking": {"type": "disabled"}},
)
except APIStatusError as error:
raise SystemExit(f"Error HTTP {error.status_code}. Revisa la tabla de errores.")
except APIError as error:
raise SystemExit(f"Error del SDK: {type(error).__name__}.")
if not respuesta.choices:
raise SystemExit("La respuesta no contiene ninguna opción.")
opcion = respuesta.choices[0]
texto = opcion.message.content or ""
print(texto if texto.strip() else "No se recibió texto final.")
print("\nFinalizació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)
else:
print("No se recibió información de consumo.")
if not texto.strip() or opcion.finish_reason != "stop":
raise SystemExit("Revisa la respuesta antes de usarla como resultado completo.")Ejecuta el archivo desde PowerShell:
.\.venv\Scripts\python.exe consulta_deepseek.pyO desde macOS o Linux:
./.venv/bin/python consulta_deepseek.pySi la solicitud se completa, verás el recordatorio, el motivo de finalización y los datos de consumo que devuelva la API. Revisa que el texto conserve jueves, 16:00, sala Azul y 30 minutos, y que no agregue información. La redacción puede variar en cada ejecución.
Si aparece un error HTTP o del SDK, consulta la tabla de errores. Evita ejecutar el programa repetidamente sin revisar el mensaje: cada ejecución inicia una nueva solicitud.
Entiende la configuración y comprueba el resultado
Estas son las decisiones principales del ejemplo. Los límites elegidos para la demostración pueden ajustarse a tu tarea:
| Elemento | Qué debes entender |
|---|---|
base_url | Es la dirección base del servicio. El SDK añade la ruta de Chat Completions al hacer la llamada. |
model="deepseek-flash" | Es el identificador de modelo elegido para este tutorial. Comprueba los identificadores oficiales antes de adaptar ejemplos antiguos. |
messages | Contiene las instrucciones y el mensaje que envías. Cambia el contenido del mensaje de usuario para probar otra tarea. |
max_tokens=512 | Es el presupuesto de generación elegido para el ejemplo; no es un número de palabras ni el máximo del servicio. |
thinking: disabled | Selecciona explícitamente el modo sin pensamiento para esta tarea breve. |
timeout=60.0 y max_retries=0 | Configuran la espera de red y desactivan los reintentos automáticos del SDK en esta demostración. |
DeepSeek documenta deepseek-flash y deepseek-v4-pro en su catálogo de modelos. Si cambias de modelo, revisa sus capacidades y tarifas. En el cliente, conserva la URL base: no la sustituyas por platform.deepseek.com ni le agregues /chat/completions.
El modo de pensamiento está activado de forma predeterminada. Por eso el código lo desactiva expresamente mediante extra_body, que es la forma documentada de enviar esta opción con el SDK.
Para interpretar la respuesta, consulta la referencia de Chat Completions y revisa estos campos:
choices[0].message.content: contiene el texto de la respuesta.finish_reason:stopindica una finalización normal;lengthindica que se alcanzó un límite y el contenido puede estar truncado.usage: informa el consumo. El programa muestra los tokens de entrada y salida cuando están disponibles.
Una finalización normal no garantiza que el recordatorio sea correcto. Compara siempre el resultado con los datos del mensaje. Si recibes length, reduce la tarea o ajusta el presupuesto de generación antes de volver a intentarlo.
Muestra la respuesta progresivamente con streaming
Con streaming puedes mostrar el texto mientras llega. Crea otro archivo, stream_deepseek.py, en la misma carpeta. Este ejemplo es independiente del anterior y utiliza la misma variable de entorno:
import os
from openai import APIError, APIStatusError, OpenAI
clave = os.getenv("DEEPSEEK_API_KEY", "").strip()
if not clave:
raise SystemExit("Configura DEEPSEEK_API_KEY en esta terminal.")
partes = []
finalizacion = None
uso = None
try:
with OpenAI(
api_key=clave,
base_url="https://api.deepseek.com",
timeout=60.0,
max_retries=0,
) as cliente:
with cliente.chat.completions.create(
model="deepseek-flash",
messages=[
{
"role": "user",
"content": (
"Redacta en español un recordatorio de máximo 60 palabras "
"para una reunión del equipo: jueves, 16:00, sala Azul, "
"duración 30 minutos. No inventes enlaces ni otros datos."
),
}
],
max_tokens=512,
stream=True,
stream_options={"include_usage": True},
extra_body={"thinking": {"type": "disabled"}},
) as flujo:
for fragmento in flujo:
if fragmento.usage is not None:
uso = fragmento.usage
if not fragmento.choices:
continue
opcion = fragmento.choices[0]
contenido = opcion.delta.content
if contenido:
partes.append(contenido)
print(contenido, end="", flush=True)
if opcion.finish_reason is not None:
finalizacion = opcion.finish_reason
except APIStatusError as error:
raise SystemExit(f"\nError HTTP {error.status_code}. El texto puede estar incompleto.")
except APIError as error:
raise SystemExit(f"\n{type(error).__name__}: no se confirmó el final del texto.")
except Exception as error:
raise SystemExit(
f"\nError de transmisión o lectura: {type(error).__name__}. "
"El texto puede estar incompleto."
)
print("\n\nFinalización:", finalizacion or "sin confirmar")
if uso is not None:
print("Tokens de entrada:", uso.prompt_tokens)
print("Tokens de salida:", uso.completion_tokens)
else:
print("No se recibió información de consumo.")
if finalizacion != "stop" or not "".join(partes).strip():
raise SystemExit("La respuesta no se confirmó como completa.")Ejecuta la versión de streaming en PowerShell:
.\.venv\Scripts\python.exe stream_deepseek.pyEn macOS o Linux:
./.venv/bin/python stream_deepseek.pyEl programa lee delta.content, imprime únicamente fragmentos con contenido y conserva el motivo de finalización. También recoge usage cuando aparece, de acuerdo con el formato de streaming de Chat Completions.
Si se detecta un error al leer la transmisión, el script avisa que el texto puede estar incompleto y no vuelve a enviar automáticamente la consulta. La ausencia de datos de consumo tampoco debe interpretarse como consumo cero.
Amplía el ejemplo: conversación y razonamiento
Conserva el historial al añadir otro turno
La guía de conversaciones de DeepSeek explica que Chat Completions no recupera automáticamente el contexto de solicitudes anteriores. Para pedir una modificación del recordatorio, envía de nuevo la conversación necesaria.
- Conserva los mensajes originales de la lista
mensajes. - Añade la respuesta recibida con el rol
assistant. - Añade la nueva instrucción con el rol
user, por ejemplo: «Hazlo más breve y conserva todos los datos». - Envía esa lista actualizada en
messagesal realizar la siguiente llamada.
Este recorrido corresponde al ejemplo de texto sin pensamiento ni herramientas. El historial enviado vuelve a formar parte de la entrada: conserva lo necesario para la tarea y revisa su consumo antes de convertir el programa en una conversación larga.
Activa el pensamiento cuando la tarea lo necesite
Para probar una tarea de razonamiento, cambia "disabled" por "enabled" en extra_body. Puedes añadir reasoning_effort="high" a la llamada según la configuración oficial del modo de pensamiento.
Revisa también el presupuesto de generación para la tarea nueva. El campo reasoning_content y el texto final content tienen funciones distintas; los ejemplos de esta guía muestran el texto final. Además, parámetros como temperature no tienen efecto en modo de pensamiento.
Si añades llamadas a herramientas, consulta las reglas específicas para conservar los mensajes y los campos de razonamiento. No extrapoles el manejo del historial del ejemplo básico a ese flujo.
Errores frecuentes de DeepSeek API en Python y cómo resolverlos
Primero identifica si el problema ocurre en tu entorno local o si DeepSeek respondió con un estado HTTP. La referencia oficial de errores permite distinguir problemas de formato, autenticación, saldo y capacidad.
| Error o síntoma | Qué revisar |
|---|---|
ModuleNotFoundError: openai | Instala el paquete con el mismo Python de .venv que ejecuta el archivo. |
| Importación circular o módulo parcialmente inicializado | Evita llamar openai.py al archivo o crear una carpeta local openai que oculte la biblioteca. |
Falta DEEPSEEK_API_KEY | Define la variable en la terminal desde la que ejecutas Python. Estos scripts no cargan archivos .env. |
400 o 422 | Corrige el formato o los parámetros. Comprueba el modelo, la interfaz y el modo elegidos. |
401 | Revisa la clave de DeepSeek, la variable que lee el programa y la URL de destino. |
402 | Comprueba el saldo de la cuenta. Crear otra clave no añade fondos. |
429 | Reduce la frecuencia o la cantidad de solicitudes simultáneas. Organiza una cola si automatizas muchas tareas. |
500 o 503 | Puede haber un fallo del servicio o sobrecarga. Espera antes de reintentar y limita los intentos. |
APITimeoutError o APIConnectionError | Revisa la conexión y el tiempo de espera. No supongas que el problema es la clave. |
Para comprobar qué intérprete y versión del paquete está usando el proyecto, ejecuta en PowerShell:
.\.venv\Scripts\python.exe -c "import sys, openai; print(sys.executable); print(openai.__version__)"En macOS o Linux:
./.venv/bin/python -c "import sys, openai; print(sys.executable); print(openai.__version__)"Estos comandos muestran la configuración local y no envían una solicitud a DeepSeek. Si el intérprete no corresponde al entorno del proyecto, corrige primero la instalación o el comando de ejecución.
Controla consumo, tiempos de espera y reintentos
El acceso al chat de DeepSeek y el consumo de su API son servicios distintos. Para calcular el costo de una integración, consulta las tarifas del modelo: distinguen entrada, salida y entrada con caché, además de las condiciones de horario aplicables. No presupongas que tendrás crédito promocional.
Usa los valores de usage para observar el consumo real de tus solicitudes. La explicación oficial de tokens ayuda a entender la unidad de facturación; no conviertas una cantidad de palabras en un costo exacto mediante una proporción fija.
Los ejemplos utilizan timeout=60.0 como configuración de espera de red. No es una promesa de que toda la generación termine en 60 segundos. También establecen max_retries=0 para que el SDK no repita automáticamente una solicitud fallida durante el diagnóstico.
El SDK permite configurar los reintentos y los tiempos de espera. Cuando automatices el proceso, define una política limitada para fallos temporales y evita superponer varios mecanismos de reintento. Un timeout no confirma por sí solo que el servidor haya dejado de procesar la solicitud.
DeepSeek también aplica límites de concurrencia por cuenta. Si aumentas el volumen, limita las solicitudes simultáneas y revisa los errores antes de aumentar la carga.
Qué revisar al adaptar código de otro tutorial
Mantén juntos el servidor, la clave, el modelo y la estructura de la interfaz utilizada. Un ejemplo de un proveedor intermediario puede requerir otros identificadores y credenciales. Para esta integración, vuelve a la configuración oficial de DeepSeek.
DeepSeek también documenta Responses API, que utiliza client.responses.create(), entradas como input y una salida accesible mediante output_text. Si adaptas un ejemplo de esa interfaz, revisa sus parámetros y eventos de streaming: no son los mismos objetos que procesa el código de Chat Completions de esta guía.
Empieza modificando la tarea del primer programa y comprueba que conserva la información solicitada. Cuando el resultado y el consumo sean adecuados para tu caso, incorpora streaming o historial según lo que necesite tu aplicación.
Verificación documental: 10 de noviembre de 2026. Los dos scripts se revisaron con las fuentes oficiales y se comprobó su sintaxis localmente. No se ejecutaron solicitudes autenticadas contra la API durante esta revisión.