Come usare gpt-6-astra tramite l'API hiapi: esempi di richiesta eseguibili in curl e Python

gpt-6-astra è un modello testuale con capacità di ragionamento, ora disponibile su hiapi e accessibile tramite un endpoint compatibile con OpenAI: /v1/responses. Questa guida fornisce un esempio di richiesta eseguibile in curl e Python, un requisito non ovvio che è facile sbagliare (è obbligatorio usare lo streaming) e i pattern di produzione necessari prima del go-live.

Cosa costruirai

Uno script che invia un prompt a gpt-6-astra e legge la risposta del modello tramite uno stream. Qui non c'è polling né ID di task: è una chiamata sincrona in stile chat, solo che viene consegnata come Server-Sent Events invece che come un'unica risposta JSON bloccante.

Prerequisiti: una chiave API hiapi. Ottienila dalla console: ogni richiesta seguente deve includerla nell'header Authorization.

Esempio minimo eseguibile

gpt-6-astra supporta un solo endpoint, POST /v1/responses, e accetta solo "stream": true. Indipendentemente da cos'altro contenga il payload, inviare "stream": false restituisce un errore 400 invalid_request; su hiapi questo modello non ha una modalità non-streaming. Progetta il tuo client per leggere lo stream di eventi, non una singola risposta 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 disabilita il buffering dell'output di curl, così vedi gli eventi non appena arrivano invece di riceverli tutti insieme alla fine. Il tipo di risposta è text/event-stream, ogni riga data: è un oggetto JSON e una riga event: ne indica il tipo. L'output di un'esecuzione ridotta è simile al seguente:

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}, ...}}

Il testo che ti interessa arriva in streaming tramite i ripetuti eventi response.output_text.delta: concatena i campi delta in ordine per ottenere la risposta completa. response.completed contiene il blocco finale usage, utile per il monitoraggio dei costi.

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() intercetta i fallimenti a livello HTTP (autenticazione, rate limit) prima che tu inizi a parsare le righe SSE: uno stream malformato e una richiesta rifiutata sono due modalità di errore diverse, e devi distinguerle nella gestione degli errori.

Due campi del payload meritano una menzione speciale:

• input è un array di oggetti messaggio, non una stringa piatta: ogni voce richiede type: "message", un role e un array di contenuto composto da parti tipizzate (input_text per il testo semplice).
• reasoning.effort (low / medium / high) è opzionale, ma controlla quanto ragionamento interno svolge il modello prima di rispondere. Se non lo imposti, hiapi applica un valore predefinito; se devi bilanciare latenza e qualità della risposta, impostalo esplicitamente.

Considerazioni per la produzione

• Lo streaming non è opzionale. Non costruire un percorso di codice che, in caso di retry, ripieghi su stream: false: con questo modello fallirebbe ogni volta. Se il tuo framework o SDK presuppone una singola risposta JSON, incapsula il ciclo SSE mostrato sopra e bufferizza il testo concatenato prima di passarlo al resto del sistema.
• I fallimenti di autenticazione sono espliciti. Una chiave non valida o revocata restituisce HTTP 401 con "code": "permission_denied" nel corpo dell'errore: controlla quel codice invece di fare pattern matching sulla stringa del messaggio, che potrebbe cambiare.
• store: false rende la richiesta stateless. hiapi non conserva la risposta lato server, quindi nelle chiamate successive non hai un previous_response_id da usare per concatenare. Se ti serve un contesto multi-turno, reinvia i turni precedenti come messaggi input aggiuntivi invece di affidarti allo stato della conversazione lato server.
• Imposta un timeout lato client, con o senza streaming. Le connessioni SSE possono bloccarsi quando la connessione cade senza che nessuna delle due parti invii un segnale di chiusura pulito; impostare un timeout sulla requests.post iniziale (come nell'esempio sopra) previene lo stallo sul primo byte, ma dovresti anche tenere traccia nel tuo codice della durata massima dello stream, come difesa in profondità.
• Riusa prompt_cache_key per contesti di sistema ripetuti. Il payload della risposta include un prompt_cache_key; se invii le stesse istruzioni a ogni chiamata, mantenere le richieste sulla stessa chiave consente a hiapi di applicare la cache dei prompt invece di rielaborarli ogni volta.

Letture correlate

• Pagina del modello gpt-6-astra: riferimento completo dei parametri e prezzi in tempo reale
• Documentazione dell'API hiapi: autenticazione, altre famiglie di modelli e elenco completo degli endpoint
• Prezzi hiapi: tariffe per token di gpt-6-astra e di tutti gli altri modelli

Domande frequenti

gpt-6-astra supporta /v1/chat/completions? No. Chiamarlo tramite /v1/chat/completions restituisce un errore 400 unsupported_endpoint che ti invita a usare /v1/responses. Su hiapi è registrato solo per la Responses API.

Posso ottenere una singola risposta JSON invece di uno stream? Con questo modello no. "stream": false viene rifiutato direttamente (invalid_request), indipendentemente dagli altri parametri impostati. Costruisci la tua integrazione attorno al consumo dello stream SSE e all'assemblaggio del testo finale lato client, come mostrato sopra.

gpt-6-astra supporta le chiamate a strumenti? Il modello accetta l'array tools nella struttura della richiesta Responses API (se non impostato, appare come array vuoto nell'oggetto risposta). Se devi integrare il function calling, definisci i tuoi strumenti come faresti con qualsiasi modello compatibile con la OpenAI Responses API e tieni d'occhio nello stream gli eventi response.output_item.added con tipo function_call.

Come si presentano gli errori di rate limit o di quota? Come gli altri errori di hiapi, vengono restituiti in formato JSON con type: "hiapi_error" e un campo code su cui puoi diramare la logica, più un request_id: includi questo ID quando contatti il supporto, così possono rintracciare la richiesta esatta lato server.

Posso usare la stessa struttura di richiesta con altri modelli di ragionamento su hiapi? La struttura di richiesta di /v1/responses è condivisa tra le famiglie di modelli hiapi compatibili con OpenAI Responses: basta cambiare il campo model per passare a un altro modello. La disponibilità varia da modello a modello, quindi prima di dare per scontato che un modello sia online, consulta la sua pagina dedicata.