Come chiamare gpt-6.1 Sol tramite HiAPI: curl, Python e test in streaming (tutorial in cinese)

Obiettivi e presupposti di questo articolo

Alla fine di questo articolo avrai eseguito gpt-6.1 Sol con una singola richiesta HTTP e ricevuto il testo in streaming: è il modello testuale della famiglia GPT-6.1 Sol su HiAPI, pensato per programmazione complessa, analisi di documenti e ragionamento multi-step. Troverai esempi curl e Python pronti da copiare, e i tre punti in cui è più facile inciampare: l'endpoint è /v1/responses (non /v1/chat/completions), lo streaming è obbligatorio e input deve essere un array.

Presupposti: una API Key di HiAPI. Creala nella pagina delle chiavi API e conservala con cura; va inviata a ogni richiesta tramite Authorization: Bearer sk-<la tua key>.

gpt-6.1 Sol è un modello puramente testuale (conversazione / ragionamento / programmazione) e non genera immagini. Per le capacità e la prova online vedi la pagina del modello gpt-6.1 Sol.

Esempio minimo funzionante

La famiglia Sol usa la Responses API: POST /v1/responses. Due regole tassative: se ne manca una, ottieni un 400:

1. "stream": true — il modello supporta solo lo streaming; stream:false viene rifiutato.
2. input è un array di oggetti messaggio — con lo streaming attivo, passare una stringa nuda restituisce input: has incorrect type.

curl

curl -N https://api.hiapi.ai/v1/responses \
  -H "Authorization: Bearer sk-<la tua key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Spiega in una frase cos'è il rate limiting di un'API." }
        ]
      }
    ],
    "stream": true
  }'

-N disattiva il buffering dell'output di curl, così vedi arrivare in tempo reale i Server-Sent Events (SSE) uno per uno. Il flusso è una serie di righe event: / data:; il testo che ti interessa compare nei frammenti response.output_text.delta e viene ripetuto per intero nell'evento finale response.completed.

Anche la forma abbreviata "input": [{"role":"user","content":"……"}] funziona; la forma canonica con type/input_text qui sopra è più affidabile quando combini input multimodali o più turni, quindi è consigliata come default.

Python

Non serve un SDK: HiAPI è semplice HTTP, basta usare requests con stream=True:

import json
import requests

API_KEY = "sk-<la tua key>"

payload = {
    "model": "gpt-6.1-sol",
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Spiega in una frase cos'è il rate limiting di un'API."}
            ],
        }
    ],
    "stream": True,
}

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    stream=True,
    timeout=120,
) as resp:
    resp.raise_for_status()

    text = ""
    for line in resp.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        event = json.loads(line[len("data:"):].strip())
        etype = event.get("type")
        if etype == "response.output_text.delta":
            text += event["delta"]
        elif etype == "response.completed":
            usage = event["response"]["usage"]
            print(f"\n[tokens: in={usage['input_tokens']} "
                  f"out={usage['output_tokens']} total={usage['total_tokens']}]")

print(text)

È più robusto distribuire in base al campo type incluso nel JSON (invece di analizzare la riga event:): ogni frame SSE è composto da due righe — event: <type> e data: <json> — quindi basta filtrare le righe data: e leggere event["type"].

Punti essenziali per la produzione

• Esiste solo la modalità streaming. Non c'è una variante non-streaming: stream:false restituisce direttamente 400. Il client va progettato fin dall'inizio intorno agli SSE: timeout di lettura, riconnessione / retry dopo l'interruzione del flusso.
• Non passare max_output_tokens. Questo profilo di esecuzione non accetta il parametro (restituisce not supported by this execution profile). Per controllare la lunghezza, vincolala nel prompt o nelle istruzioni di sistema. Il modello può emettere al massimo circa 128.000 token per risposta, ma questo limite non è configurabile tramite parametro.
• Metti il prompt di sistema nel campo top-level instructions (stringa), non dentro un messaggio:

{
  "model": "gpt-6.1-sol",
  "instructions": "Sei un assistente conciso: rispondi con una sola frase.",
  "input": [
    { "type": "message", "role": "user",
      "content": [{ "type": "input_text", "text": "Cos'è un webhook?" }] }
  ],
  "reasoning": { "effort": "low" },
  "stream": true
}

• Usa reasoning.effort per bilanciare profondità di ragionamento e costo. gpt-6.1 Sol è un modello di ragionamento; reasoning.effort supporta cinque livelli low / medium / high / xhigh / max, con default medium. Più basso è il livello, meno token di ragionamento consumi — e i token di ragionamento vengono fatturati come output, compaiono in usage.output_tokens_details.reasoning_tokens nell'evento finale. Per i task che si risolvono con un livello basso, non attivare livelli alti.
• Per output strutturati usa text.format. Il modello supporta la modalità strict di JSON Schema: utile per fargli produrre in modo affidabile JSON analizzabile, invece di sperare nel formato tramite il prompt.
• Supporta le chiamate a tool (function calling). tools + tool_choice a livello top-level sono disponibili, e puoi reintegrare i risultati dei tool nella conversazione per continuare il ragionamento: adatto a scenari agent.
• Conversazioni multi-turno: basta aggiungere in ordine i messaggi user e assistant precedenti all'array input e inviare la richiesta successiva.
• Un errore di autenticazione è 401. Se la key è errata o revocata restituisce 401, code permission_denied ("This API key is invalid."). In questo caso lancia subito l'errore e non fare retry — un retry non sistema una key sbagliata; il request_id nel corpo della risposta serve al supporto tecnico per la diagnosi.
• La fatturazione è a token. Input e output sono tariffati separatamente, e il prezzo unitario dell'output è nettamente più alto di quello dell'input; i token di input con cache hit costano meno; i token di ragionamento sono conteggiati nell'output e quindi fatturati insieme (quindi abbassare reasoning.effort fa risparmiare direttamente); quando un singolo input supera circa 272.000 token si entra nella fascia di prezzo superiore per contesti lunghi. I valori esatti fanno fede sulla pagina dei prezzi in tempo reale: non scrivere i prezzi hardcoded nel codice.

Registro di test: una richiesta eseguita davvero

Gli esempi di questo articolo non sono copiati dalla documentazione — ho chiamato realmente /v1/responses con il curl qui sopra (reasoning.effort: low, prompt "spiega in una frase cos'è il rate limiting di un'API") e ho osservato:

• L'evento finale response.completed con usage: input_tokens=31, output_tokens=28, total_tokens=59, di cui output_tokens_details.reasoning_tokens=0 — con livello basso e una domanda semplice i token di ragionamento possono essere 0, e il costo è quasi solo la parte di output visibile.
• Il testo arriva nel flusso come incrementi response.output_text.delta, e nell'evento finale puoi ottenere il risultato completo in un colpo da response.output[0].content[0].text; entrambi i modi funzionano.
• Il corpo della risposta include l'eco di reasoning.effort, service_tier, prompt_cache_retention e altri campi, confermando che effort e cache sono effettivamente attivi.

Ho anche provocato davvero alcuni errori comuni, così puoi confrontarli per la diagnosi (tutte risposte reali):

Cosa hai sbagliato	HTTP	code	message
Inviato a /v1/chat/completions	400	unsupported_protocol	Model does not support this protocol
Passato stream:false	400	invalid_parameter	stream: must be true
Passato max_output_tokens	400	invalid_parameter	max_output_tokens: is not supported by this execution profile
input passato come stringa	400	invalid_parameter	input: has incorrect type
key non valida	401	permission_denied	This API key is invalid.（con request_id）

Regola mnemonica per il debug: se ricevi 400 controlla prima queste tre cose — l'endpoint è /v1/responses, stream è true, input è un array. La stragrande maggioranza delle "chiamate che non funzionano" ricade in uno di questi tre casi.

Link correlati

• Pagina del modello gpt-6.1 Sol — capacità, parametri e prova online
• Documentazione HiAPI — panoramica delle interfacce e altri modelli
• Pagina dei prezzi — prezzi unitari in tempo reale a consumo
• Stai ancora scegliendo il modello? Vedi GPT-6 Astra vs GPT-5.6 Sol: come scegliere, e la pagina del modello GPT-6 Astra, anch'esso basato sulla Responses API

Domande frequenti

Posso collegarmi direttamente con l'SDK ufficiale di OpenAI? gpt-6.1 Sol usa il protocollo Responses API e la forma dell'interfaccia è compatibile, ma gli esempi di questo articolo usano l'HTTP puro più leggero (requests + stream=True), senza dipendere da alcun SDK: copiali e funzionano. La chiave è puntare il base URL a https://api.hiapi.ai e usare la key di HiAPI.

Perché passando stream:false ricevo sempre 400? È per design, non un bug. La famiglia Sol supporta solo lo streaming: stream deve essere true, altrimenti restituisce invalid_parameter (stream: must be true). Basta modificare il client per leggere gli SSE.

Come controllo la lunghezza dell'output? Non posso usare max_output_tokens? No, se lo passi ottieni 400. Specifica il requisito di lunghezza in instructions (ad es. "rispondi con una sola frase") o vincolalo nel prompt.

Come ridurre i costi? Abbassa prima reasoning.effort (i token di ragionamento sono fatturati come output: un livello basso fa risparmiare subito); riusa il prompt di sistema per ottenere cache hit sull'input a costo inferiore; evita di inserire in un colpo contesti enormi che attivano la fascia di prezzo alta. I prezzi unitari in tempo reale sono sulla pagina dei prezzi.