Guía de integración de la API DeepSeek: solicitudes compatibles con OpenAI a través de ECAIX

Esta guía explica cómo probar un identificador de modelo DeepSeek a través de ECAIX usando un endpoint compatible con OpenAI. Cubre la solicitud mínima funcional, ejemplos en Python y curl, verificación de modelos, streaming, salida estructurada, herramientas y un camino de diagnóstico para errores comunes.

La guía describe el acceso a través del gateway ECAIX a un modelo expuesto en el catálogo actual de ECAIX. No se afirma que ECAIX sea el endpoint oficial de la API DeepSeek ni que todas las características de DeepSeek estén disponibles a través de todas las rutas del gateway. Consulte la página del modelo en vivo y la documentación del proveedor antes de mover una carga de trabajo a producción.

Inicio rápido

Siga este procedimiento si ya tiene una aplicación con el SDK de OpenAI:

1. Abra la página del modelo DeepSeek v4.1 Flash y confirme que el identificador está disponible.
2. Cree una clave de la API de ECAIX.
3. Establezca la URL base compatible con OpenAI en https://ecaix.com/api/ai/v1.
4. Mantenga el SDK y el código de la aplicación sin cambios donde sea posible.
5. Ejecute la solicitud mínima que se muestra a continuación.
6. Agregue el streaming, la salida en formato JSON o herramientas solo después de que la solicitud básica funcione.

Endpoint y identificador de modelo

Para clientes compatibles con OpenAI, use:

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

El identificador de modelo no es una promesa permanente en un artículo de blog. Confírmelo en la dirección del catálogo de modelos en vivo antes de cada nueva integración o despliegue. Si necesita un miembro diferente de la familia DeepSeek, copie el identificador exacto de la página de detalles del modelo en lugar de adivinar un sufijo.

El formato del endpoint también es importante. El SDK debe recibir el camino base que termina en /v1; el cliente agrega /chat/completions o otro camino de operación. No agregue /chat/completions a base_url si el SDK ya lo agrega.

Python con el SDK de OpenAI

Instale o actualice el SDK de Python de OpenAI en su entorno virtual:

python -m pip install --upgrade openai

Luego, use la URL base de ECAIX y la clave de la API:

const client = new OpenAI({
  apiKey: process.env.ECAIX_API_KEY,
  baseURL: "https://ecaix.com/api/ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

console.log(response.choices[0].message.content);

Use código servidor para la solicitud de la API. Una aplicación web debe llamar a su propio backend en lugar de exponer la clave de ECAIX en el código JavaScript del lado del cliente.

Solicitud diagnóstica con curl

Si el SDK falla, retire el SDK de la ecuación y pruebe el endpoint directamente. Guarde los encabezados y el cuerpo por separado para distinguir un problema de HTTP de un problema de formato de respuesta.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

No pegue los encabezados guardados ni la respuesta en una solicitud pública sin eliminar claves de API, identificadores de solicitud, prompts, rutas de repositorio y datos de clientes.

Cómo diagnosticar la respuesta

Siga este orden:

1. Código de estado HTTP: determine si la solicitud llegó a un endpoint válido.
2. Cuerpo de la respuesta: lea el código de error del proveedor o gateway.
3. Identificador de modelo: copie el identificador exacto del directorio de modelos actual.
4. Autenticación: verifique el encabezado de la clave, la cuenta y los permisos.
5. Formato de la solicitud: reduzca el cuerpo a model, messages y un límite pequeño de salida.
6. Campos de características: agregue el streaming, JSON o herramientas uno a la vez.
7. Comportamiento del SDK: compare la solicitud del SDK con la solicitud directa con curl.

Esto evita confundir un problema de la biblioteca del cliente con el enrutamiento del modelo o las permisiones de la cuenta.

Respuestas en streaming

Si la aplicación necesita salida incremental, agregue el streaming solo después de que una solicitud normal funcione correctamente:

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

El comportamiento exacto de los eventos depende del endpoint y del SDK. Verifique cómo su marco maneja un delta vacío, un evento de uso final, interrupción de conexión y terminación de estilo [DONE]. No considere una implementación de streaming lista para producción hasta que haya probado interrupciones y retiros.

Salida estructurada y JSON

Si necesita una salida legible por máquina, comience con una solicitud normal y luego agregue la opción más pequeña de salida estructurada soportada por el endpoint y el modelo. Valide el contenido devuelto con un parser de JSON real. Una solicitud que dice "devuelve JSON" no es lo mismo que una respuesta con esquema obligatorio.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with keys title and priority."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

Si el parámetro response_format no es aceptado, puede depender del modelo y del camino. Si el endpoint devuelve un error por parámetro no soportado, elimine el campo y verifique la documentación del camino antes de intentar otro formato.

Llamadas a funciones y herramientas

La llamada a funciones requiere una prueba separada de la generación de texto. Empiece con una función inofensiva y revise el nombre y los argumentos devueltos antes de ejecutar algo.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

print(response.choices[0].message.tool_calls)

Un modelo puede devolver una respuesta válida de texto mientras que la llamada a funciones falla debido a la conversión de esquemas, parámetros no soportados o comportamiento específico del cliente. Nunca ejecute los argumentos devueltos de herramientas en un sistema de producción sin validar el esquema y agregar controles de autorización.

Caminos compatibles con OpenAI y Anthropic

ECAIX expone superficies de compatibilidad diferentes para diferentes clientes:

Consulte la documentación de Chat Completions, Respuestas y Mensajes de Anthropic antes de elegir un camino. El mismo identificador de modelo puede no exponer campos o comportamientos idénticos en cada superficie de compatibilidad.

Detalles actuales del modelo

Use las páginas de detalles en vivo para verificar capacidades y disponibilidad:

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Estas páginas son más confiables que un artículo estático para identificadores de modelos actuales, información de contexto y enlaces a precios.

Errores comunes

Lista de verificación de seguridad y producción

Antes de pasar a un proyecto de producción, confirme:

• Las claves de la API se almacenan en el lado del servidor y pueden rotarse.
• Los prompts y respuestas no contienen secretos no aprobados ni datos de clientes.
• Entiende si el gateway registra solicitudes y por cuánto tiempo se retienen los registros.
• La disponibilidad y los precios del modelo se verifican desde las páginas en vivo.
• Los tiempos de espera, retiros, idempotencia y límites de tasa se manejan por su aplicación.
• Las desconexiones de streaming no crean trabajos duplicados.
• Las llamadas a herramientas tienen listas blancas, validaciones, autorizaciones y registros de auditoría.
• Los términos del proveedor y del gateway permiten la carga de trabajo que planea enviar.

Registre la integración antes de la liberación

Anote la fecha, la versión del cliente, el identificador de modelo, el endpoint, el código de estado HTTP y las pruebas de características que realmente realizó. Si una prueba no se realizó, marque como no verificada. Este registro facilita la comparación con la próxima actualización de modelo o gateway y evita que un ejemplo de blog antiguo se convierta en una suposición no soportada para producción.

Preguntas frecuentes

¿Es esto el endpoint oficial de la API DeepSeek?

No. Este artículo documenta el acceso a través del gateway ECAIX a un identificador de modelo expuesto en el catálogo de ECAIX. Consulte la documentación oficial de la API DeepSeek para el endpoint nativo de DeepSeek, las reglas de cuenta y las capacidades específicas