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

gpt-6-astra es un modelo de texto con capacidad de razonamiento, ya disponible en hiapi, accesible a través de un endpoint compatible con OpenAI: /v1/responses. Esta guía ofrece un ejemplo de solicitud ejecutable en curl y Python, un requisito no obvio que suele provocar errores (el uso obligatorio de streaming) y los patrones de práctica en producción necesarios antes del lanzamiento.

Qué vas a construir

Un script que envía un prompt a gpt-6-astra y lee la respuesta del modelo mediante streaming. Aquí no hay polling ni ID de tarea: es una llamada síncrona de tipo chat, solo que se entrega como Server-Sent Events en lugar de una respuesta JSON bloqueante.

Requisitos previos: una clave de API de hiapi. Obtén una desde la consola; cada solicitud a continuación debe incluirla en el encabezado Authorization.

Ejemplo mínimo ejecutable

gpt-6-astra solo admite un endpoint —POST /v1/responses— y solo acepta "stream": true. Independientemente de lo que contenga el payload de la solicitud, enviar "stream": false devuelve un error 400 invalid_request; este modelo no tiene modo no streaming en hiapi. Diseña tu cliente en torno a la lectura del flujo de eventos, no en torno a una única respuesta JSON.

curl

curl -N -X POST "https://api.hiapi.ai/v1/responses" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Explain one practical way to check an AI-generated answer against its source." }
        ]
      }
    ],
    "stream": true,
    "store": false,
    "reasoning": { "effort": "medium" }
  }'

-N desactiva el búfer de salida de curl, de modo que puedas ver los eventos en cuanto lleguen en lugar de recibirlos todos de golpe al final. El tipo de respuesta es text/event-stream, cada línea data: es un objeto JSON y una línea event: indica su tipo. Una ejecución abreviada se ve así:

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress", ...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"OK", ...}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed","usage":{"input_tokens":12,"output_tokens":5,"total_tokens":17}, ...}}

El texto que realmente buscas llega por streaming a través de eventos recurrentes response.output_text.delta; concatena el campo delta en orden para obtener la respuesta completa. response.completed incluye el bloque final de usage para el seguimiento de costos.

Python

import json
import requests

payload = {
    "model": "gpt-6-astra",
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain one practical way to check an AI-generated answer against its source.",
                },
            ],
        },
    ],
    "stream": True,
    "store": False,
    "reasoning": {"effort": "medium"},
}

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json=payload,
    stream=True,
    timeout=60,
) as resp:
    resp.raise_for_status()
    answer = []
    for line in resp.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":
            answer.append(event["delta"])
        elif event.get("type") == "response.completed":
            usage = event["response"]["usage"]
            print(f"\n\ntokens: {usage['input_tokens']} in / {usage['output_tokens']} out")

    print("".join(answer))

resp.raise_for_status() captura los fallos a nivel HTTP (autenticación, límite de velocidad) antes de que empieces a analizar las líneas SSE: una secuencia malformada y una solicitud rechazada son dos modos de fallo distintos que debes diferenciar en tu manejo de errores.

Hay dos campos del payload de la solicitud que merecen mención especial:

• input es un arreglo de objetos de mensaje, no una cadena plana; cada entrada requiere type: "message", un role y un arreglo de contenido formado por partes tipadas (usa input_text para texto plano).
• reasoning.effort (low / medium / high) es opcional, pero controla cuánto razonamiento interno realiza el modelo antes de responder. Si no lo estableces, hiapi aplica un valor predeterminado; si estás ponderando latencia frente a calidad de la respuesta, establécela explícitamente.

Consideraciones para producción

• El streaming no es opcional. No construyas una ruta de código que recurra a stream: false al reintentar; con este modelo fallará siempre. Si tu framework o SDK asume una única respuesta JSON, envuelve el bucle SSE anterior y almacena en búfer el texto concatenado antes de entregarlo.
• Los fallos de autenticación son explícitos. Una clave inválida o revocada devuelve HTTP 401 con "code": "permission_denied" en el cuerpo del error; comprueba ese código en lugar de hacer coincidir patrones con la cadena del mensaje, ya que la cadena puede cambiar.
• store: false hace que la solicitud sea sin estado. hiapi no conserva la respuesta en el servidor, por lo que en llamadas posteriores no hay previous_response_id disponible para encadenar. Si necesitas contexto de múltiples turnos, reenvía los turnos anteriores como mensajes input adicionales en lugar de depender del estado de conversación del servidor.
• Establece un tiempo de espera del cliente tanto si usas streaming como si no. Las conexiones SSE pueden quedarse colgadas cuando se interrumpe la conexión y ninguna de las partes envía una señal de cierre limpia; establecer un timeout en el requests.post inicial (como en el ejemplo anterior) evita que se detenga la espera del primer byte, pero también deberías rastrear la duración máxima del flujo en tu propio código como defensa en profundidad.
• Reutiliza prompt_cache_key para contexto de sistema repetido. El payload de la respuesta incluye un prompt_cache_key; si envías las mismas instrucciones en cada llamada, mantener las solicitudes en la misma clave permite que hiapi aplique la caché de prompts en lugar de reprocesarlas cada vez.

Lecturas relacionadas

• Página del modelo gpt-6-astra: referencia completa de parámetros y precios en tiempo real
• Documentación de la API de hiapi: autenticación, otras familias de modelos y la lista completa de endpoints
• Precios de hiapi: tarifas por token de gpt-6-astra y de todos los demás modelos

Preguntas frecuentes

¿gpt-6-astra admite /v1/chat/completions? No. Llamarlo a través de /v1/chat/completions devuelve un error 400 unsupported_endpoint que te indica que uses /v1/responses. En hiapi solo está registrado para la API de Responses.

¿Puedo obtener una única respuesta JSON en lugar de un flujo? Con este modelo, no. "stream": false se rechaza directamente (invalid_request), independientemente de si se establecen otros parámetros. Construye tu integración en torno al consumo del flujo SSE y al ensamblaje del texto final en el cliente, como se muestra arriba.

¿gpt-6-astra admite llamadas a herramientas? El modelo acepta un arreglo tools en la estructura de solicitud de la API de Responses (si no se establece, aparece como un arreglo vacío en el objeto de respuesta). Si vas a integrar llamadas a funciones, define tus herramientas como lo harías con cualquier modelo compatible con la API de Responses de OpenAI, y presta atención a los eventos response.output_item.added con tipo function_call en el flujo.

¿Cómo se ve un error de límite de velocidad o de cuota? Como otros errores de hiapi, se devuelve en formato JSON con type: "hiapi_error" y un campo code sobre el que puedes ramificar, además de un request_id; incluye ese ID al contactar con soporte para que puedan rastrear la solicitud exacta en el servidor.

¿Puedo usar la misma estructura de solicitud con otros modelos de razonamiento de hiapi? La estructura de solicitud de /v1/responses se comparte entre las familias de modelos de hiapi compatibles con OpenAI Responses; basta con sustituir el campo model para cambiar de modelo. La disponibilidad varía según el modelo, así que consulta la página propia de cada modelo antes de asumir que uno está disponible.