Blog

Tutorial

Cómo llamar a kimi-k3.1-pro-highspeed a través de la API de HiAPI: ejemplos en curl y Python

Nov 12, 2026
Imagen de portada del blog de HiAPI: sobre un fondo marrón oscuro, cintas anchas se entrelazan con ritmo de tejido de cestería, con toques beige y color latón, formando una composición plana.
En esta página

Qué es kimi-k3.1-pro-highspeed y cuándo elegirlo

kimi-k3.1-pro-highspeed es uno de los modelos de chat que ofrece HiAPI. Se invoca igual que cualquier otro modelo de chat de la plataforma: envías un conjunto de mensajes y recibes una completación. El "high-speed" del nombre indica el compromiso que se espera de él: elígelo cuando valores más la latencia que la profundidad de razonamiento bruta, cuando quieras tiempos de respuesta predecibles en lugar de la respuesta más lenta y exhaustiva.

Por eso encaja bien en varias cargas de trabajo concretas:

  • Interfaces interactivas: interfaces de chat, autocompletado y asistentes en línea donde el usuario está esperando una respuesta.
  • Pipelines de alto rendimiento: tareas de clasificación, extracción, resumen y reescritura en las que necesitas rendimiento y los resultados de cada solicitud son breves.
  • Bucles de agentes de múltiples saltos: flujos de varios pasos en los que cada llamada es pequeña y la latencia total depende principalmente del número de idas y vueltas, no de ninguna llamada individual.

No es la elección obvia cuando la tarea requiere un razonamiento largo y meditado sobre un contexto extenso, o cuando el contenido que generas se beneficia de "una pasada lenta pero de alta calidad en lugar de muchas pasadas rápidas". En esos casos, primero evalúa la calidad de la salida con pruebas de referencia y luego optimiza la velocidad: una respuesta rápida pero incorrecta cuesta más que una lenta pero correcta.

Como el modelo se ofrece a través de la interfaz unificada de HiAPI, cambiar más adelante a otro modelo o volver a este solo requiere modificar la carga útil de la solicitud, no reescribir el código. Si colocas el nombre del modelo en la configuración en lugar de codificarlo directamente en el punto de llamada, podrás hacer pruebas A/B con otros modelos sin tocar el código que construye la solicitud.

Qué significa "de chat" en la práctica

Cada solicitud tiene esta estructura: un identificador de modelo, una lista ordenada de mensajes (cada mensaje con role y content) y parámetros opcionales como stream, temperature y max_tokens. El prompt del sistema se pasa como un mensaje con role: "system". Ese es todo el modelo mental; el resto de esta guía es solo trabajo de plomería alrededor de esta forma.

Requisitos previos: credenciales, endpoint y nombre del modelo

Antes de escribir cualquier código, confirma que tienes los siguientes cuatro elementos. La mayoría de los fallos en la primera llamada se deben a que falta algo de esta lista, no a un error en el cuerpo de la solicitud.

1. Una clave de API

Genera una clave desde el panel de tu cuenta de HiAPI. Trátala como un secreto: cárgala desde una variable de entorno, nunca la confirmes en un repositorio y rótala en cuanto aparezca en registros o cuadernos compartidos.

export HIAPI_API_KEY="your-key-here"

2. URL base

El endpoint se compone de la URL base de HiAPI más la ruta de completación de chat. Coloca la URL base en la configuración para no tener que cambiar el código cuando cambie:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1"

3. Identificador del modelo

La cadena del modelo que debes enviar es exactamente:

kimi-k3.1-pro-highspeed

Cópiala carácter por carácter. El nombre del modelo coincide literalmente: un espacio adicional, una diferencia de mayúsculas o un error tipográfico devolverán un error de modelo no encontrado en lugar de un error de validación de otro campo, lo que podría llevarte a buscar en el lugar equivocado.

4. Un cliente capaz de enviar HTTPS

Para los ejemplos de curl a continuación, solo necesitas un shell con curl instalado, que viene de serie en macOS y en la mayoría de las imágenes de Linux. Para la parte de Python, necesitas Python 3.8+ y el paquete requests:

pip install requests

Si prefieres un cliente de estilo SDK, el mismo endpoint, la misma clave y el mismo nombre de modelo se aplican igual: lo importante es el formato en el cable, y esta guía se mantiene en HTTP sin procesar para que nada quede oculto tras una abstracción.

Comprobación de sanidad

Antes de construir la solicitud completa, ejecuta una comprobación rápida para confirmar que la clave y la URL base se resuelven: una llamada deliberadamente mínima con un prompt de una sola palabra. Si tiene éxito, cualquier fallo posterior tendrá que ver con la carga útil de tu solicitud, no con las credenciales.

Una solicitud curl funcional

A continuación tienes una solicitud completa que puedes copiar y pegar directamente. Usa un mensaje de sistema para establecer el comportamiento, un mensaje de usuario como solicitud real y fija max_tokens para que las respuestas sean breves durante las pruebas.

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [
      {"role": "system", "content": "Eres un asistente técnico conciso. Responde en dos frases o menos."},
      {"role": "user", "content": "Explica qué es una clave de idempotencia y por qué es importante para los reintentos."}
    ],
    "temperature": 0.3,
    "max_tokens": 200,
    "stream": false
  }'

Explicación campo por campo

  • model: el identificador del modelo de la sección anterior. Obligatorio.
  • messages: un arreglo ordenado. system establece el rol y las restricciones; user lleva la tarea. El orden importa: los mensajes posteriores tienen mayor prioridad para guiar el comportamiento. Para flujos de varios turnos, sigue agregando turnos de user y assistant al mismo arreglo en lugar de concatenar todo en un único mensaje de usuario enorme.
  • temperature: aleatoriedad del muestreo. Los valores bajos producen salidas más reproducibles, que es lo que necesitan la extracción y la clasificación. Auméntalo solo cuando realmente quieras variación.
  • max_tokens: límite superior de la respuesta generada. Establecerlo explícitamente te protege de generaciones descontroladas y hace que la latencia sea predecible.
  • stream: aquí es false, lo que significa que recibirás un objeto JSON cuando termine la generación. Las secciones siguientes tratan sobre true.

Qué devuelve

La respuesta es un objeto JSON que contiene un arreglo choices. El texto que buscas está en choices[0].message.content. También hay un bloque usage que describe el consumo de tokens: regístralo, porque cuando se factura por token, es tu única señal de coste por solicitud.

Si estás depurando, pasa la salida por un formateador para que sea legible:

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | python -m json.tool

Coloca el cuerpo de la solicitud en payload.json y usa -d @payload.json; en cuanto la carga útil supere unos pocos campos, evitarás los problemas de comillas del shell.

Trasladar la solicitud a Python

El objetivo aquí no es un script de demostración, sino una función importable. Mantén la carga útil idéntica a la versión de curl (los mismos campos, los mismos nombres, la misma cadena de modelo) para que el comportamiento no cambie al cambiar de herramienta.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"


def chat(
    user_message: str,
    system_message: str = "Eres un asistente técnico conciso.",
    temperature: float = 0.3,
    max_tokens: int = 400,
    timeout: float = 30.0,
) -> str:
    payload = {
        "model": MODEL,
        "messages": [
            {"role": "system", "content": system_message},
            {"role": "user", "content": user_message},
        ],
        "temperature": temperature,
        "max_tokens": max_tokens,
        "stream": False,
    }
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    data = response.json()
    return data["choices"][0]["message"]["content"]

Luego:

print(chat("Resume en una frase la diferencia entre PUT y PATCH."))

Por qué se escribe así

  • Usar json=payload en lugar de JSON escrito a mano: requests serializa correctamente y establece el tipo de contenido, lo que elimina toda una clase de errores de comillas.
  • timeout explícito: sin él, una conexión estancada puede dejar tu proceso de trabajo colgado indefinidamente. Para completaciones breves, treinta segundos es holgado; para rutas interactivas, redúcelo.
  • raise_for_status() cuanto antes: quieres que el fallo de la capa HTTP se exponga como excepción en el límite de la llamada, no como un KeyError sobre choices tres líneas después.
  • Configuración a nivel de módulo: la clave, la URL base y el modelo están en un solo lugar. Hacer pruebas A/B de otros modelos más adelante solo requiere cambiar una constante.

Conversación de varios turnos

Para conversaciones reales, acepta una lista de mensajes como parámetro en lugar de construir dos mensajes fijos:

def chat_with_history(messages: list, **kwargs) -> dict:
    payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
    r = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=30.0,
    )
    r.raise_for_status()
    body = r.json()
    return {
        "content": body["choices"][0]["message"]["content"],
        "usage": body.get("usage"),
    }

Agrega la respuesta del asistente de vuelta a messages con role: "assistant" para continuar la conversación, y recorta los turnos antiguos cuando el historial se alargue: el contexto se factura, así que un historial de conversación ilimitado eleva silenciosamente el coste de cada solicitud.

Habilitar y consumir respuestas en streaming

Establece "stream": true y el servidor enviará la respuesta de forma incremental como eventos enviados por el servidor en lugar de un solo objeto al final. Para cualquier contenido que un usuario esté viendo, vale la pena el trabajo adicional en el cliente: incluso si el tiempo total de generación no cambia, el tiempo hasta el primer token cae de forma significativa.

Perspectiva desde curl

curl -N -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [{"role": "user", "content": "Escribe un haiku sobre los reintentos."}],
    "stream": true
  }'

-N desactiva el almacenamiento en búfer de salida de curl, para que realmente veas los eventos llegar a medida que se envían. Lo que obtienes es una serie de líneas, cada una comenzando con data: , que transporta un fragmento JSON. El último evento es data: [DONE]. Trata ese centinela como la marca de fin de flujo, no como JSON analizable.

Cliente en Python

import json
import requests


def stream_chat(user_message: str, timeout: float = 60.0) -> str:
    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": user_message}],
        "stream": True,
    }
    pieces = []
    with requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        stream=True,
        timeout=timeout,
    ) as r:
        r.raise_for_status()
        for raw in r.iter_lines(decode_unicode=True):
            if not raw or not raw.startswith("data: "):
                continue
            data = raw[len("data: "):].strip()
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0].get("delta", {})
            text = delta.get("content")
            if text:
                pieces.append(text)
                print(text, end="", flush=True)
    return "".join(pieces)

Reglas para mantener el streaming correcto

  • Concatenar, no reemplazar. Cada bloque solo transporta el fragmento nuevo. Acumula en una lista y haz un join una sola vez al final; agregar a una cadena dentro del bucle es de complejidad cuadrática en salidas largas.
  • Protegerte contra contenido ausente. Algunos bloques solo transportan metadatos, así que delta puede no tener la clave content. Usa .get() y omite los valores vacíos.
  • Manejar líneas incompletas. Los límites de trama pueden dividir líneas. iter_lines se encarga de esto, pero si analizas el flujo de bytes sin procesar tú mismo, almacena en búfer hasta ver un salto de línea.
  • Establecer tiempos de espera adecuados para streaming. Un flujo total puede superar legítimamente el tiempo de espera de una solicitud breve. Usa un tiempo de espera de lectura más largo o un plazo de lectura por bloque en lugar de desactivar el tiempo de espera por completo.
  • Conservar la ruta sin streaming. Cuando solo necesitas el texto final de una tarea en segundo plano, stream: false es más sencillo y tiene un coste de inferencia menor. Deja el streaming para las rutas interactivas.

Interpretar las respuestas de error y diseñar reintentos

Reintentar solo ayuda si el fallo es transitorio. Reintentar ciegamente una solicitud mal formada solo amplifica el error. La distinción útil es: errores que corriges en el código frente a errores que la red o el servidor resolverán por sí solos.

Clasificación por código de estado

No reintentar: corregir la solicitud:

  • 400 Bad Request: JSON mal formado, falta un campo obligatorio o un valor de parámetro no es válido. Lee el mensaje de error, corrige la carga útil y agrega una prueba para evitar que vuelva a ocurrir.
  • 401 Unauthorized: la clave falta, está mal formada o fue revocada. Comprueba el formato del encabezado Authorization y si la variable de entorno está realmente establecida en el proceso en ejecución, no solo en tu shell.
  • 403 Forbidden: la clave es válida, pero no tiene permiso para realizar esta operación o usar este modelo. Un bucle de reintentos aquí es puro ruido.
  • 404 Not Found: normalmente es una ruta incorrecta o un identificador de modelo desconocido. Verifica la URL base y la cadena exacta del modelo.
  • Errores de validación de tipo 422: el tipo de parámetro es correcto pero el valor no es aceptable (por ejemplo, un temperature fuera de rango). Limita ese valor en el código.

Reintentar con retroceso exponencial:

  • 429 Too Many Requests: superaste el límite de tasa. Retrocede y, si la respuesta incluye una indicación de retry-after, síguela en lugar de adivinar.
  • 500 / 502 / 503 / 504: fallo del servidor o de la puerta de enlace. Aquí es exactamente donde entra en juego el retroceso exponencial.
  • Errores de conexión y tiempos de espera: el socket falló antes de completar la respuesta. Reintenta, pero solo si la operación es segura de repetir.

Un bucle de reintentos que se comporta correctamente

import random
import time
import requests

RETRYABLE_STATUS = {429, 500, 502, 503, 504}


def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(url, headers=headers, json=payload, timeout=30.0)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == max_attempts:
                raise
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in RETRYABLE_STATUS:
                raise RuntimeError(f"No reintentable {r.status_code}: {r.text[:200]}")
            if attempt == max_attempts:
                raise RuntimeError(f"Reintentos agotados, último {r.status_code}")
        delay = base_delay * (2 ** (attempt - 1))
        time.sleep(delay + random.uniform(0, 0.5))
    raise RuntimeError("unreachable")

Dos detalles importantes en producción

  • La fluctuación (jitter) no es opcional. Sin ella, un grupo de procesos de trabajo que alcanzan el límite de tasa al mismo tiempo reintentarán al unísono y recrearán el pico. El término aleatorio anterior los dispersa.
  • Limita el tiempo total, no solo el número de intentos. Cuatro intentos con retroceso exponencial pueden superar el plazo de tu solicitud. Limita el número de intentos para que el peor caso siga dentro del presupuesto del llamador y pasa el tiempo restante como tiempo de espera del siguiente intento.

No reintentes solicitudes en streaming ante un fallo parcial, a menos que decidas cómo manejar el texto que ya se envió al usuario. El patrón habitual es reintentar solo si aún no se ha mostrado nada; de lo contrario, exponer el truncamiento.

Lista de verificación antes de salir a producción

Antes de que este código se convierta en una carga crítica, ejecuta una lista breve.

  • Tiempos de espera en todas partes. Cada solicitud tiene tiempos de espera explícitos de conexión/lectura, y el valor proviene de tu presupuesto de latencia, no copiado del ejemplo.
  • Secretos fuera del repositorio. La clave de API proviene del entorno o de un gestor de secretos y nunca se escribe en los registros. Limpia los encabezados de cualquier registrador de solicitudes.
  • Nombre del modelo centralizado en un solo lugar. kimi-k3.1-pro-highspeed aparece como una única constante, para que puedas reemplazarlo o hacer pruebas A/B sin buscar y reemplazar.
  • Errores clasificados, no tragados. Las rutas reintentables y no reintentables están claramente separadas en el código, el retroceso incluye fluctuación y el número de intentos tiene un límite.
  • Registrar el uso. Registra el uso de tokens devuelto en cada respuesta junto con la latencia y el estado. Cuando la facturación se basa en tokens, esta es una alerta temprana de que el prompt se está volviendo demasiado grande sin que te des cuenta.
  • Ruta de streaming probada de verdad. Verifica que la salida concatenada sea igual a la salida sin streaming para el mismo prompt, y que una desconexión a mitad del flujo no deje tu interfaz de usuario en un estado roto.
  • Coste controlado por diseño. Establece siempre max_tokens, recorta el historial de conversación y resume los documentos largos antes de incluirlos en el contexto: estas tres palancas hacen que el gasto sea proporcional al valor.

Una vez hecho esto, pasar de la prueba de concepto con curl a un llamador en producción es principalmente trabajo de configuración. Empieza con la función sin streaming, agrega streaming cuando exista la ruta interactiva y deja que el envoltorio de reintentos absorba los fallos que no puedas prevenir.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API