Cómo usar DeepSeek V4 Flash a través de la API de hiapi: curl, Python y ejemplos de solicitud ejecutables

DeepSeek V4 Flash es un modelo de chat de razonamiento y en hiapi su integración es distinta a la de la mayoría de los modelos de la plataforma: no utiliza la cola asíncrona POST /v1/tasks empleada para la generación de imágenes y vídeos, sino que expone un endpoint de finalización de chat compatible con OpenAI: POST /v1/chat/completions, con soporte síncrono o en streaming y sin necesidad de sondeo. Este tutorial te guía para lanzar una solicitud ejecutable con curl y Python, y luego presenta dos problemas que realmente dan dolores de cabeza en producción.

Qué vas a construir

Un script mínimo que envía un prompt a deepseek-v4-flash a través de hiapi y muestra la respuesta del modelo, además de los patrones que necesitarás cuando ese script se convierta en una integración real: gestionar el presupuesto de tokens de razonamiento, el streaming, los reintentos y la estructura de errores que documenta la documentación.

Requisitos previos: una clave de API de hiapi. Consíguela en el panel de hiapi: cada solicitud de esta guía se autentica mediante Authorization: Bearer sk-<your-key>.

Ejemplo mínimo ejecutable

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Explain what a hash table is in two sentences."}],
    "max_tokens": 500
  }'

Una llamada correcta devuelve el objeto estándar de finalización de chat:

{
  "id": "gen-...",
  "object": "chat.completion",
  "model": "deepseek/deepseek-v4-flash",
  "provider": "DeepInfra",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {"role": "assistant", "content": "A hash table is ...", "reasoning": "..."}
  }],
  "usage": {
    "prompt_tokens": 14, "completion_tokens": 187, "total_tokens": 201,
    "completion_tokens_details": {"reasoning_tokens": 96}
  }
}

Hay dos cosas que conviene tener en cuenta: en la solicitud se usa el ID de modelo sin prefijo deepseek-v4-flash; hiapi lo resuelve internamente hacia el proveedor upstream, mientras que el campo model de la respuesta devuelve un ID calificado con el proveedor (deepseek/deepseek-v4-flash), que debes tratar como información de referencia y no reenviar como parámetro de la solicitud. Además, además de content, el mensaje incluye un campo reasoning: se trata de un modelo de razonamiento, y usage.completion_tokens_details.reasoning_tokens te indica qué parte del gasto de completion_tokens se dedicó a esa cadena de pensamiento y qué parte a la respuesta visible.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"},
    json={
        "model": "deepseek-v4-flash",
        "messages": [{"role": "user", "content": "Explain what a hash table is in two sentences."}],
        "max_tokens": 500,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Como el endpoint es compatible con OpenAI, este código también funciona sin cambios con el SDK oficial de Python openai: solo hay que apuntar base_url a https://api.hiapi.ai/v1 y pasar la clave de hiapi como api_key.

Patrones de uso en producción

La trampa del presupuesto de razonamiento: no pongas max_tokens demasiado bajo

max_tokens limita el coste combinado de razonamiento más respuesta, no solo la respuesta visible. Si el modelo sigue razonando cuando alcanza el límite, obtendrás una respuesta con finish_reason: "length" y content: null: tokens consumidos y facturados sin nada que mostrar. Para cualquier prompt que no sea trivial, deja un margen real en la solicitud (al menos unos cientos de tokens), en lugar de recortar max_tokens a lo que crees que necesitará la respuesta.

Desactivar el razonamiento para tareas simples y deterministas

Si la tarea no necesita cadena de pensamiento —clasificación, consultas breves, conversión de formato— puedes suprimir el razonamiento por completo:

{
  "model": "deepseek-v4-flash",
  "messages": [{"role": "user", "content": "Say OK and nothing else."}],
  "max_tokens": 50,
  "reasoning": {"enabled": false}
}

Con reasoning.enabled: false, el campo message.reasoning de la respuesta devuelve null y completion_tokens_details.reasoning_tokens es 0: solo pagas por la salida visible y la latencia se reduce en consecuencia. Mantén el comportamiento predeterminado (razonamiento activado) solo para las tareas en las que el pensamiento adicional realmente mejora la respuesta.

Streaming

Establece "stream": true para recibir eventos enviados por el servidor al estilo estándar de OpenAI sin esperar la respuesta completa:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Count to 5."}],"stream":true}'

Cada fragmento es una línea data: {...} que transporta el incremento de choices[0].delta.content; el último fragmento contiene usage y el flujo termina con la línea literal data: [DONE]. Analiza cada fragmento en cuanto llegue, en lugar de acumular la respuesta completa en el cliente: de eso se trata precisamente cuando una interfaz de chat usa streaming.

Idempotencia y reintentos

La finalización de chat aquí es una llamada HTTP sin estado, no una tarea en cola: no hay ID de tarea que sondear ni riesgo de enviar contenido duplicado a una cola por accidente. Los reintentos se centran en problemas HTTP normales: ante errores de transporte o 5xx, reintenta con retroceso exponencial; ante 429, respeta la cabecera Retry-After antes de reintentar (consulta la documentación de límites de velocidad). No reintentes los errores 4xx que indican una solicitud incorrecta (por ejemplo, un messages mal formado): corrige el cuerpo de la solicitud.

Gestión de errores

Una clave no válida o ausente devuelve HTTP 401:

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

En el manejador de errores, comprueba error.code en lugar de hacer coincidir patrones con la cadena del mensaje: permission_denied es el identificador estable. Si recibes este error con una clave que crees válida, consulta la documentación de autenticación.

Lecturas relacionadas

• Documentación de autenticación de hiapi: cómo funcionan la cabecera Authorization y los ámbitos de las claves en toda la plataforma.
• Documentación de límites de velocidad de hiapi: comportamiento de 429 y Retry-After.
• Página del modelo deepseek-v4-flash: precios y capacidades actuales.

Preguntas frecuentes

¿Tengo que sondear el resultado como con los modelos de imagen y vídeo de hiapi? No. La generación de imágenes y vídeos en hiapi usa la cola asíncrona /v1/tasks (crear → sondear o callback → descargar output[0].url). Los modelos de chat como deepseek-v4-flash son solo llamadas HTTP síncronas (o en streaming) a /v1/chat/completions: obtienes la respuesta directamente en la respuesta.

¿Por qué usage.completion_tokens es más alto de lo que debería costar la respuesta visible? Porque incluye los tokens de razonamiento. Revisa usage.completion_tokens_details.reasoning_tokens para ver el desglose y usa "reasoning": {"enabled": false} cuando no necesites que el modelo muestre su proceso de pensamiento.

Mi respuesta trae "finish_reason": "length" y content vacío: ¿qué ha pasado? El modelo agotó max_tokens mientras seguía razonando y nunca llegó a escribir la respuesta visible. Aumenta max_tokens o desactiva el razonamiento para prompts más simples.

¿Puedo usar el SDK oficial de OpenAI en lugar de llamadas HTTP directas? Sí: configura base_url del SDK en https://api.hiapi.ai/v1 y api_key con tu clave de hiapi; la estructura de solicitud y respuesta es la misma.

¿Dónde puedo encontrar los precios actuales de este modelo? En la página del modelo o en la página de precios en tiempo real: el coste por token puede variar ligeramente según el enrutamiento al proveedor upstream, así que consúltalo allí en lugar de fiarte de las cifras de este artículo.