Tutoriale
Come chiamare kimi-k3.1-pro-highspeed tramite l'API HiAPI: esempi curl e Python
In questa pagina
Cos'è kimi-k3.1-pro-highspeed e quando sceglierlo
kimi-k3.1-pro-highspeed è uno dei modelli conversazionali offerti da HiAPI. Si chiama esattamente come qualsiasi altro modello conversazionale della piattaforma: invii una serie di messaggi e ricevi un completamento. Il "high-speed" nel nome indica il compromesso previsto: scegli questo modello quando dai priorità alla latenza rispetto alla profondità di ragionamento grezza, quando vuoi tempi di risposta prevedibili anziché la risposta più lenta e dettagliata.
È quindi adatto a diverse categorie specifiche di carichi di lavoro:
- Interfacce interattive — UI di chat, autocompletamento e assistenti inline, dove l'utente sta aspettando la risposta.
- Pipeline ad alto throughput — attività di classificazione, estrazione, riepilogo e riscrittura, dove serve throughput e i risultati per singola richiesta sono brevi.
- Cicli di agenti multi-hop — flussi a più passaggi in cui ogni chiamata è piccola e la latenza totale dipende principalmente dal numero di round-trip, non da una singola chiamata.
Non è la scelta ovvia quando il compito richiede un ragionamento lungo e ponderato su un contesto ampio, o quando il contenuto generato richiede che "una passata lenta ma di alta qualità valga più di molte passate veloci". In questi casi, fai prima un benchmark della qualità dell'output e poi ottimizza per la velocità: una risposta veloce ma sbagliata costa più di una lenta ma corretta.
Poiché il modello è disponibile tramite l'interfaccia unificata di HiAPI, passare in seguito ad altri modelli o tornare ad esso comporta solo modificare il payload della richiesta, non riscrivere il codice. Metti il nome del modello nella configurazione invece di codificarlo nel punto di chiamata, e potrai fare test A/B con altri modelli senza toccare il codice che costruisce le richieste.
Cosa significa "conversazionale" in pratica
Ogni richiesta ha questa struttura: un identificatore di modello, una lista ordinata di messaggi (ogni messaggio con role e content), e parametri opzionali come stream, temperature e max_tokens. Il prompt di sistema viene passato come messaggio con role: "system". Questo è l'intero modello mentale: il resto della guida è solo il lavoro di plumbing attorno a questa forma.
Prerequisiti: credenziali, endpoint e nome del modello
Prima di scrivere qualsiasi codice, verifica di avere i seguenti quattro elementi. La maggior parte dei fallimenti alla prima chiamata deriva da mancanze in questa checklist, non da bug nel corpo della richiesta.
1. Una chiave API
Genera una chiave dalla dashboard del tuo account HiAPI. Trattala come un segreto: caricala da una variabile d'ambiente, non committarla mai nel repository e ruotala non appena appare nei log o in un notebook condiviso.
export HIAPI_API_KEY="your-key-here"
2. URL di base
L'endpoint è composto dall'URL di base di HiAPI più il percorso di chat completions. Metti l'URL di base nella configurazione, così potrai cambiarlo senza modificare il codice:
export HIAPI_BASE_URL="https://api.hiapi.ai/v1"
3. Identificatore del modello
La stringa del modello da inviare è esattamente:
kimi-k3.1-pro-highspeed
Copiala carattere per carattere. I nomi dei modelli corrispondono letteralmente: uno spazio in più, una differenza di maiuscole o un errore di battitura restituiscono un errore di modello non trovato, non un errore di validazione di altri campi, il che potrebbe portarti a cercare nel posto sbagliato.
4. Un client in grado di inviare HTTPS
Per gli esempi curl seguenti ti serve solo una shell con curl installato, presente di serie su macOS e sulla maggior parte delle immagini Linux. Per la parte Python ti servono Python 3.8+ e il pacchetto requests:
pip install requests
Se preferisci un client in stile SDK, lo stesso endpoint, la stessa chiave e lo stesso nome del modello funzionano ugualmente: ciò che conta è il formato di rete, e questa guida si attiene all'HTTP puro per non nascondere nulla dietro un'astrazione.
Controllo di integrità
Prima di costruire la richiesta completa, esegui un controllo rapido per verificare che la chiave e l'URL di base si risolvano: una chiamata volutamente minimale con un solo prompt di una parola. Se funziona, qualsiasi fallimento successivo riguarda il payload della richiesta, non le credenziali.
Una richiesta curl funzionante
Ecco una richiesta completa, copiabile e incollabile. Usa un messaggio di sistema per impostare il comportamento, un messaggio utente come richiesta effettiva e fissa max_tokens per mantenere breve la risposta durante i test.
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [
{"role": "system", "content": "Sei un assistente tecnico conciso. Rispondi in due frasi o meno."},
{"role": "user", "content": "Spiega cos'è una chiave di idempotenza e perché è importante per i retry."}
],
"temperature": 0.3,
"max_tokens": 200,
"stream": false
}'
Spiegazione campo per campo
model— l'identificatore del modello della sezione precedente. Obbligatorio.messages— un array ordinato.systemimposta personalità e vincoli;userporta il compito. L'ordine conta: i messaggi più in basso hanno priorità maggiore nel guidare il comportamento. Per i flussi multi-turno, aggiungi continuamente turniusereassistantallo stesso array, invece di concatenare tutto in un unico enorme messaggio utente.temperature— casualità del campionamento. Valori bassi danno output più riproducibili, ciò di cui hanno bisogno estrazione e classificazione. Alzala solo quando vuoi davvero variazione.max_tokens— limite della risposta generata. Impostarlo esplicitamente ti protegge da generazioni fuori controllo e rende la latenza prevedibile.stream— quifalse, il che significa che ricevi un oggetto JSON al completamento della generazione. Le sezioni successive trattanotrue.
Cosa viene restituito
La risposta è un oggetto JSON contenente un array choices. Il testo che ti interessa è in choices[0].message.content. C'è anche un blocco usage che descrive il consumo di token: registralo, perché quando la fatturazione è basata sui token è il tuo unico segnale del costo per singola richiesta.
Se stai facendo debug, passa l'output attraverso un formattatore per renderlo leggibile:
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | python -m json.tool
Mettere il corpo della richiesta in payload.json e usare -d @payload.json evita i problemi di quoting della shell non appena il payload supera qualche campo.
Portare la richiesta in Python
L'obiettivo qui non è uno script dimostrativo, ma una funzione importabile. Mantieni il payload identico alla versione curl — stessi campi, stessi nomi, stessa stringa del modello — così il comportamento non cambia quando cambi strumento.
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"
def chat(
user_message: str,
system_message: str = "Sei un assistente tecnico conciso.",
temperature: float = 0.3,
max_tokens: int = 400,
timeout: float = 30.0,
) -> str:
payload = {
"model": MODEL,
"messages": [
{"role": "system", "content": system_message},
{"role": "user", "content": user_message},
],
"temperature": temperature,
"max_tokens": max_tokens,
"stream": False,
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
data = response.json()
return data["choices"][0]["message"]["content"]
Poi:
print(chat("Riassumi in una frase la differenza tra PUT e PATCH."))
Perché è scritto così
- Usare
json=payloadinvece di scrivere JSON a mano — requests serializza correttamente e imposta il content type, eliminando un'intera classe di bug di quoting. timeoutesplicito — senza di esso, una connessione bloccata può sospendere il tuo processo worker a tempo indeterminato. Per completamenti brevi, trenta secondi sono abbondanti; per i percorsi interattivi, abbassalo.raise_for_status()il prima possibile — vuoi che il fallimento a livello HTTP emerga come eccezione al confine della chiamata, non comeKeyErrorsuchoicestre righe dopo.- Configurazione a livello di modulo — chiave, URL di base e modello concentrati in un unico punto. Per fare test A/B su altri modelli in seguito, basta cambiare una costante.
Conversazioni multi-turno
Per conversazioni reali, accetta una lista di messaggi come parametro invece di costruire due messaggi fissi:
def chat_with_history(messages: list, **kwargs) -> dict:
payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
r = requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=30.0,
)
r.raise_for_status()
body = r.json()
return {
"content": body["choices"][0]["message"]["content"],
"usage": body.get("usage"),
}
Aggiungi la risposta dell'assistente di nuovo a messages con role: "assistant" per continuare la conversazione, e pota i turni più vecchi man mano che la cronologia si allunga: il contesto viene fatturato, quindi una cronologia conversazionale illimitata aumenta silenziosamente il costo di ogni richiesta.
Abilitare e consumare le risposte in streaming
Imposta "stream": true e il server invierà la risposta in modo incrementale come server-sent event, invece di inviare un unico oggetto alla fine. Per qualsiasi contenuto che un utente sta guardando, vale il lavoro extra lato client: anche se il tempo totale di generazione non cambia, il tempo al primo token cala sensibilmente.
Vista lato curl
curl -N -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [{"role": "user", "content": "Scrivi un haiku sui retry."}],
"stream": true
}'
-N disabilita il buffering dell'output di curl, così puoi vedere effettivamente gli eventi arrivare mentre vengono inviati. Ottieni una serie di righe, ognuna che inizia con data: , che trasporta un frammento JSON. L'evento finale è data: [DONE]. Tratta quel sentinella come marcatore di fine stream, non come JSON da parsare.
Client Python
import json
import requests
def stream_chat(user_message: str, timeout: float = 60.0) -> str:
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": user_message}],
"stream": True,
}
pieces = []
with requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
stream=True,
timeout=timeout,
) as r:
r.raise_for_status()
for raw in r.iter_lines(decode_unicode=True):
if not raw or not raw.startswith("data: "):
continue
data = raw[len("data: "):].strip()
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
pieces.append(text)
print(text, end="", flush=True)
return "".join(pieces)
Regole per mantenere corretto lo streaming
- Concatena, non sostituire. Ogni chunk trasporta solo il nuovo frammento. Accumula in una lista e fai join una volta alla fine; aggiungere a una stringa in un ciclo è quadratico sugli output lunghi.
- Proteggiti dai contenuti mancanti. Alcuni chunk trasportano solo metadati, quindi
deltapotrebbe non avere la chiavecontent. Usa.get()e salta i valori vuoti. - Gestisci le righe incomplete. I confini dei frame possono spezzare una riga.
iter_linesse ne occupa, ma se parsi tu stesso il flusso di byte grezzo, bufferizza fino a vedere un carattere di nuova riga. - Imposta timeout adatti allo streaming. Uno stream totale può legittimamente superare il timeout di una richiesta breve. Usa un timeout di lettura più lungo o una scadenza per chunk, invece di disabilitare del tutto il timeout.
- Mantieni il percorso non-streaming. Quando ti serve solo il testo finale per un'attività in background,
stream: falseè più semplice e ha un costo di inferenza inferiore. Riserva lo streaming ai percorsi interattivi.
Interpretare le risposte di errore e progettare i retry
I retry aiutano solo se il fallimento è temporaneo. Riprovare ciecamente una richiesta malformata non fa che amplificare l'errore. La distinzione utile è: errori che correggi nel codice, ed errori che la rete o il server risolveranno da soli.
Classificazione per codice di stato
Non riprovare — correggi la richiesta:
- 400 Bad Request — JSON malformato, campo obbligatorio mancante o valore di parametro non valido. Leggi il messaggio di errore, correggi il payload e aggiungi un test per evitare che si ripeta.
- 401 Unauthorized — chiave mancante, malformata o revocata. Controlla il formato dell'header
Authorizatione verifica che la variabile d'ambiente sia effettivamente impostata nel processo in esecuzione, non solo nella tua shell. - 403 Forbidden — la chiave è valida, ma non è autorizzata a eseguire questa operazione o usare questo modello. Un ciclo di retry qui è puro rumore.
- 404 Not Found — di solito percorso sbagliato o identificatore di modello sconosciuto. Verifica l'URL di base e la stringa esatta del modello.
- Errori di validazione tipo 422 — tipo di parametro corretto ma valore inaccettabile (ad esempio un
temperaturefuori intervallo). Limita il valore nel codice.
Riprova con backoff:
- 429 Too Many Requests — hai superato il rate limit. Fai backoff e, se la risposta contiene un suggerimento retry-after, seguilo invece di indovinare.
- 500 / 502 / 503 / 504 — guasti lato server o gateway. È esattamente qui che serve il backoff esponenziale.
- Errori di connessione e timeout — il socket fallisce prima che la risposta sia completa. Riprova, ma solo se l'operazione è sicura da ripetere.
Un ciclo di retry che si comporta bene
import random
import time
import requests
RETRYABLE_STATUS = {429, 500, 502, 503, 504}
def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(url, headers=headers, json=payload, timeout=30.0)
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
else:
if r.status_code < 400:
return r.json()
if r.status_code not in RETRYABLE_STATUS:
raise RuntimeError(f"non riprovabile {r.status_code}: {r.text[:200]}")
if attempt == max_attempts:
raise RuntimeError(f"retry esauriti, ultimo {r.status_code}")
delay = base_delay * (2 ** (attempt - 1))
time.sleep(delay + random.uniform(0, 0.5))
raise RuntimeError("unreachable")
Due dettagli importanti in produzione
- Il jitter non è opzionale. Senza di esso, un gruppo di processi worker che colpiscono contemporaneamente il rate limit riproveranno all'unisono, ricreando il picco. Il termine casuale qui sopra li distribuisce.
- Limita il tempo totale, non solo il numero di tentativi. Quattro tentativi con backoff esponenziale possono superare la tua scadenza della richiesta. Limita il numero di tentativi in modo che il caso peggiore rientri nel budget del chiamante, e passa il tempo rimanente come timeout del tentativo successivo.
Non riprovare una richiesta in streaming dopo un fallimento parziale, a meno che tu non abbia deciso come gestire il testo già inviato all'utente. Il pattern comune è riprovare solo se non è ancora stato mostrato nulla, altrimenti esporre il troncamento.
Checklist prima del go-live
Prima che questo codice diventi un carico critico, esegui una breve checklist.
- Timeout ovunque. Ogni richiesta ha timeout espliciti di connessione/lettura, e il valore deriva dal tuo budget di latenza, non copiato dagli esempi.
- Segreti fuori dal repository. La chiave API proviene dall'ambiente o da un gestore di segreti e non viene mai scritta nei log. Rimuovi gli header da qualsiasi logger di richieste.
- Nome del modello centralizzato.
kimi-k3.1-pro-highspeedappare come un'unica costante, così puoi sostituirlo o fare test A/B senza search-and-replace. - Errori classificati, non inghiottiti. I percorsi riprovabili e non riprovabili sono distinti nel codice, il backoff include jitter e il numero di tentativi è limitato.
- Registra l'utilizzo. Registra l'utilizzo di token restituito da ogni risposta insieme a latenza e stato. Quando la fatturazione è basata sui token, è il primo segnale che il prompt sta diventando silenziosamente troppo grande.
- Percorso in streaming testato sul serio. Verifica che con lo stesso prompt l'output concatenato sia uguale all'output non in streaming, e che un'interruzione a metà stream non lasci la tua UI in uno stato corrotto.
- Costi controllati per progettazione. Imposta sempre
max_tokens, pota la cronologia conversazionale e riassumi i documenti lunghi prima di inserirli nel contesto: queste tre leve rendono la spesa proporzionata al valore.
Fatto questo, passare da una proof of concept curl a un chiamante di produzione è principalmente lavoro di configurazione. Inizia con la funzione non-streaming, aggiungi lo streaming quando esiste un percorso interattivo, e lascia che il wrapper di retry assorba i fallimenti che non puoi prevenire.
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