Blog

Tutoriale

Come chiamare gpt-5.6-sol@azure tramite l'API HiAPI: curl e Python

Autenticazione, struttura della richiesta, esempi disponibili e gestione degli errori

Nov 10, 2026
Fogli di carta sovrapposti color crema e grafite che si allontanano a piccoli gradini, con un foglio color terracotta come accento — copertina del tutorial gpt-5.6-sol@azure.
In questa pagina

Cosa significa gpt-5.6-sol@azure come target di modello HiAPI

gpt-5.6-sol@azure è un identificatore di modello, non un SDK separato, non un endpoint separato e nemmeno un metodo di autenticazione separato. È esattamente la stringa che inserisci nel campo model della richiesta di chat completion che invii a HiAPI.

Il suffisso @azure indica da quale provider backend è servita quella variante del modello. Dal punto di vista della tua applicazione, questo non cambia affatto il modo di chiamare: stesso URL di base, stessa autenticazione bearer, stessa struttura di richiesta e risposta di qualsiasi altro modello chat della piattaforma. Non devi installare nulla in più, né servono credenziali specifiche del provider — HiAPI gestisce instradamento e rapporti con i provider dalla sua parte.

Il risultato pratico: qualsiasi client compatibile OpenAI che stai già usando può puntare a questo modello con due modifiche: imposta l'URL di base del client su HiAPI e imposta il nome del modello su gpt-5.6-sol@azure. Se al momento hai il nome del modello codificato da qualche parte nella configurazione, questo è l'unico valore che devi cambiare quando passi a un altro modello sulla piattaforma — il che rende i confronti A/B molto economici.

In questo tutorial l'identificatore compare sempre come stringa letterale gpt-5.6-sol@azure. Digitarlo con precisione: è sensibile alle maiuscole, e gli spazi superflui introdotti da un copia-incolla sono una delle cause reali dell'errore "modello sconosciuto" descritto più avanti.

Cosa ti serve prima di iniziare

  • Un account HiAPI con accesso alla piattaforma.
  • Una chiave API generata dal tuo account.
  • Una shell con curl, oppure Python 3 con la libreria requests.

Gli esempi seguenti non richiedono altro.

Ottenere la chiave API e configurare l'autenticazione

L'autenticazione di HiAPI è un bearer token: la tua chiave API va inserita nell'header Authorization di ogni richiesta, preceduta dalla parola Bearer e da uno spazio.

Authorization: Bearer YOUR_API_KEY

Generi la chiave dalla dashboard del tuo account. Trattala come una password — è una credenziale attiva che può consumare il tuo saldo e non dovrebbe mai comparire in commit, screenshot, notebook condivisi o righe di log.

Salvarla in una variabile d'ambiente

L'approccio di base è esportare la chiave una volta per sessione shell e leggerla dall'ambiente ovunque serva:

export HIAPI_API_KEY="your-key-here"

Su un server, impostala tramite il process manager o un secret store, non con un file .env committato. Se il file .env è davvero l'unica opzione, aggiungilo a .gitignore prima di scriverci la prima chiave.

Referenziarla, non incorporarla

In curl fai riferimento alla variabile shell, così la chiave non compare mai nella cronologia dei comandi o nell'elenco dei processi:

curl -H "Authorization: Bearer $HIAPI_API_KEY" ...

In Python leggila a runtime con os.environ:

import os

API_KEY = os.environ["HIAPI_API_KEY"]

Usa deliberatamente os.environ["..."] invece di os.environ.get("..."): se la variabile manca, vuoi un errore evidente all'avvio, non un errore di autenticazione confuso quindici righe più avanti.

Regole di igiene delle chiavi da interiorizzare subito

  • Una chiave per ambiente. Tieni separate le chiavi di sviluppo e produzione, così puoi ruotare o revocare una senza rompere l'altra.
  • Esposta significa ruotata. Se una chiave è comparsa in un luogo pubblico, revocala ed emetti una nuova chiave — non limitarti a rimuovere il commit.
  • Non loggare gli header. Un middleware di logging delle richieste che scarica tutti gli header scriverà volentieri il tuo bearer token su disco. Oscura Authorization prima di loggare.

Se la prima chiamata restituisce un errore di autenticazione, la causa è quasi sempre una di queste: la variabile è stata esportata in una shell diversa da quella che esegue la richiesta, manca il prefisso Bearer , oppure la chiave è stata copiata con un carattere di newline finale.

Anatomia del corpo minimo della richiesta

Ogni chiamata a gpt-5.6-sol@azure è una POST con corpo JSON. Puoi costruire una richiesta valida con un solo campo, ed è il modo migliore per iniziare: prima ottieni una risposta, poi aggiungi i parametri.

Campi obbligatori

  • model — la stringa gpt-5.6-sol@azure. È ciò che instrada la richiesta al target corretto.
  • messages — un array di oggetti messaggio. Ogni oggetto ha role e content. I ruoli convenzionali sono system (istruzioni che modellano il comportamento), user (input) e assistant (turni precedenti in una conversazione multi-turno).

Il corpo minimo è questo:

{
  "model": "gpt-5.6-sol@azure",
  "messages": [
    { "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
  ]
}

Questo basta. La risposta arriva nella struttura chat completion: un array choices, il cui primo elemento contiene la risposta dell'assistente sotto message.content, più un blocco usage che descrive il consumo di token. Il tuo codice deve leggere da choices[0].message.content, senza dare per scontati altri campi.

Campi opzionali che vale la pena conoscere

Non sono obbligatori, ma sono quelli che userai per primi:

  • temperature — casualità del campionamento. Valori bassi rendono l'output più deterministico e ripetitivo; valori alti lo rendono più vario. Scegli il valore con intenzione, non per abitudine.
  • max_tokens (o il limite equivalente di lunghezza dell'output esposto dal tuo client) — tetto sulla lunghezza generata. Utile per controllare sia la latenza sia i costi.
  • top_p — un altro controllo della casualità. In pratica, regola temperature oppure top_p, non entrambi, altrimenti non puoi attribuire i cambiamenti di comportamento a nessuno dei due.
  • stream — se true, la risposta arriva in modo incrementale come server-sent event invece che come singolo documento JSON. Ottimo per le interfacce utente, ma richiede più lavoro per un parsing corretto.
  • stop — una o più sequenze che terminano la generazione in anticipo.

Nota sulle conversazioni multi-turno

L'API è stateless. Tra una richiesta e l'altra non viene conservato nulla. Per continuare una conversazione devi reinviare ogni volta l'intero array messages, aggiungendo le risposte precedenti dell'assistente e il nuovo messaggio dell'utente. Di conseguenza le conversazioni lunghe fanno crescere il corpo della richiesta e anche il consumo di token — tienine conto quando progetti una funzionalità di chat.

All'inizio mantieni il corpo snello

Parti dai due campi obbligatori e verifica di ottenere una risposta sensata. Poi aggiungi un parametro alla volta e osserva la differenza. Il debugging è molto più semplice quando hai una baseline recente e funzionante.

Richiesta disponibile in curl

Questa è una richiesta completa ed eseguibile. Se la tua regione o il tuo piano sono diversi, sostituisci l'URL di base con quello mostrato nella documentazione API della piattaforma e assicurati che HIAPI_API_KEY sia esportata nella shell corrente.

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol@azure",
    "messages": [
      { "role": "system", "content": "You are a concise technical assistant." },
      { "role": "user", "content": "Give me three practical uses for idempotency keys." }
    ],
    "temperature": 0.3
  }'

Cosa fa ogni flag

  • -sS nasconde la barra di avanzamento ma stampa comunque gli errori — così i fallimenti non passano inosservati.
  • -X POST imposta esplicitamente il metodo, soprattutto per leggibilità.
  • L'header Authorization porta il bearer token preso dall'ambiente.
  • Content-Type: application/json è obbligatorio; senza di esso il server non sa come interpretare il corpo.
  • -d fornisce il payload JSON. Racchiudilo tra apici singoli, così la shell non interpreta le virgolette doppie interne.

Leggere la risposta

Una chiamata riuscita restituisce JSON con un array choices. Il testo che ti interessa si trova in choices[0].message.content. C'è anche un oggetto usage con il conteggio dei token di prompt e completion — registralo, perché è il modo più economico per osservare la tendenza dei consumi prima che diventino una sorpresa.

Se vuoi vedere direttamente la struttura senza combattere col terminale, passa da un formattatore:

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
  | python3 -m json.tool

Questa riga è lo smoke test più rapido per una nuova chiave. Eseguila prima di toccare qualsiasi codice applicativo — se fallisce, il problema è nelle credenziali o nella connettività, non nel tuo programma.

La stessa richiesta in Python

La versione con requests è breve, ma va scritta con cura: controlla il codice di stato prima di analizzare il corpo della risposta, perché la struttura delle risposte di errore è diversa da quella delle risposte riuscite e, se accedi direttamente a choices, otterrai un confuso KeyError.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-5.6-sol@azure",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Give me three practical uses for idempotency keys."},
    ],
    "temperature": 0.3,
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

if response.status_code != 200:
    # Surface the status and the server's error body, not just the exception.
    print(f"HTTP {response.status_code}: {response.text}")
    response.raise_for_status()

data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))

Tre dettagli importanti

Usa json=payload, non data=json.dumps(payload). Passare il dizionario a json= imposta l'header Content-Type per te e serializza correttamente ogni volta. La serializzazione manuale è la fonte della maggior parte dei corpi di richiesta malformati.

Imposta sempre un timeout. Senza, una richiesta bloccata appende il tuo worker a tempo indefinito. Un timeout generoso è comunque molto meglio di nessuno.

In caso di fallimento stampa response.text. Il corpo dell'errore contiene i dettagli che ti servono — tipo di errore, codice e messaggio leggibile. Loggare solo il messaggio dell'eccezione di raise_for_status() scarta queste informazioni e ti lascia a indovinare.

Impacchettala in una funzione

Quando la chiamata funziona, promuovila a funzione che riceve l'array di messaggi come parametro e restituisce la stringa del contenuto. Questo mantiene pulito il codice applicativo e ti dà esattamente un punto in cui cambiare nome del modello, timeout o, più avanti, strategia di retry.

Diagnosticare gli errori comuni

Quasi ogni prima chiamata fallita rientra in quattro categorie. Ecco come distinguerle rapidamente.

Errori di autenticazione

Sintomo: risposta 401, oppure 403 se la chiave è valida ma manca l'accesso alla risorsa richiesta.

Controlla in ordine:

  1. HIAPI_API_KEY è davvero impostata nella shell o nel processo che effettua la richiesta? echo $HIAPI_API_KEY dovrebbe stampare qualcosa.
  2. L'header contiene la parola letterale Bearer e esattamente uno spazio prima della chiave?
  3. La chiave ha preso un newline finale o delle virgolette dal copia-incolla? Riesportala in modo pulito.
  4. La chiave è stata revocata o ruotata da quando l'hai copiata? Emettine una nuova.

Identificatore di modello sconosciuto

Sintomo: 400 o 404, con un messaggio che menziona il modello.

Il colpevole abituale è un refuso, una mancata corrispondenza di maiuscole o uno spazio superfluo nella stringa. gpt-5.6-sol@azure deve essere esatto — @, trattini e minuscole contano. Se leggi il nome del modello da un file di configurazione o da una variabile d'ambiente, stampa il valore e la sua lunghezza; gli spazi invisibili sono un colpevole comune.

Corpo della richiesta malformato

Sintomo: 400, con un messaggio che lamenta parsing JSON o campi mancanti.

  • Se l'errore parla di parsing, il tuo corpo non è JSON valido. In curl, racchiudi il payload tra apici singoli e le chiavi tra virgolette doppie. In Python, usa json=payload.
  • Se parla di messages, verifica di aver passato un array di oggetti con role e content, non semplici stringhe.
  • Se parla di model mancante, la chiave è scritta male o si trova al livello di annidamento errato.

Un rapido controllo di sanità: prima di inviare, passa il payload a un validatore JSON. Bastano pochi secondi per eliminare un'intera categoria di problemi.

Rate limit e quote

Sintomo: risposta 429, a volte con un suggerimento retry-after.

Significa che la tua richiesta è ben formata e autenticata, ma è arrivata troppo velocemente o ha superato la quota. La soluzione non è riprovare subito in un ciclo stretto — peggiorerebbe solo le cose. Usa un backoff esponenziale con jitter, limita il numero di tentativi e considera un 429 persistente come segnale per rivedere la concorrenza.

Errori lato server

500 o 502 non sono colpa tua. Riprova con backoff; se persistono, cattura l'ID completo della richiesta e il corpo della risposta prima di escalare — sono questi dettagli a rendere produttiva una conversazione con il supporto.

Abitudine di debug universale

Per ogni chiamata fallita registra quattro cose: stato HTTP, corpo della risposta, percorso dell'endpoint e nome del modello. Non loggare la chiave API. Questa quaterna distingue tutte le categorie sopra in pochi secondi, cosa che un messaggio di eccezione nudo raramente riesce a fare.

Prossimi passi dopo la prima chiamata riuscita

Una volta che lo smoke test restituisce contenuto, hai un'integrazione funzionante. Ecco come renderla duratura.

Tarare i parametri con intenzione

Scegli una temperatura per il tuo caso d'uso e annota il perché. I compiti di estrazione e classificazione di solito vogliono bassa casualità; il brainstorming ne vuole di più. Cambia un solo parametro per esperimento, così puoi attribuire i risultati. Se stai considerando lo streaming, prototipalo presto — le differenze nel parsing delle risposte sono abbastanza grandi che adattarlo dopo costa più fatica che usarlo fin dall'inizio.

Retry e timeout come strategia, non come ripensamento

Avvolgi la chiamata in un wrapper di retry con backoff esponenziale, solo per risposte 429 e 5xx. Non riprovare mai un 400 o un 401 — la richiesta o le credenziali sono sbagliate e riprovare fa solo perdere tempo. Imposta un timeout client per ogni richiesta e valuta una scadenza complessiva per i flussi utente.

Monitora costi e latenza fin dal primo giorno

Registra il blocco usage insieme alle tue misurazioni di latenza. Il conteggio dei token è l'input di ogni discorso sui costi, la latenza è l'input di ogni discorso sull'esperienza utente. Senza questi dati stai ottimizzando alla cieca.

Metti il nome del modello in configurazione

Codificare gpt-5.6-sol@azure in tre file è il modo per rendere dolorose le migrazioni. Tienilo in un unico valore di configurazione, così cambiare modello diventa una modifica di una riga — ed è anche il modo per confrontare i modelli in modo equo sulla piattaforma.

Sposta le chiavi in una gestione dei secret adeguata

Se sei partito dalle variabili d'ambiente sul tuo laptop, il percorso di produzione è un secret store gestito con iniezione a runtime. Stesso codice, custodia più sicura.

Rafforza il percorso dell'output

L'output del modello è input non attendibile. Se lo renderizzi come HTML, fai escaping. Se lo analizzi come JSON, validalo prima di agire. Se lo instradi verso sistemi downstream, decidi esplicitamente cosa succede quando la risposta è vuota o troncata.

Quando sei pronto a esplorare altri target di modello sulla piattaforma, usano la stessa struttura di richiesta — cambia solo la stringa model, quindi tutto ciò che hai costruito sopra resta valido così com'è.

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