Cómo usar kimi-k3 a través de la API de hiapi: curl, Python y ejemplos de solicitud ejecutables

Qué vas a construir

kimi-k3 es un modelo de conversación con capacidad de razonamiento, disponible en hiapi a través del endpoint estándar compatible con OpenAI /v1/chat/completions: no necesitas sondear tareas asíncronas ni subir imágenes. Esta guía te lleva desde cero hasta una llamada ejecutable con curl y Python, y luego explica dos cosas que suelen dar problemas en producción: los tokens de razonamiento que consumen tu presupuesto de max_tokens y la salida en streaming.

Requisitos previos: una clave de API de hiapi. Si aún no tienes una, obténla desde la consola: cada solicitud a continuación se autentica mediante Authorization: Bearer sk-<your-key>.

Ejemplo mínimo ejecutable

kimi-k3 es un modelo de texto, por lo que no pasa por la cola de tareas /v1/tasks que hiapi usa para los modelos de imagen/vídeo: es una llamada directa y síncrona a una finalización de chat.

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
    ],
    "max_tokens": 300
  }'

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [
            {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
        ],
        "max_tokens": 300,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Una respuesta exitosa tiene este aspecto:

{
  "id": "chatcmpl-fb762e7481bd4442abb1d8ed3892b4f5",
  "model": "FW-Kimi-K3",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need answer user: \"Reply with exactly the word OK.\" ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 95,
    "completion_tokens": 52,
    "total_tokens": 147,
    "completion_tokens_details": {"reasoning_tokens": 38}
  }
}

La respuesta final está en choices[0].message.content. El ID de modelo en la solicitud es el ID simple kimi-k3: hiapi lo mapea internamente (el campo model del cuerpo de la respuesta devuelve la etiqueta subyacente, por ejemplo FW-Kimi-K3, lo cual es el comportamiento esperado).

El único escollo: los tokens de razonamiento y max_tokens

kimi-k3 es un modelo de razonamiento: escribe su cadena de pensamiento en message.reasoning_content antes de generar el content final, y ambos comparten el mismo presupuesto de max_tokens. Si max_tokens se configura demasiado bajo, el modelo puede consumir todo el presupuesto en el razonamiento y devolver finish_reason: "length" con el campo content vacío:

{
  "choices": [{
    "message": {"content": "", "reasoning_content": "The user is asking me to say \"OK\""},
    "finish_reason": "length"
  }]
}

Esto no es un bug: simplemente el razonamiento agotó el espacio antes de llegar a la respuesta final. Hay dos formas de manejarlo:

• Dale margen suficiente. Para respuestas breves y fácticas, un max_tokens de 200–300 suele bastar para cubrir el razonamiento y la respuesta. Para generaciones más largas, aumenta el presupuesto en consecuencia.
• Revisa finish_reason. Si devuelve "length" y content está vacío, aumenta max_tokens y vuelve a intentarlo; no tomes la cadena vacía como respuesta final.

Salida en streaming

Configura "stream": true para obtener Server-Sent Events (SSE) en lugar de esperar la respuesta completa. Los fragmentos llevan primero los incrementos de delta.reasoning_content y, una vez que el modelo empieza a escribir la respuesta final, llevan delta.content:

import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Count to 3."}],
        "max_tokens": 200,
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data: ") and line != b"data: [DONE]":
            print(line.decode("utf-8"))

Si estás construyendo una interfaz de chat, renderiza en streaming solo delta.content: la mayoría de las aplicaciones ocultan delta.reasoning_content detrás de un interruptor de «pensando» o lo muestran plegado, en lugar de mostrarlo en línea.

Consideraciones para producción

• Manejo de errores. Una clave inválida o ausente devuelve HTTP 401 con un cuerpo de respuesta estructurado:

  {"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}
  

  Anota el request_id: si abres un ticket, el equipo de soporte lo necesitará.
• Reintentos. Las finalizaciones de chat son síncronas, así que no hay un ID de tarea que sondear ni un callback que registrar (ese patrón se aplica a los modelos asíncronos de imagen/vídeo de hiapi, no al texto). Ante un timeout o un 5xx, simplemente vuelve a enviar la solicitud; como el servidor no tiene ninguna tarea en cola, puedes tratarlo como un reintento idempotente normal, similar a un GET.
• Facturación. kimi-k3 se factura por token igual que el resto de modelos de texto de la plataforma: antes de estimar costes a escala, consulta las tarifas actuales en la página de precios, ya que los tokens de razonamiento cuentan como tokens de finalización.

Preguntas frecuentes

¿kimi-k3 admite salida en streaming? Sí: pasa "stream": true y lee la respuesta text/event-stream como se muestra arriba.

¿Por qué mi respuesta tiene content vacío? finish_reason casi con seguridad es "length": el modelo gastó todo el presupuesto de max_tokens en reasoning_content antes de llegar a la respuesta final. Aumenta max_tokens y vuelve a intentarlo.

¿kimi-k3 necesita el endpoint /v1/tasks de hiapi? No. /v1/tasks se usa para modelos asíncronos de generación de imagen, vídeo y música. kimi-k3 es un modelo de texto síncrono que se sirve a través del endpoint estándar /v1/chat/completions.

¿Puedo usar el SDK de Python de OpenAI en lugar de requests nativo? Sí: apunta el base_url del SDK a https://api.hiapi.ai/v1 y pasa tu clave de hiapi como clave de API; la estructura de solicitud/respuesta es compatible con OpenAI.

¿Qué ID de modelo debo pasar en la solicitud? El ID simple kimi-k3. En el campo model del cuerpo de la respuesta verás la etiqueta interna devuelta, por ejemplo FW-Kimi-K3: es el comportamiento esperado y no afecta a la facturación ni al comportamiento.