Tutoriale
Come chiamare claude-opus-5-5@aws tramite l'API HiAPI: guida per curl e Python
In questa pagina
Com'è usare claude-opus-5-5@aws tramite HiAPI
HiAPI fornisce un'interfaccia HTTP unificata per diversi modelli. Non devi configurare account, SDK e archiviazione delle credenziali separatamente per ogni provider: ti rivolgi a HiAPI con lo stesso formato di richiesta e selezioni il modello desiderato tramite il suo identificatore. In questo tutorial l'identificatore è claude-opus-5-5@aws—il suffisso @aws fa parte del nome del modello, non è un campo separato, e va passato così com'è.
Il ciclo di vita di una richiesta è il seguente:
- Autenticazione—invia la tua chiave API HiAPI come bearer token nell'header
Authorization. - Invio del payload in stile chat—un body JSON contenente
modele un arraymessages, in cui ogni messaggio ha unrole(system,useroassistant) e uncontent. - Ricezione della risposta JSON—la replica dell'assistente compare nell'array
choicesdella risposta, insieme ai metadati di utilizzo. - Continuazione della conversazione—aggiungi il messaggio dell'assistente e il tuo successivo messaggio utente allo stesso array
messagese invia di nuovo. L'API è senza stato; l'intera conversazione risiede nel payload della tua richiesta.
Poiché la struttura delle richieste è identica per tutti i modelli, il codice scritto per claude-opus-5-5@aws può essere migrato ad altri modelli cambiando solo la stringa model. Tieni questo campo in un unico punto del codice—come valore di configurazione o variabile d'ambiente—invece di codificarlo in più file.
Una nota sulla denominazione: la piattaforma documenta questo modello come claude-opus-5-5@aws. Usa esattamente questa stringa. Errori di battitura, spazi superflui o un suffisso mancante producono errori di tipo modello non trovato, senza avvisi utili.
Ottenere le credenziali e completare l'autenticazione
Prima di chiamare l'API devi ottenere una chiave API dal tuo account HiAPI. Tratta la chiave come un segreto: conservala in una variabile d'ambiente o nel gestore di segreti della piattaforma, mai nel controllo di versione e mai nel codice client inviato al browser.
HiAPI autentica le richieste tramite un bearer token nell'header Authorization:
export HIAPI_API_KEY="your-api-key-here"
Ogni richiesta deve includere:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Queste regole pratiche evitano la maggior parte dei fallimenti di autenticazione:
- Mantieni il prefisso letterale
Bearer, seguito da uno spazio e poi dalla chiave. La mancanza del prefisso o dello spazio è un errore di copia-incolla frequente. - Non racchiudere la chiave tra virgolette nel valore dell'header.
- Se ruoti la chiave, aggiorna la variabile d'ambiente e riavvia il processo—i worker di lunga durata tendono a memorizzare il vecchio valore.
- Quando incolli la chiave in un file
.env, controlla spazi finali o caratteri di nuova riga; alcuni loader non li rimuovono automaticamente.
Se la chiave manca o è malformata riceverai un errore di autenticazione (di tipo 401), non un errore di modello, quindi è facile distinguerlo dai problemi successivi. Una volta che la richiesta è autenticata con successo, lo stesso header è valido per lo streaming, il tool calling e tutte le altre modalità di questa guida—non servono credenziali diverse per ogni funzionalità.
Per il codice lato server, carica la chiave una volta all'avvio e passala a un client condiviso o a una piccola funzione wrapper. In questo modo centralizzi il segreto e rendi banale il passaggio tra credenziali di sviluppo e di produzione.
Costruire una richiesta funzionante con curl
Ecco una richiesta completa e funzionante. Sostituisci la chiave segnaposto con la tua, oppure esegui prima l'export della sezione precedente per far sostituire la variabile alla shell.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5@aws",
"messages": [
{
"role": "user",
"content": "Spiega in tre frasi perché un endpoint POST idempotente è importante per un'API di pagamento."
}
]
}'
Analisi dettagliata:
- Endpoint—
POST https://api.hiapi.ai/v1/chat/completions. - Header—il bearer token e il content type JSON. Entrambi necessari.
model—l'identificatore esattoclaude-opus-5-5@aws.messages—un array di oggetti con role e content. L'ultimo messaggio utente è quello a cui il modello deve rispondere.- Payload—
-dinvia JSON grezzo, quindi la gestione delle virgolette è importante. Nella shell racchiudi l'intero body tra apici singoli e usa virgolette doppie per le chiavi JSON.
La risposta è un JSON contenente un array choices. Il testo generato si trova in choices[0].message.content, insieme alle informazioni di utilizzo (conteggio dei token) per monitorare i consumi. L'utilizzo della risposta è fatturato a token; le tariffe attuali sono riportate nel pannello dei prezzi del sito.
Modifiche comuni:
{
"model": "claude-opus-5-5@aws",
"max_tokens": 512,
"temperature": 0.2,
"messages": [
{"role": "system", "content": "Sei un editor tecnico conciso."},
{"role": "user", "content": "Riassumi il payload della richiesta precedente in una riga."}
]
}
Usa max_tokens per limitare generazioni fuori controllo, temperature per regolare verbosità e varianza, e un messaggio system per impostare il comportamento una volta per ogni conversazione. Il messaggio system va inserito nello stesso array messages, prima dei turni utente.
La stessa richiesta in Python
La versione Python usa la libreria standard urllib, quindi lo snippet funziona senza installare nulla. Se preferisci una libreria client, la struttura della richiesta è identica—cambia solo il trasporto.
import json
import os
import urllib.request
API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"
def ask(user_message: str, system_message: str | None = None) -> str:
messages = []
if system_message:
messages.append({"role": "system", "content": system_message})
messages.append({"role": "user", "content": user_message})
payload = json.dumps({
"model": MODEL,
"messages": messages,
}).encode("utf-8")
request = urllib.request.Request(
API_URL,
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
body = json.loads(response.read().decode("utf-8"))
return body["choices"][0]["message"]["content"]
if __name__ == "__main__":
print(ask("Saluta usando esattamente cinque parole."))
Perché vale la pena mantenere questa struttura:
MODELeAPI_URLsono costanti a livello di modulo, quindi cambiare modello o endpoint richiede una sola riga.- La chiave proviene dall'ambiente; la funzione non accetta mai un parametro con il segreto grezzo.
- La logica di parsing è isolata in fondo, quindi puoi sostituire
urllibconhttpxorequestssenza toccare il modo in cui costruisci la conversazione.
Per proseguire una conversazione a più turni, aggiungi la replica dell'assistente e il successivo messaggio utente a messages prima di reinviare. Lascia crescere l'array fino al limite di contesto, poi riassumi i turni precedenti in un messaggio system per restare nel budget. L'utilizzo nella risposta si basa sui token; le tariffe attuali sono elencate nel pannello dei prezzi del sito.
Risposte in streaming per scenari interattivi
Per le UI di chat e le generazioni lunghe, lo streaming invia contenuti parziali man mano che vengono prodotti, invece di attendere la risposta completa. Il body della richiesta resta invariato tranne un campo:
{
"model": "claude-opus-5-5@aws",
"messages": [{"role": "user", "content": "Scrivi un breve changelog per una libreria che ha appena adottato lo streaming."}],
"stream": true
}
Con stream: true l'endpoint risponde con server-sent events: ogni blocco è una riga con prefisso data: , e lo stream termina con una riga di marcatore finale. La maggior parte dei blocchi contiene nell'array choices un delta con un frammento di testo, non il messaggio completo.
Usando curl, rimuovi l'effetto silenzioso di -sS per osservare l'output arrivare gradualmente:
curl -N https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Conta lentamente fino a cinque."}]}'
Il flag -N disabilita il buffering, così vedi i blocchi quando arrivano. In Python, leggi la risposta riga per riga:
with urllib.request.urlopen(request) as response:
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line.startswith("data: "):
continue
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
print(text, end="", flush=True)
Suggerimenti pratici:
- Gestisci sempre il marcatore finale
[DONE]e le righe vuote/di keep-alive; non dare per scontato che ogni riga sia JSON. - Non bloccare mai il thread della UI sull'intero stream—aggiungi i delta a un buffer man mano che arrivano.
- Se il client si disconnette, chiudi la risposta per liberare la generazione a monte.
- Lo streaming non cambia il modo in cui viene calcolato l'utilizzo; l'ultimo blocco di solito porta i metadati di utilizzo. La fatturazione avviene sui token di output; le tariffe attuali sono nel pannello dei prezzi del sito.
Aggiungere il tool calling alla conversazione
L'uso degli strumenti permette al modello di richiedere azioni strutturate dal tuo codice, non solo di generare testo. Alla richiesta si aggiunge un array tools; alla conversazione si aggiungono messaggi dell'assistente con tool_calls e messaggi con role: "tool" contenenti i risultati.
Definisci i parametri dello strumento con JSON Schema:
{
"model": "claude-opus-5-5@aws",
"messages": [
{"role": "user", "content": "Che tempo fa ora a Lisbona?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Restituisce il meteo attuale di una città.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Nome della città, ad esempio Lisbon"}
},
"required": ["city"]
}
}
}
]
}
Il modello può restituire un messaggio contenente tool_calls invece del testo finale. Ogni voce specifica il nome della funzione e porta un argomento sotto forma di stringa JSON. Il tuo compito è eseguire la funzione sul tuo sistema e poi aggiungere il risultato:
- Aggiungi così com'è a
messagesil messaggio dell'assistente contenentetool_calls. - Per ogni chiamata aggiungi un messaggio con
role: "tool", iltool_call_idcorrispondente dal messaggio dell'assistente e uncontentimpostato al risultato serializzato. - Invia di nuovo la richiesta con lo stesso array
tools. Il modello genererà quindi una risposta in linguaggio naturale basata sui tuoi risultati.
Misure di protezione da adottare fin da subito:
- Valida i parametri—prima di eseguire qualsiasi operazione, valida i parametri rispetto allo schema—non passare mai l'output del modello direttamente a una shell o a una query di database.
- Limita i cicli. Imposta un limite ai turni di tool calling (di solito tre-cinque), così un modello che continua a richiedere chiamate non entri in un ciclo infinito.
- Restituisci gli errori come risultati dello strumento. Se la funzione fallisce, invia una breve stringa di errore con il
tool_call_idcorrispondente; il modello può quindi riprovare o spiegare il fallimento invece di bloccarsi. - Mantieni descrizioni precise degli strumenti. Descrizioni vaghe causano selezioni errate dello strumento molto più spesso degli errori nei parametri.
Le definizioni degli strumenti vengono valutate insieme alla richiesta e contano nel consumo di token. Le tariffe attuali sono pubblicate nel pannello dei prezzi del sito.
Cosa fare dopo
Inizia dalla chiamata curl minima, spostala in una funzione wrapper Python, poi aggiungi streaming e strumenti solo se il tuo caso d'uso lo richiede. La stringa del modello claude-opus-5-5@aws resta sempre invariata—tutto il resto sono campi nel payload della richiesta.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business