Blog

Tutoriale

Come chiamare kimi-k3.1-pro-highspeed tramite l'API HiAPI: esempi curl e Python

Nov 12, 2026
Immagine di copertina del blog HiAPI: su fondo marrone scuro, ampie fasce intrecciate con ritmo a intreccio da cesto, con accenti beige e color ottone, che compongono una vista dall'alto.
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. system imposta personalità e vincoli; user porta il compito. L'ordine conta: i messaggi più in basso hanno priorità maggiore nel guidare il comportamento. Per i flussi multi-turno, aggiungi continuamente turni user e assistant allo 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 — qui false, il che significa che ricevi un oggetto JSON al completamento della generazione. Le sezioni successive trattano true.

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=payload invece di scrivere JSON a mano — requests serializza correttamente e imposta il content type, eliminando un'intera classe di bug di quoting.
  • timeout esplicito — 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 come KeyError su choices tre 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 delta potrebbe non avere la chiave content. Usa .get() e salta i valori vuoti.
  • Gestisci le righe incomplete. I confini dei frame possono spezzare una riga. iter_lines se 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 Authorization e 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 temperature fuori 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-highspeed appare 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.

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