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

Il significato di gpt-5.6-terra@azure in una richiesta HiAPI

In una richiesta HiAPI, gpt-5.6-terra@azure è un identificatore di modello: devi inserirlo nel campo model del corpo della richiesta di chat. Questo è l'intero accordo dal tuo lato. Non devi costruire URL specifici del fornitore, non devi cambiare SDK e non devi modificare la struttura del corpo della richiesta.

Il suffisso @azure è metadato di routing: indica a HiAPI quale backend deve gestire le richieste per questa variante del modello. Tutto il resto del corpo della richiesta — messages, temperature, max_tokens, stream, tools — mantiene la struttura standard di chat-completions che già conosci. Questo conta in pratica: se hai già una richiesta funzionante che chiama altri modelli su HiAPI, passare a gpt-5.6-terra@azure di solito richiede di cambiare una sola riga.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Adottare due abitudini rende rari i bug legati all'ID del modello:

• Tratta l'ID come una stringa opaca. Copialo così com'è, incluso @ e il suffisso minuscolo. Niente spazi, non cambiare maiuscole/minuscole.
• Mettilo nella configurazione, non sparso nel codice. Usare una costante o una variabile d'ambiente trasforma i test A/B tra ID di modelli diversi in un cambio di configurazione, anziché in un refactoring.

Poiché il suffisso gestisce il routing, non dovresti dedurre nulla sullo stack del servizio sottostante solo dall'ID. Latenza, limiti e parametri supportati sono proprietà che HiAPI espone quando rende disponibile il modello, quindi verifica prima il comportamento con una piccola richiesta reale e solo dopo inserisci le ipotesi nella tua applicazione.

Prerequisiti e preparazione della chiave

Prima della prima chiamata, verifica tre cose:

1. Un account HiAPI. Devi effettuare l'accesso per creare credenziali e consultare nella console le informazioni aggiornate su modelli e prezzi.
2. Una chiave API. Generala nella console e conservala in un luogo sicuro: trattala come una password. Questa guida non presuppone un formato specifico per la chiave; qualsiasi stringa ti dia la console è il valore da inserire nell'header Authorization.
3. Un client HTTP. Usa curl per verifiche rapide e Python 3 con requests o l'SDK compatibile con OpenAI per scrivere il codice dell'applicazione.

Tieni la chiave lontana dai file sorgente

Usa le variabili d'ambiente. Il modello è lo stesso su ogni piattaforma:

export HIAPI_API_KEY="your-key-here"

Poi richiamala a runtime. Nella shell: "$HIAPI_API_KEY". In Python: os.environ["HIAPI_API_KEY"]. In CI, usa l'archivio segreto fornito dal tuo provider, anziché committare un file .env.

Se incolli la chiave nel terminale per il debug, ricorda che potrebbe restare nella cronologia della shell: se è una credenziale reale, ruotala in seguito. Per lo sviluppo locale, usare una chiave usa-e-getta solo per i test è più facile da gestire rispetto a riutilizzare una credenziale di produzione.

Verifica il tuo Base URL e l'endpoint

HiAPI espone un endpoint chat completions compatibile con OpenAI. Prendi il base URL e il percorso dalla documentazione della tua console e mantienili coerenti tra curl e Python: la maggior parte delle segnalazioni del tipo "curl funziona ma Python no" si riduce a uno slash finale o a un segmento di percorso mancante.

Una richiesta curl funzionante

Ecco la chiamata minima corretta. Sostituisci il base URL con quello mostrato nella tua console e assicurati che HIAPI_API_KEY sia esportata.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

Spiegazione campo per campo:

• -sS silenzia la barra di avanzamento ma mostra comunque gli errori. Se vuoi vedere gli header della risposta insieme al corpo, aggiungi -i.
• Authorization: Bearer $HIAPI_API_KEY autentica la richiesta. Il prefisso Bearer e lo spazio sono necessari.
• Content-Type: application/json: se lo ometti, molti server rifiutano la richiesta prima ancora di analizzarne il corpo.
• model: l'ID esatto gpt-5.6-terra@azure.
• messages: un array ordinato. system imposta il comportamento; user contiene il prompt. Per le conversazioni a più turni, aggiungi in ordine i turni assistant e user.
• max_tokens: limite massimo alla lunghezza della risposta. Tienilo basso durante le verifiche rapide, così un eventuale errore costa poco ed è veloce.

Una risposta riuscita è un JSON che contiene l'array choices; il testo che ti serve è in choices[0].message.content. Per le prime volte, passa l'output attraverso un formattatore JSON, così vedi la struttura invece di affaticarti su una lunga riga.

Una volta che questa richiesta funziona, salvala come script shell che legge la chiave da una variabile d'ambiente. Avrai così un health check ripetibile da eseguire ogni volta che cambi l'ID del modello o i parametri.

La richiesta Python equivalente

Il corpo della richiesta è identico: cambia solo il modo di trasporto. Con requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Ci sono tre dettagli che vale la pena mantenere: usa json=payload invece di serializzare a mano (imposta gli header e la codifica al posto tuo), imposta sempre un timeout e chiama raise_for_status(), così un 4xx o 5xx emerge come eccezione invece di generare un IndexError quando indicizzi il corpo di una risposta di errore.

Stile SDK del fornitore

Poiché l'endpoint è compatibile con OpenAI, un SDK configurato con un base URL personalizzato produce la stessa richiesta:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

Mostrare entrambi i modi ha senso perché: l'ID del modello è l'unica variabile che identifica quale modello ti serve. Il resto è una normale pipeline chat-completions, quindi puoi passare da HTTP grezzo all'SDK senza riscrivere la logica.

Aggiungere streaming e tool calling

Entrambe le funzionalità sono incrementali. Non riscrivi la richiesta di base: aggiungi campi e cambi il modo di consumare la risposta.

Streaming

Imposta "stream": true nel corpo della richiesta:

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

La risposta diventa una serie di server-sent event, anziché un singolo oggetto JSON. Ogni chunk porta un delta che contiene un frammento di contenuto; sul primo e sull'ultimo chunk delta.content può essere None, quindi controlla prima di concatenare. Con HTTP grezzo vale lo stesso: leggi il corpo riga per riga, rimuovi il prefisso data: , salta [DONE] e analizza il JSON di ogni riga.

Tool calling

Descrivi i tool nella richiesta e lascia che il modello decida quando chiamarli:

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

Quando il modello vuole chiamare un tool, choices[0].message contiene un array tool_calls anziché testo semplice. Ogni voce ha un id e una function che contiene name e arguments (una stringa JSON che devi analizzare). Esegui la tua funzione, poi invia il risultato come messaggio con role: "tool", con il tool_call_id corrispondente e l'output serializzato: quindi avvia una nuova richiesta per ottenere la risposta finale.

tool_choice accetta "auto" (decide il modello), "none" (solo testo) o una funzione specifica. Streaming e tool possono essere combinati, ma gli argomenti del tool calling arrivano a frammenti tra i vari chunk e devi accumularli prima di analizzarli: fai prima funzionare il tool calling in modalità non streaming.

Diagnosticare gli errori di richiesta più comuni

Esegui il debug in questo ordine; ogni passo isola un livello, così non insegui due problemi contemporaneamente.

1. Autenticazione (401 / 403)

Le cause più probabili: chiave mancante, prefisso Bearer perso o variabile d'ambiente espansa in una stringa vuota. Mostra come viene costruito l'header senza stampare l'intera chiave e verifica che la variabile sia impostata nella stessa shell o nello stesso processo che esegue la richiesta.

2. Endpoint e percorso (404)

Un 404 di solito significa percorso errato: errore di battitura, /v1 mancante o uno slash finale aggiuntivo dove non dovrebbe esserci. Copia l'URL esatto dalla console, non ridigitarlo.

3. ID del modello (400, con messaggio sul modello)

L'ID deve corrispondere esattamente: gpt-5.6-terra@azure. Gli errori comuni includono variazioni di maiuscole/minuscole, @azure mancante o spazi extra dal copia-incolla. Se il messaggio dice che il modello è sconosciuto, confronta carattere per carattere la stringa configurata con l'elenco della console prima di sospettare un guasto del servizio.

4. Corpo della richiesta malformato (400 / 422)

Se l'errore menziona il corpo della richiesta, controlla prima la validità del JSON: virgole finali o virgolette non escapate sono i colpevoli abituali. Poi verifica i nomi dei campi (è messages, non message) e i ruoli (system, user, assistant, tool). max_tokens deve essere un numero e tools deve essere un array di oggetti strutturati correttamente.

5. Trattare una risposta in streaming come JSON normale

Se l'output è vuoto, illeggibile o genera un errore di parsing, probabilmente hai richiesto stream: true ma stai analizzando la risposta come un singolo documento JSON. Leggi come flusso di eventi, salta [DONE] e proteggiti dai delta None.

6. Timeout del client

Le generazioni lunghe possono superare il timeout HTTP predefinito. Aumentalo esplicitamente nel client oppure passa allo streaming, così i byte iniziano ad arrivare subito.

Checklist per la riproduzione rapida

• Esegui la chiamata curl minima. Se funziona, il problema è nel tuo codice.
• Se fallisce, riprova in una shell nuova con la tua chiave e l'ID del modello.
• Registra sia il codice di stato HTTP sia il corpo della risposta: il corpo di un errore contiene dettagli diagnostici.
• Solo dopo che questi controlli sono passati dovresti sospettare un problema lato server che valga la pena di essere escalato.

Con una richiesta funzionante, un ciclo di streaming e questa checklist, gpt-5.6-terra@azure si comporta nel tuo stack come qualsiasi altro modello di chat, e cambiare modello diventa una modifica di una riga nella configurazione.