Blog

Tutoriale

Come usare gpt-6-sol tramite l'API HiAPI: curl, Python e una richiesta funzionante

Nov 12, 2026
Copertina architettonica con piani in cemento grigio caldo intersecati da un'ombra inclinata blu ardesia e una sottile giuntura verde salvia.
In questa pagina

Cosa serve prima della prima chiamata

Prima di scrivere qualsiasi codice, prepara tre cose. Il resto di questo tutorial si basa su di esse.

Una chiave API HiAPI

Ogni richiesta inviata all'API HiAPI deve essere autenticata con una chiave API. Crea una chiave nella dashboard del tuo account HiAPI e conservala in un luogo sicuro, preferibilmente in una variabile d'ambiente anziché in un file di codice sorgente. Trattala come una password: se viene compromessa, ruotala immediatamente.

export HIAPI_API_KEY="your-api-key-here"

L'endpoint di base

Tutte le chiamate in questa guida sono dirette all'endpoint di base dell'API HiAPI; ogni modello è accessibile tramite lo stesso formato di percorso della richiesta. Non serve un host o un SDK separato per ogni modello: gpt-6-sol si seleziona nel corpo della richiesta, non modificando le impostazioni del client.

Un client HTTP

Ti serve uno dei seguenti:

  • curl, disponibile per impostazione predefinita sulla maggior parte dei sistemi Linux e macOS e nel terminale Windows.
  • Python con la libreria requests installata (pip install requests), oppure la libreria standard urllib se preferisci non introdurre dipendenze.

Non servono altri strumenti. Non ti serve un SDK specifico di un fornitore né installare nulla relativo al modello. Se riesci a inviare una richiesta HTTPS POST con un corpo JSON e delle intestazioni, puoi chiamare gpt-6-sol.

Un'abitudine utile da adottare subito: tieni un file di bozza con la richiesta funzionante che stai usando, così quando qualcosa fallisce puoi confrontare la chiamata fallita con l'ultima chiamata funzionante nota.

Autenticarsi con una chiave bearer

L'autenticazione è il punto in cui si verificano più errori nella prima chiamata, quindi vale la pena affrontarla con attenzione.

L'intestazione Authorization

L'API HiAPI si aspetta la tua chiave nell'intestazione bearer standard:

Authorization: Bearer $HIAPI_API_KEY

Ovvero la parola letterale Bearer, uno spazio e poi la chiave. Gli errori comuni includono: omettere la parola Bearer, includere un carattere di nuova riga superfluo durante la copia del valore, oppure aggiungere virgolette alla chiave quando il client le aggiunge già.

Il content type deve essere JSON

La richiesta trasporta un corpo JSON, quindi l'intestazione del content type deve corrispondere:

Content-Type: application/json

Se questa intestazione manca, alcuni server riescono comunque a interpretare il corpo, ma non dovresti farci affidamento: impostala esplicitamente. Un content type non corrispondente è una causa comune di errori di validazione della richiesta che sembrano errori del corpo.

L'insieme minimo di intestazioni

Ti servono solo le due intestazioni sopra:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Mantieni l'insieme di intestazioni il più ridotto possibile. Intestazioni speculative prese in prestito da esempi di altre API hanno più probabilità di creare confusione che di aiutare. Una volta che la chiamata con queste due intestazioni riesce, hai una base pulita per confronti futuri.

Evita di incollare la chiave direttamente nella cronologia della shell o in file sottoposti a commit. Fare riferimento alla variabile d'ambiente come sopra tiene la chiave lontana dal codice sorgente e dalla cronologia del terminale.

Costruire il corpo della richiesta per gpt-6-sol

Il corpo della richiesta è JSON e il suo nucleo è una lista di messaggi. Inizia dalla configurazione minima; aggiungi campi solo dopo che la chiamata ha successo.

Payload minimo della richiesta

Il corpo utile minimo deve specificare il modello e fornire un messaggio:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Spiega in una frase cos'è un bearer token API." }
  ]
}

Qui entrano in gioco due campi:

  • model seleziona gpt-6-sol, così lo stesso endpoint potrà in futuro servire altri modelli.
  • messages è la lista ordinata dei turni di conversazione. Ogni voce ha un role (system, user o assistant) e una stringa content.

Valori predefiniti sicuri e aggiunte opzionali

Considera model e messages come obbligatori. Tutto il resto è opzionale e va aggiunto con criterio:

  • Un messaggio system all'inizio di messages definisce il comportamento o il tono della conversazione. È un normale messaggio, non un campo separato di primo livello.
  • Se necessario, il controllo della lunghezza dell'output si imposta come parametro nel corpo della richiesta. Aggiungili solo quando l'output predefinito è troppo corto o troppo lungo per il tuo caso d'uso.
  • I parametri di campionamento cambiano la forma dell'output, non la sua validità. Evita di modificarli durante il debug di una chiamata fallita, perché non possono correggere errori di autenticazione o di struttura del corpo.

Una regola pratica

Quando si verifica un errore, il payload dovrebbe essere il più possibile vicino all'esempio minimo. Rimuovi i campi opzionali uno alla volta finché la chiamata non riesce, poi riaggiungili. Questo isola rapidamente il problema: un parametro difettoso è più facile da trovare di uno nascosto tra cinque parametri corretti.

Inviare una richiesta funzionante con curl

Ecco un comando completo che puoi eseguire direttamente, a condizione che la tua chiave sia esportata. Usa un percorso endpoint segnaposto conforme alle convenzioni dell'API HiAPI descritte sopra.

curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Spiega in una frase cos'è un bearer token API." }
    ]
  }'

Imposta HIAPI_BASE_URL sull'endpoint di base presente nella tua dashboard HiAPI. I flag sono importanti:

  • -X POST imposta il metodo; queste chiamate sono tutte POST.
  • -H aggiunge ciascuna intestazione, una per riga.
  • -d fornisce il corpo JSON. Gli apici singoli impediscono l'interpolazione da parte della shell.
  • -sS mantiene l'output silenzioso ma mostra comunque gli errori, cosa necessaria quando si esegue uno script.

Leggere la risposta

Una risposta riuscita è JSON. Di solito vedrai un oggetto di primo livello che contiene il nome del modello e una lista di choices, ciascuna con un messaggio il cui content contiene il testo generato. Leggi prima la struttura, poi il contenuto: verifica che l'oggetto sia analizzabile, poi individua il campo content.

Per migliorare la leggibilità, puoi passarlo a uno strumento di formattazione JSON:

... | python -m json.tool

Se invece il tuo terminale stampa un oggetto di errore, la chiamata non è riuscita: passa alla sezione sugli errori anziché modificare il prompt. Quando la richiesta non raggiunge nemmeno il modello, il problema non è nel prompt.

Inviare la stessa richiesta con Python

Il payload che hai appena verificato con curl può essere trasferito direttamente. Mantieni il corpo identico, così le correzioni verificate nel terminale si applicano anche al codice.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-6-sol",
    "messages": [
        {"role": "user", "content": "Spiega in una frase cos'è un bearer token API."}
    ],
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    timeout=60,
)

response.raise_for_status()
data = response.json()

for choice in data.get("choices", []):
    message = choice.get("message", {})
    print(message.get("content", ""))

Perché questa versione è più sicura nel codice applicativo

  • Il corpo è un dizionario. Quando passi json=payload, requests lo serializza e imposta il content type per te, ma mantenere le intestazioni esplicite evita sorprese quando cambi client.
  • La chiave proviene da una variabile d'ambiente. Nessun segreto è codificato nel file, quindi il file può essere sottoposto a commit.
  • raise_for_status() viene eseguito per primo. Le risposte non 2xx generano immediatamente un'eccezione, prima che tu tenti di leggere campi inesistenti nel corpo della risposta di errore.
  • È impostato un timeout. Senza timeout, una connessione bloccata potrebbe sospendere indefinitamente un processo worker.

Il ciclo su choices previene anche le chiavi mancanti, il che rende l'esempio tollerante alle risposte con output scarso o assente. Costruisci il tuo wrapper di produzione attorno a questo scheletro: valida, invia, controlla lo stato, poi analizza.

Ricevere risposte in streaming anziché attendere

Per impostazione predefinita, l'API restituisce la risposta completa in un singolo JSON. Per output lunghi o interfacce interattive, puoi invece richiedere che la risposta venga consegnata progressivamente durante la generazione.

L'interruttore dello streaming

Lo streaming si abilita tramite un flag nel corpo della richiesta, non usando un endpoint diverso:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Scrivi un breve testo sui codici di stato HTTP." }
  ],
  "stream": true
}

Aggiungi questo flag per ultimo, dopo che la chiamata non in streaming funziona già. Cambia il modo in cui viene organizzata la risposta, non se la richiesta è valida.

Consumare l'output incrementale

Con lo streaming attivo, la risposta non è più un singolo documento JSON. Arriva come una serie di eventi, di solito separati per riga, ciascuno contenente una piccola porzione di output. Il tuo client deve leggerli man mano che arrivano, anziché chiamare .json() sull'intero corpo della risposta.

with requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    stream=True,
    timeout=60,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

Nel terminale, lo stesso flag si comporta diversamente da una chiamata non in streaming: l'output appare progressivamente, quindi una pipe troncata può sembrare una richiesta fallita quando in realtà è stato interrotto solo lo stream.

Quale usare

Usa la modalità non in streaming per attività batch, test e ogni situazione in cui ti serve l'oggetto completo in una volta. Usa lo streaming quando qualcuno sta aspettando il testo o quando l'output è così lungo che la latenza diventa evidente. Mantieni entrambi i percorsi nel codebase, perché il percorso non in streaming è più facile da sottoporre a debug.

Leggere e correggere i codici di errore comuni

Diagnostica prima in base al codice di stato, poi in base al corpo della risposta. Non cambiare modello né riscrivere il prompt prima di aver stabilito quale livello sta fallendo.

401 Unauthorized

Causa: chiave mancante, malformata o revocata. Correzione: verifica che l'intestazione sia esattamente Authorization: Bearer <key>, controlla la presenza di spazi nascosti o variabili d'ambiente scadute e verifica che la chiave sia ancora valida nella tua dashboard. Stampa la lunghezza della variabile anziché il valore per intercettare errori di variabile vuota.

400 Bad Request

Causa: il corpo della richiesta non è analizzabile o mancano campi obbligatori. Correzione: invia di nuovo il payload minimo, contenente solo model e messages. Valida il JSON con python -m json.tool prima di inviarlo; virgole finali o errori di battitura in model sono cause comuni. Verifica che Content-Type sia application/json.

403 Forbidden

Causa: la chiave è valida ma manca l'autorizzazione ad accedere alla risorsa richiesta. Correzione: verifica che il tuo account abbia accesso a gpt-6-sol e che il nome del modello nel corpo della richiesta corrisponda a quello configurato per il tuo account.

404 Not Found

Causa: percorso URL errato, di solito un errore di battitura nell'endpoint, oppure un percorso di base mancante o duplicato. Correzione: confronta l'URL completo carattere per carattere con la chiamata curl funzionante.

429 Too Many Requests

Causa: stai inviando richieste più velocemente di quanto il tuo account consenta. Correzione: aspetta e riprova con ritardi crescenti. Rispetta eventuali indicazioni di retry presenti nelle intestazioni e non riprovare mai in un ciclo serrato: peggiorerebbe il problema. Distingui questo caso dai 5xx, che indicano un problema lato server e non un problema di frequenza delle tue richieste.

Errori 5xx del server

Causa: il servizio non riesce a gestire una richiesta per il resto valida. Correzione: riprova con attesa crescente; se il problema persiste, cattura il corpo della risposta e l'ID della richiesta ed evita di modificare il payload, dal momento che funzionava.

Una sequenza di debug ripetibile

  1. Codice di stato: si tratta di autenticazione, percorso o corpo della richiesta?
  2. Corpo della risposta: indica il campo problematico?
  3. Struttura del payload: torna all'esempio minimo.
  4. Solo per ultimi, considera il prompt o i parametri.

Questa sequenza riduce costantemente il tempo che intercorre tra un errore e la sua correzione. Una volta che le tue chiamate sono stabili, conserva affiancate le versioni funzionanti in curl e Python, così ogni futuro test parte da uno stato funzionante noto.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API