SDK de API DeepSeek: usa el SDK de OpenAI y cambia endpoints

Por qué el SDK de OpenAI es el SDK de API DeepSeek

Cuando la gente busca un SDK de API DeepSeek, espera un paquete con el nombre del proveedor. En la práctica, la propia documentación de DeepSeek describe llamar a su API a través del SDK de OpenAI con una URL base diferente, porque la API sigue el formato de petición y respuesta de OpenAI. Consulta su documentación actual para la URL base exacta y los nombres de los modelos; ellos son la autoridad sobre su servicio.

La consecuencia es útil. Cualquier código escrito contra la biblioteca cliente de OpenAI puede comunicarse con cualquier servidor que implemente los mismos endpoints, que aquí son POST /v1/chat/completions, POST /v1/responses y GET /v1/models. Moverse entre proveedores se convierte en un cambio de configuración en lugar de una reescritura. El resto de este artículo muestra el patrón en Python, Node y curl, luego una estructura que hace el intercambio trivial.

Configuración en Python

Instala el paquete oficial y apúntalo al endpoint:

Copypip install openai

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.deepseekapi.top/v1",
    api_key="YOUR_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain idempotency in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Consigue una clave en la página de clave de API. Los nuevos usuarios pueden reclamar $0,50 de crédito de prueba con un solo clic, sin necesidad de tarjeta. El artículo API de DeepSeek en Python profundiza en este lenguaje, incluyendo el manejo de errores.

Configuración en Node.js

Copynpm install openai

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseekapi.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "List four uses of a message queue." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

El patrón es idéntico: base URL, clave, modelo. El streaming devuelve Eventos enviados por el servidor, y la biblioteca los convierte en un iterador asíncrono. Las llamadas a funciones siguen el mismo esquema que otras APIs compatibles con OpenAI: pasa tools, lee el streaming de tool_calls y devuelve los resultados como mensajes role: "tool".

Haz que el endpoint sea intercambiable

No codifiques los tres valores en duro. Léelos desde el entorno y envuelve la creación del cliente en una función. Luego, moverse de un endpoint a otro significa editar un archivo .env, no el código fuente.

Copyimport os
from openai import OpenAI

def make_client():
    return OpenAI(
        base_url=os.environ.get("LLM_BASE_URL", "https://api.deepseekapi.top/v1"),
        api_key=os.environ["LLM_API_KEY"],
    )

MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt: str) -> str:
    r = make_client().chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
    )
    return r.choices[0].message.content

Ahora un proveedor diferente solo necesita tres variables de entorno. Los SDKs oficiales también leen OPENAI_API_BASE y OPENAI_API_KEY en algunas versiones, pero las variables explícitas son más claras y evitan sorpresas cuando ejecutas varios proveedores a la vez.

Si usas TypeScript u otro lenguaje, la idea es la misma: una función fábrica, tres variables, sin nombres de proveedor dispersos por el código fuente. Un error común es permitir que el nombre del proveedor se filtre en los nombres de funciones, mensajes de registro y nombres de variables, lo que hace que un cambio posterior sea más difícil de lo necesario. Nombra las cosas según la tarea (ask, summarise) en lugar del proveedor.

Mantén una pequeña prueba que envíe un prompt fijo a través de ask() y verifique que la respuesta no esté vacía. Ejecútala después de cada cambio de endpoint; captura URLs y claves incorrectas en segundos.

Qué se mantiene igual y qué cambia al intercambiar

La última fila es la que atrapa a la gente. Un endpoint es compatible a nivel de protocolo, no a nivel de comportamiento. Dos proveedores pueden aceptar solicitudes idénticas y dar respuestas muy diferentes. El modelo aquí es un único modelo de pesos abiertos de un proveedor independiente, ajustado para responder sin rechazos de contenido para uso adulto lícito, y no es la API oficial de DeepSeek ni de ningún otro laboratorio. Vuelve a probar los prompts que ajustaste para otro modelo.

Funcionalidades que tiene este endpoint y las que no

• Soportado: chat completions, el formato Responses, listado de modelos, streaming, llamadas a funciones, modo JSON (response_format con json_object), y el paso de temperatura, top_p, stop, seed y las penalizaciones.
• No ofrecido: generación de imágenes, audio o video, embeddings, ajuste fino.
• Límites: una ventana de 100.000 tokens, un cuerpo máximo de 8 MB, 8 peticiones simultáneas y 300 por minuto con una clave completa (2 y 60 con una clave de prueba).
• Errores: HTTP 429 con el código rate_limited o concurrency, y un encabezado Retry-After: 5 en caso de sobrecarga temporal.

Si tu código llama a un endpoint de embeddings, necesitarás otro proveedor para esa parte y puedes mantener el chat aquí. Dividir por tarea es una razón común para el patrón de variables de entorno anterior.

Una lista de verificación de migración

Cuando cambias un endpoint por otro en un proyecto existente, recorre una lista corta en lugar de cambiar todo a la vez.

1. Demuestra el endpoint. Envía una solicitud con curl y confirma que recibes texto. Llama a GET /v1/models y verifica que el id uncensored esté listado.
2. Cambia los tres valores. Base URL, clave, nombre del modelo, nada más. No toques los prompts aún.
3. Ejecuta tus pruebas existentes. Si tienes pruebas de regresión de prompts, ejecútalas y anota cuáles fallan. Los fallos suelen ser comportamentales, como un formato de salida diferente, no errores de protocolo.
4. Verifica los parámetros. Elimina las opciones que el endpoint no necesita. Mantén temperature, top_p, stop y seed si los usas.
5. Prueba el streaming y las herramientas por separado. Los errores de streaming a menudo se ocultan en el código del cliente que asume una disposición específica de los fragmentos. Las llamadas a funciones necesitan un esquema que el modelo siga bien, así que prueba con tus funciones reales.
6. Mide el costo y la latencia con tráfico real. Compara un día de peticiones, no un solo prompt.

Haz esto en una rama o con un feature flag que enrute una pequeña parte del tráfico al nuevo endpoint. Como el código del cliente es compartido, revertir el cambio consiste en modificar una variable de entorno.

Maneja los reintentos y revisa el uso

Los SDKs reintentan algunos errores por defecto, pero aún debes manejar el 429 tú mismo, ya que los límites de concurrencia son reales en producción. Captura la excepción de límite de tasa, espera el número de segundos en Retry-After (5 en caso de sobrecarga) y reintenta unas cuantas veces. Las peticiones fallidas no se cobran, así que los reintentos son seguros para tu saldo.

Registra usage.prompt_tokens y usage.completion_tokens en cada llamada. La tarifa es de $0,15 por cada 1M de tokens de entrada y $0,50 por cada 1M de tokens de salida, así que una llamada con 2.000 tokens de entrada y 600 de salida cuesta 2.000 × $0,15 / 1M + 600 × $0,50 / 1M = $0,0003 + $0,0003 = $0,0006. Los encabezados de la respuesta también incluyen X-Balance-USD con el crédito restante. Consulta la página de precios para recargas y bonificaciones, y la documentación para la lista completa de parámetros.

Editores y otras herramientas

Los tres valores se transfieren a cualquier herramienta con una configuración de proveedor compatible con OpenAI. El artículo sobre cómo usar una API estilo DeepSeek en Cursor explica cómo configurar uno de estos editores. En cada herramienta, los campos tienen etiquetas ligeramente distintas, pero siempre debes ingresar la base URL que termina en /v1, la clave y el nombre del modelo.

Más guías

• Costo de la API de DeepSeek frente a la API de OpenAI: Ejemplos resueltos
• Clave de API de DeepSeek: acceso a LLM sin censura