Cómo usar deepseek-v4.1-flash a través de la API de hiapi: curl, Python y ejemplos de solicitud funcionales

deepseek-v4.1-flash es un modelo de razonamiento rápido y de bajo costo al que se puede acceder mediante la API unificada de hiapi. Actualmente está marcado como Preview en la página del modelo, lo que significa que la compilación subyacente puede rotar mientras que el ID de modelo público (deepseek-v4.1-flash) permanece estable, por lo que no tendrás que cambiar ningún código cuando ocurra la rotación. Esta guía muestra una solicitud que realmente funciona: el endpoint correcto, los campos correctos y los encabezados de autenticación correctos.

Requisitos previos

• Una clave de API de hiapi (sk-...). Obténla desde tu consola de hiapi y luego expórtala:

export HIAPI_API_KEY="sk-your-key-here"

• Sirve cualquier cliente HTTP. Los siguientes ejemplos usan curl y requests de Python, además de instrucciones para usar el SDK oficial de OpenAI.

Ejemplo mínimo funcional

hiapi ofrece dos endpoints de texto. /v1/responses es el endpoint canónico recomendado (forma de OpenAI Responses API, eventos SSE semánticos). /v1/chat/completions es el endpoint compatible con versiones anteriores (forma de OpenAI Chat Completions); úsalo solo si estás migrando una integración existente de Chat Completions. Esta guía usa /v1/responses.

curl

curl https://api.hiapi.ai/v1/responses \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "input": [
      {"role": "user", "content": "Explain what a hash map is in two sentences."}
    ]
  }'

Una respuesta exitosa devuelve un array output que contiene la respuesta del modelo, junto con un bloque usage:

{
  "id": "resp_...",
  "model": "deepseek-v4.1-flash-expires-on-0910",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "A hash map stores key-value pairs..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 42,
    "total_tokens": 56,
    "output_tokens_details": {"reasoning_tokens": 0}
  }
}

Ten en cuenta que el campo model de la respuesta aparece como deepseek-v4.1-flash-expires-on-0910: esta es la compilación interna fija que actualmente sirve a este modelo en versión preview. Este es el comportamiento esperado de los modelos en versión preview en hiapi, no una señal de que el modelo vaya a retirarse; sigue solicitando el ID simple deepseek-v4.1-flash y hiapi te enrutará automáticamente a la compilación actual.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [
            {"role": "user", "content": "Explain what a hash map is in two sentences."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["output"][0]["content"][0]["text"])
print(data["usage"])

Uso del SDK de OpenAI

Los endpoints /v1/responses y /v1/chat/completions de hiapi son compatibles con el SDK oficial de OpenAI; solo tienes que apuntar la URL base a hiapi y mantener el ID de modelo en su forma simple:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)
resp = client.responses.create(
    model="deepseek-v4.1-flash",
    input=[{"role": "user", "content": "Explain what a hash map is in two sentences."}],
)
print(resp.output[0].content[0].text)

Prácticas para producción

Las solicitudes no tienen estado: es necesario reenviar la conversación completa

hiapi no conserva el estado de la conversación en el servidor para este modelo. Cada solicitud debe incluir el historial completo de mensajes en input. No envíes store, previous_response_id, conversation, background ni context_management: no están soportados y serán ignorados o rechazados. Para conversaciones multiturno, añade tú mismo cada nuevo mensaje de usuario/asistente al array input y envía el array completo en cada solicitud.

history = [{"role": "user", "content": "What's a hash map?"}]
# ... call, get a reply, then append it and the next question ...
history.append({"role": "assistant", "content": "<model's previous reply>"})
history.append({"role": "user", "content": "How is that different from a hash set?"})

Intensidad de razonamiento

deepseek-v4.1-flash acepta un objeto reasoning que controla cuánto razonamiento interno realiza antes de responder. La enumeración de effort para este modelo es none | high | max; ten en cuenta que no son los niveles low/medium/high que usan otros modelos de razonamiento en hiapi, así que no asumas que se puede aplicar directamente.

{
  "model": "deepseek-v4.1-flash",
  "input": [{"role": "user", "content": "Prove that the square root of 2 is irrational."}],
  "reasoning": {"effort": "high"}
}

Los tokens de razonamiento se facturan como tokens de salida y se informan por separado en usage.output_tokens_details.reasoning_tokens, por lo que las solicitudes con intensidad high/max pueden ser considerablemente más caras que con none aunque la longitud de la respuesta visible sea la misma. Antes de configurar una intensidad predeterminada para el tráfico de producción, consulta las tarifas actuales por token en la página de precios.

Transmisión en streaming

Pasa "stream": true para obtener Server-Sent Events en lugar de un único bloque JSON. /v1/responses transmite eventos semánticos, no incrementos de texto sin procesar envueltos en el marcador [DONE] al estilo Chat-Completions. La secuencia de eventos de una finalización normal es:

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta   (repeated, one per chunk of text)
response.output_text.done
response.content_part.done
response.output_item.done
response.completed

Trata response.completed como el evento de terminación exitosa. También debes tratar response.incomplete (por ejemplo, al alcanzar el límite de tokens/longitud) y response.failed (errores del servidor) como estados de terminación; no asumas que todos los flujos terminan con response.completed.

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [{"role": "user", "content": "Count to 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as r:
    for line in r.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        event = json.loads(line[len(b"data: "):])
        if event.get("type") == "response.output_text.delta":
            print(event["delta"], end="", flush=True)
        elif event.get("type") in ("response.completed", "response.incomplete", "response.failed"):
            break

Manejo de errores

Una clave de API no válida o ausente devuelve HTTP 401 con un cuerpo de error estructurado:

{"error": {"code": "permission_denied", "message": "..."}}

Comprueba resp.status_code y ramifica según error.code, en lugar de analizar la cadena del mensaje, ya que el texto del mensaje puede cambiar de redacción sin previo aviso.

Documentación relacionada

• Página del modelo deepseek-v4.1-flash
• Referencia de /v1/responses
• Referencia de /v1/chat/completions
• Autenticación
• Precios

Preguntas frecuentes

¿deepseek-v4.1-flash es para producción o solo para pruebas? Está marcado como preview, lo que en hiapi significa que el modelo está en línea y se puede llamar con normalidad, pero la compilación subyacente puede rotar según lo determine hiapi. Cuando rote, el ID de modelo público no cambiará y tu código seguirá funcionando sin modificaciones. Si necesitas un compromiso formal que no sea preview, consulta las variantes de DeepSeek v4 que no son preview en la lista de modelos.

¿Por qué la respuesta muestra un nombre de modelo diferente al que solicité? Verás un valor como deepseek-v4.1-flash-expires-on-0910 en el campo model de la respuesta. Esa es la compilación fija específica que actualmente sirve tu solicitud bajo el ID deepseek-v4.1-flash; este es el comportamiento esperado de un modelo en versión preview, no un error.

¿Puedo usar /v1/chat/completions en lugar de /v1/responses? Sí, hiapi soporta ambos para este modelo. /v1/chat/completions usa la forma de solicitud/respuesta de OpenAI Chat Completions (array messages, choices[0].message.content), en lugar de la forma input/output de /v1/responses. Elige el que coincida con tu integración existente; las integraciones nuevas deberían usar /v1/responses por defecto.

¿hiapi almacena mi historial de conversación para que solo tenga que enviar el mensaje más reciente? No. Este modelo no tiene previous_response_id ni estado de conversación en el servidor; debes enviar el historial completo de mensajes en input en cada solicitud.

¿Qué omite realmente reasoning.effort: "none"? Omite por completo el proceso de razonamiento interno del modelo y responde directamente. Para tareas que se benefician del razonamiento de varios pasos (matemáticas, lógica con múltiples restricciones), usa "high" o "max"; a mayor intensidad, también aumentan el uso de tokens de salida y la latencia.

¿Se necesitan claves de API distintas para solicitudes en streaming y no streaming? No; la misma clave Authorization: Bearer sk-... sirve para ambas. La transmisión en streaming se controla completamente con el campo "stream": true del cuerpo de la solicitud.