Cómo usar la API de grok-4.6: cURL, Python y una solicitud funcional

grok-4.6 es un modelo de chat optimizado para razonamiento disponible a través de la API de hiapi. A diferencia de sus modelos de imagen y vídeo, no utiliza el pipeline asíncrono /v1/tasks: es una interfaz de chat completions síncrona y compatible con OpenAI, por lo que obtienes directamente una respuesta HTTP normal (o un flujo SSE) sin necesidad de sondeo. Este artículo comienza con una solicitud mínima funcional y luego cubre lo que realmente necesitas en producción: streaming, llamadas a herramientas, modo JSON y manejo de errores.

Qué necesitas

• Una clave de API de hiapi. Si aún no tienes una, obtén una desde la consola; cada solicitud a continuación requiere incluirla en la cabecera Authorization: Bearer sk-....
• Cualquier cliente HTTP. Los ejemplos usan curl y requests de Python; la estructura JSON es la misma independientemente del lenguaje.
• No se necesita SDK. El formato de solicitud/respuesta de grok-4.6 se ajusta mucho a la convención de chat completions de OpenAI, por lo que las herramientas compatibles con OpenAI suelen funcionar, pero hiapi ofrece su propio endpoint de chat completions, no un endpoint propietario: apunta tu cliente a https://api.hiapi.ai/v1/chat/completions y usa el ID de modelo sin prefijo grok-4.6.

Solicitud mínima funcional

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "Explica en una frase qué hace un filtro de Kalman."}
    ]
  }'

Una respuesta exitosa se ve así:

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Un filtro de Kalman estima el estado real de un sistema a lo largo del tiempo combinando mediciones ruidosas con un modelo de predicción y ponderándolos según su respectiva incertidumbre."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

El texto de la respuesta se encuentra en choices[0].message.content, igual que en cualquier API de chat al estilo OpenAI.

A continuación se muestra la misma llamada en Python usando requests:

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "Explica en una frase qué hace un filtro de Kalman."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Ajustes de razonamiento de grok-4.6

grok-4.6 es un modelo de razonamiento: antes de escribir la respuesta final, consume tokens adicionales "pensando", y esos tokens de razonamiento se facturan como tokens de salida (consulta la página de precios para las tarifas actuales). Puedes controlar la cantidad de razonamiento mediante reasoning_effort, que acepta uno de los valores low, medium, high o xhigh (si se omite, la API usa high por defecto):

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Saluda en cinco palabras."}],
    "reasoning_effort": "low"
  }'

La respuesta no transmitida en streaming expone la traza de razonamiento del modelo en message.reasoning_content, separada del message.content final. Para tareas breves y de baja latencia, baja a low o medium; para problemas de varios pasos, high o xhigh intercambian latencia y tokens por mejores respuestas.

Respuestas en streaming

Establece "stream": true para leer la respuesta como Server-Sent Events en lugar de esperar la finalización completa:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Cuenta del 1 al 5."}],
    "stream": true
  }'

Cada línea es un bloque de datos data: {...}. Los tokens de razonamiento se transmiten mediante choices[0].delta.reasoning_content, luego los tokens de respuesta se transmiten mediante choices[0].delta.content, y el flujo termina con el literal data: [DONE]:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"Enumerar"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

En Python, requests puede iterar el flujo línea por línea:

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "Cuenta del 1 al 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

Llamadas a herramientas

grok-4.6 admite llamadas a funciones al estilo OpenAI: pasa un array tools y usa tool_choice: "auto" para que el modelo decida cuándo llamar a una herramienta.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "¿Qué tiempo hace en Tokio?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Obtiene el tiempo actual de una ciudad",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Cuando el modelo decide llamar a la herramienta, finish_reason devuelve "tool_calls" y los argumentos llegan como una cadena JSON que debes analizar tú mismo:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Ejecuta tu función y luego añade un mensaje con role: "tool" (que contenga el resultado de la ejecución y el tool_call_id correspondiente) a messages, y envía la conversación de vuelta para obtener la respuesta final en lenguaje natural.

Modo JSON

Si quieres analizar la respuesta sin el ida y vuelta de las llamadas a herramientas, establece response_format:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "Responde con un objeto JSON que contenga las claves \"city\" y \"country\"."},
      {"role": "user", "content": "¿Dónde está la Torre Eiffel?"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content se devuelve como una cadena JSON (todavía dentro del sobre normal de chat completions), y lo analizas en tu lado con json.loads(...). Asegúrate de indicar al modelo en el prompt que genere realmente JSON: response_format restringe el formato de salida, pero no construye el esquema por ti.

Prácticas para producción

• Gestiona los códigos de error documentados. Una clave incorrecta o ausente devuelve HTTP 401 con el cuerpo de respuesta {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}. El saldo insuficiente devuelve 402; un ID de modelo no válido o un formato de parámetro incorrecto devuelve 400. Comprueba primero el código de estado y registra el request_id del cuerpo de la respuesta de error: si necesitas informar de un problema, esa es exactamente la información que usarás.
• Usa reintentos con retroceso para 429 y 503. hiapi aplica límites de velocidad por cuenta; 429 indica que has superado el límite y 503 que el modelo no está disponible temporalmente. Ambos son adecuados para reintentos con retroceso exponencial acotado (por ejemplo, 1 s, 2 s, 4 s, y abandonar tras varios intentos) en lugar de un bucle apretado.
• Establece tiempos de espera en las solicitudes. Con una intensidad de razonamiento high o xhigh, el tiempo es significativamente mayor que con low; configura el tiempo de espera del cliente según el nivel de intensidad utilizado en lugar de usar una única constante global.
• Prefiere el streaming en cualquier escenario orientado al usuario. Las llamadas no transmitidas en streaming se bloquean hasta que la respuesta completa (incluidos todos los tokens de razonamiento) está lista; el streaming envía los primeros tokens a tu UI de inmediato y te permite mostrar un estado de "pensando" cuando los incrementos de reasoning_content llegan antes de la respuesta final.
• No codifiques las claves de forma fija. Cárgalas desde variables de entorno o un gestor de secretos, nunca desde el control de código fuente; los ejemplos anteriores leen de $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"] precisamente por esta razón.

Para la referencia completa de parámetros (incluidos todos los campos que acepta grok-4.6), consulta la página del modelo y la documentación de grok-4.6.

Preguntas frecuentes

¿grok-4.6 en hiapi es compatible con el SDK de OpenAI? Las estructuras de solicitud y respuesta siguen la convención de chat completions de OpenAI (messages, choices[0].message.content, incrementos de streaming, llamadas a herramientas), por lo que la mayoría de las herramientas compatibles con OpenAI que permiten sobrescribir la URL base y el ID de modelo deberían funcionar. Apunta la URL base a https://api.hiapi.ai/v1 y usa grok-4.6 como ID de modelo.

¿Por qué mi respuesta es más lenta que con otros modelos? grok-4.6 consume tokens en un razonamiento interno antes de responder, y esos tokens se facturan como tokens de salida. Para llamadas sensibles a la latencia, baja reasoning_effort a low o medium, o cambia al streaming para no tener que esperar la respuesta completa de una vez.

¿Qué significa reasoning_content y puedo ocultarlo a los usuarios? Es la traza de razonamiento intermedia del modelo, devuelta por separado de content (o como delta.reasoning_content cuando se transmite en streaming). Puedes perfectamente no renderizarla en tu UI: solo content es la respuesta final.

Recibí 401 y permission_denied: ¿qué ha fallado? Tu cabecera Authorization falta, tiene un formato incorrecto, o la clave no es válida o ha sido revocada. Vuelve a comprobar que envías Authorization: Bearer sk-... y que usas una clave válida de la consola.

¿Puedo usar a la vez las llamadas a funciones de grok-4.6 y el modo JSON en la misma solicitud? tools/tool_choice y response_format son parámetros independientes y se pueden establecer a la vez, pero si el modelo decide llamar a una herramienta, finish_reason de ese turno será "tool_calls" y message.content puede estar vacío: gestiona primero la llamada a la herramienta y luego solicita la respuesta final en formato JSON en un turno posterior.

¿Cómo controlo el coste? Los tokens de razonamiento cuentan como tokens de salida, por lo que el coste varía con reasoning_effort y la longitud de la respuesta. Antes de ejecutar tareas de alta carga, consulta la tarifa actual por token en la página de precios.