Cómo usar Claude Sonnet 4.6 a través de la API de hiapi

Lo que vas a construir

Un ejemplo de integración funcional: llamar a Claude Sonnet 4.6 a través de la API Chat Completions compatible con OpenAI de hiapi — una sola solicitud devuelve una respuesta de completado real, y además cubre los patrones de nivel de producción que realmente usarás una vez que la demo funcione (salida en streaming, llamada a herramientas, pensamiento adaptativo).

Requisito previo: una clave de API de hiapi. Obténla desde la consola — es simplemente una cadena sk-..., y la misma clave sirve para todos los modelos habilitados en tu cuenta, no solo para este.

Todo lo que aparece a continuación se verificó ejecutándolo realmente contra la API en vivo en el momento de redactar este artículo.

Ejemplo mínimo funcional

Claude Sonnet 4.6 es un modelo de texto en el endpoint estándar de Chat Completions, no el flujo asíncrono /v1/tasks que hiapi usa para modelos de imagen/vídeo/audio. Una solicitud, una respuesta, sin sondeo.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
    ]
  }'

Respuesta (recortada):

{
  "id": "msg_bdrk_011Cf8Bo25qCVFFQF5ETk8Wf",
  "model": "claude-sonnet-4-6",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 13, "completion_tokens": 4, "total_tokens": 17 }
}

La misma llamada con Python usando solo requests:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-sonnet-4-6",
        "messages": [
            {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Dado que la estructura es compatible con OpenAI, este código también funciona sin cambios con los SDK oficiales de Python/JS openai — solo apunta base_url a https://api.hiapi.ai/v1 y pasa tu clave de hiapi.

Patrones de nivel de producción

Salida en streaming

Establece "stream": true y lee Server-Sent Events. Cada bloque de datos lleva un fragmento de delta.content; el flujo termina con un bloque final con finish_reason: "stop", seguido del centinela [DONE]:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"Here"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":" you"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Acumula choices[0].delta.content a través de los bloques de datos para reconstruir el texto completo.

Llamada a herramientas

Declara funciones de la misma manera que con OpenAI, luego, en el siguiente turno, reenvía el mensaje tool_calls del asistente junto con un mensaje de resultado tool:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

La respuesta devuelve finish_reason: "tool_calls", con el nombre de la función y los argumentos codificados en JSON en choices[0].message.tool_calls. Ejecuta tu función localmente y, en la siguiente solicitud, envía el resultado de vuelta como un mensaje con role: "tool" y el tool_call_id correspondiente — el modelo continúa desde ahí.

Pensamiento adaptativo

Claude Sonnet 4.6 admite un paso de razonamiento que se habilita bajo demanda. Añade "thinking": {"type": "adaptive"} y elige el nivel de esfuerzo mediante output_config.effort (low, medium, high o max):

{
  "model": "claude-sonnet-4-6",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

La traza de razonamiento legible se devuelve en choices[0].message.reasoning_content; el array original reasoning_details lleva metadatos de firma, y si vas a continuar la conversación y entrar en llamadas a herramientas, debes conservarlo tal cual — no lo analices, no lo muestres ni lo inventes, simplemente reenvíalo tal cual en la siguiente solicitud.

Manejo de errores

Un fallo de autenticación devuelve HTTP 401 con el sobre de error hiapi_error:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Comprueba response.status_code antes de acceder a response.json()["choices"], y si necesitas escalar el caso, registra error.request_id — el equipo de soporte puede usarlo para rastrear la llamada concreta.

Idempotencia y reintentos

A diferencia de los trabajos de /v1/tasks, las llamadas a Chat Completions no son idempotentes por ID de solicitud — una solicitud reintentada es un nuevo completado. Para tráfico de producción, envuelve la llamada con tus propios reintentos con retroceso para manejar 5xx/timeouts, y establece un límite con max_tokens para evitar que una tormenta de reintentos genere facturación sin límite.

Lecturas relacionadas

• Referencia del modelo Claude Sonnet 4.6 — tabla completa de parámetros, esquema de respuesta y más ejemplos de solicitudes directamente de la documentación de hiapi.
• Autenticación — cómo funcionan las claves de API de hiapi y cómo rotarlas.
• Precios de hiapi — tarifas por token en tiempo real de Claude Sonnet 4.6 y de todos los demás modelos habilitados.

Preguntas frecuentes

¿claude-sonnet-4-6 es el ID de modelo exacto que debo enviar? Sí — envía la cadena sin prefijos claude-sonnet-4-6 en el campo model. hiapi la enruta a Claude Sonnet 4.6 de Anthropic detrás de una interfaz compatible con OpenAI, por lo que no se necesita ningún prefijo específico del proveedor.

¿Esto usa el mismo flujo /v1/tasks que los modelos de imagen y vídeo de hiapi? No. Los modelos de texto como Claude Sonnet 4.6 usan el endpoint síncrono POST /v1/chat/completions — una solicitud, una respuesta (o un flujo SSE). /v1/tasks es solo para modelos de medios (imagen, vídeo, audio), que se ejecutan de forma asíncrona y devuelven una URL sondeable o un callback.

¿Puedo usar el SDK de OpenAI en lugar de curl/requests nativos? Sí. Como el endpoint es compatible con OpenAI, solo apunta base_url del SDK oficial openai a https://api.hiapi.ai/v1 y usa tu clave de hiapi como api_key — no se necesitan otros cambios de código para chat básico, salida en streaming o llamada a herramientas.

¿Claude Sonnet 4.6 admite entrada de imágenes? Sí, mediante bloques de contenido — establece el content del mensaje como un array que contenga un bloque con type: "image_url" y image_url.url apuntando a una URL pública de imagen, junto a tu bloque de texto.

¿Qué pasa si omito thinking? Según la versión actual, el pensamiento adaptativo se habilita bajo demanda — omite el campo thinking (o establece thinking.type en disabled), y el modelo responderá directamente, sin reasoning_content en la respuesta.

¿Dónde puedo consultar los precios actuales antes de ejecutar tareas de gran volumen? La página de precios de hiapi enumera las tarifas por token en tiempo real de Claude Sonnet 4.6 — revísala antes de presupuestar, ya que las tarifas pueden cambiar y este artículo no codifica de forma fija una cifra que podría quedar desactualizada.