Blog

Tutoriale

Come usare krea-3/text-to-image tramite l'API HiAPI: curl, Python e una richiesta eseguibile

Nov 10, 2026
Immagine di copertina: su uno sfondo grigio carbone caldo, una fascia di luce ambrata attraversa diagonalmente l'immagine, con sottili linee di colore complementare lungo i bordi.
In questa pagina

Perché chiamare krea-3/text-to-image tramite un'API aggregata

Ogni nuovo modello di immagine significa un altro SDK, un altro schema di autenticazione, un altro insieme di stranezze nelle risposte. Se pubblichi una sola funzionalità di immagini, questo costo è sopportabile. Ma se ne pubblichi diverse — o vuoi poter sostituire i modelli liberamente in futuro — diventa il costo principale del tuo lavoro.

Chiamare krea-3/text-to-image tramite HiAPI elimina questo costo. Integri una sola volta contro un'unica convenzione di endpoint, un'unica credenziale e un'unica struttura di risposta. L'identificatore del modello diventa un campo nel payload della richiesta, non una biforcazione nel codebase. Quando vuoi confrontare l'output con altri modelli di immagine o migrare i carichi di lavoro, cambi una stringa, non un'integrazione.

Per questo modello specifico, i vantaggi pratici sono concreti:

  • Tutte le richieste condividono la stessa struttura. Le chiamate text-to-image seguono la stessa convenzione di autenticazione e payload su tutta la piattaforma, quindi ciò che impari dalla prima chiamata si trasferisce direttamente al modello successivo.
  • Codice applicativo indipendente dal modello. Mantieni il nome del modello nella configurazione. Prototipare con krea-3/text-to-image e poi passare a un altro modello in produzione non dovrebbe richiedere modifiche al tuo livello HTTP.
  • Un unico punto di osservazione dell'utilizzo. Fatturazione, log delle richieste e risposte di errore provengono tutti dalla stessa interfaccia, anziché da N dashboard di fornitori.
  • Meno chiavi. Indipendentemente da quanti modelli chiami, devi archiviare, ruotare e limitare una sola chiave.

Il prezzo è il costo tipico dell'aggregazione: lavori attraverso un'interfaccia generica, quindi le stranezze specifiche dei modelli vengono normalizzate. In pratica, è proprio ciò che vuoi — input normalizzati, errori prevedibili e la libertà di trattare il modello come un parametro regolabile.

Questo tutorial mantiene deliberatamente un ambito ristretto. Costruiremo una richiesta eseguibile, la eseguiremo due volte (prima con curl, poi con Python), osserveremo come la formulazione del prompt orienta l'output verso lo stile fotografico o illustrativo, e poi faremo debug dei pochi casi di fallimento che rappresentano la maggior parte dei problemi alla prima chiamata. Niente diagrammi architetturali, niente opinioni sui framework — solo una richiesta che puoi inviare nei prossimi cinque minuti e una checklist da usare quando qualcosa va storto.

Presupposti: hai un account HiAPI, puoi leggere la chiave API dalla dashboard e hai familiarità con il terminale e l'interprete Python. Nient'altro è necessario.

Prima di inviare la richiesta

Tre condizioni devono essere soddisfatte prima della prima chiamata. Se le fai bene, il resto è soprattutto ottimizzazione; se le sbagli, passerai un'ora a fare debug del livello sbagliato.

1. Account e chiave API

Accedi a HiAPI e ottieni la tua chiave API dalla dashboard. Trattala come un segreto: deve risiedere in una variabile d'ambiente o in un gestore di segreti, mai in un file committato, mai in un prompt o in un messaggio di supporto. Gli esempi seguenti la leggono da una variabile d'ambiente:

export HIAPI_API_KEY="your-key-here"

Se la tua organizzazione supporta più chiavi, usa una chiave dedicata per questa integrazione, così puoi ruotarla indipendentemente dalle altre esecuzioni.

2. Convenzione dell'endpoint e header di autenticazione

Le richieste HiAPI usano l'autenticazione con bearer token — lo stesso schema che hai visto in altre centinaia di API:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Usa il base URL mostrato nel riferimento API di HiAPI per la regione del tuo account e aggiungi il percorso di generazione immagini ivi documentato. Non indovinare il percorso a memoria né da un post di blog (incluso questo) — il riferimento API è l'unica fonte di verità, e il percorso è l'unica parte della richiesta che può cambiare senza preavviso. Consiglio del tutorial: consulta il riferimento una volta, copia l'URL e salvalo in un valore di configurazione.

3. L'identificatore del modello, scritto esattamente così

L'identificatore del modello è krea-3/text-to-image. Mantieni il prefisso del namespace e i trattini esattamente come scritti — krea3/text2image o un semplice krea-3 falliranno con modello non trovato. Anche le maiuscole contano. Salvalo come costante:

MODEL = "krea-3/text-to-image"

È questa stringa a rendere la tua integrazione indipendente dal modello, quindi dagli un nome e trattala come configurazione, anziché codificarla a mano in ogni punto di chiamata.

Cose che non devi capire in anticipo

Non devi conoscere i nomi dei campi per dimensioni dell'immagine, seed o passi prima della prima chiamata. Inizia dalla configurazione minima: autenticazione, identificatore del modello, prompt. Una volta ottenuta una risposta 200, aggiungi i parametri uno alla volta, perché una richiesta fallita con cinque campi impostati ti dà cinque sospetti. Una richiesta fallita minimale te ne dà uno solo.

Costruire una richiesta eseguibile con curl

curl è il modo più rapido per isolare i due problemi della prima chiamata: credenziali e struttura del payload. Niente versione dell'SDK, niente virtual environment, niente runtime asincrono — solo una richiesta sulla rete.

La chiamata minima porta solo ciò che il modello richiede davvero: header di autenticazione, identificatore del modello e prompt.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-3/text-to-image",
    "prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
  }'

Due note prima di eseguire. Primo, $HIAPI_BASE_URL è un segnaposto — impostalo al base URL del riferimento API di HiAPI e verifica il segmento del percorso contro lo stesso riferimento. Secondo, il flag -sS mantiene l'output silenzioso ma mostra comunque gli errori, che è esattamente ciò che vuoi durante il debug.

Come appare una risposta sana: un oggetto JSON contenente un riferimento o dati dell'immagine generata e i metadati della richiesta. La struttura esatta è documentata nel riferimento API; non scrivere codice di parsing per una struttura che non hai ancora osservato. Salva la risposta reale su file, così da avere una verità di riferimento:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
  -o response.json

Poi ispezionalo con jq o con il tuo editor. Questo file è il tuo fixture di test: quando passi a Python, confronta l'output. Se la risposta Python differisce strutturalmente da response.json, il problema è nel tuo codice, non nel modello.

Il motivo per cui farlo prima con curl è la leva diagnostica. Se la chiamata curl riesce, la tua chiave è valida, l'URL è corretto e l'identificatore del modello viene risolto — quindi qualsiasi fallimento successivo è nel tuo codice applicativo. Se la chiamata curl fallisce, il corpo dell'errore ti dice quale di questi tre è il problema, e non hai ancora scritto una riga di codice.

Una volta che la richiesta minima riesce, aggiungi un parametro alla volta. Riesegui curl dopo ogni aggiunta. Conserva i payload riusciti; diventeranno fixture di input accettati per i tuoi test.

La stessa richiesta in Python

La versione Python è deliberatamente noiosa: stesso URL, stessi header, stesso corpo JSON. L'obiettivo è la portabilità — la struttura di richiesta che hai validato in curl dovrebbe trasferirsi allo script, poi al servizio, senza riprogettazione.

import os
import json
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"

def generate(prompt: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"model": MODEL, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate(
        "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
    )
    print(json.dumps(result, indent=2))

Alcune scelte deliberate:

  • Usa variabili d'ambiente, non valori letterali. La chiave non deve mai comparire nel codice sorgente. Se la variabile manca, os.environ["HIAPI_API_KEY"] fallisce rumorosamente all'avvio, il che è meglio di un 401 confuso tre livelli più in basso.
  • Chiama raise_for_status() prima del parsing. Vuoi che gli errori HTTP emergano come eccezioni, non come un KeyError quando provi a leggere un campo da un corpo di errore che è comunque JSON.
  • Un timeout generoso. La generazione di immagini non è un endpoint istantaneo. Imposta un timeout che lo rifletta e gestiscilo esplicitamente in produzione (vedi la sezione produzione).
  • Usa json= invece di costruire stringhe a mano. Lascia che la libreria serializzi. Concatenare JSON a mano è proprio la fonte di errori da virgole finali e virgolette.

Eseguilo una volta e confronta l'output con il response.json catturato in precedenza. La struttura dovrebbe corrispondere. Stampa il riferimento dell'immagine o i dati dell'immagine decodificata in base a ciò che la risposta restituisce — di nuovo, scrivi codice per la struttura osservata, non per quella ipotizzata.

Poiché MODEL è una costante, la stessa funzione generate() funziona con qualsiasi modello di immagine sulla piattaforma. È questo il ritorno del modello aggregato: spostarlo in un servizio, aggiungere un secondo modello o fare A/B test sugli output diventano cambiamenti di parametro, non riscritture.

Controllare lo stile fotografico e quello illustrativo

Lo stile non è un interruttore; è la direzione verso cui spingi il modello, e krea-3/text-to-image risponde alle stesse leve che useresti collaborando con un fotografo o un illustratore: soggetto, mezzo, illuminazione e vocabolario della tecnica.

Spingere verso lo stile fotografico

L'output fotografico consiste principalmente nel nominare gli strumenti e le loro conseguenze. Parole che descrivono fotocamera, obiettivo, pellicola e luce reale funzionano meglio della parola "realistico".

  • Nomina il mezzo e il modo di scatto: "fotografia 35mm", "ritratto editoriale", "fermo documentaristico".
  • Nomina la luce: "luce diurna coperta", "controluce dell'ora d'oro", "softbox singolo a sinistra della fotocamera".
  • Nomina le imperfezioni: "lieve motion blur", "grana visibile", "profondità di campo ridotta".

Confronta "un pescatore su un molo" con "un pescatore provato dal tempo che ripara una rete su un molo all'alba, luce coperta, fotografia 35mm, grana visibile". Il secondo prompt vincola il modello verso la texture e l'illuminazione fotografiche, anziché verso una rappresentazione generica.

Spingere verso lo stile illustrativo

L'illustrazione consiste nel nominare la tradizione, la qualità della linea e la palette — e spesso nel rimuovere gli indizi fotografici che hai appena imparato.

  • Nomina lo stile: "illustrazione vettoriale piatta", "inchiostro e acquerello", "illustrazione editoriale di metà secolo", "line art isometrica".
  • Nomina le linee: "tratti puliti e uniformi", "linee gestuali libere".
  • Nomina la palette: "palette essenziale a due colori", "pastelli tenui".

Iterare, non presupporre

Tratta il prompt come configurazione regolabile. Cambia una sola dimensione alla volta — sostituisci solo la frase del mezzo, mantieni invariati soggetto e illuminazione — così capisci cosa fa ciascun token. Conserva un breve registro delle varianti di prompt e degli output prodotti; questo registro vale più di qualsiasi libreria di preset, perché è calibrato sul tuo modello e sui tuoi contenuti.

Se la richiesta espone parametri oltre al prompt — dimensioni, seed o simili — regolali dopo aver fissato il prompt, non prima. Cambiare insieme il prompt e tre parametri non ti dice quale cambiamento ha fatto la differenza.

Diagnosticare gli errori più comuni

La maggior parte dei fallimenti alla prima chiamata rientra in quattro categorie. Segui la checklist in ordine; ogni passo esclude un livello.

Errori di autenticazione

Sintomo: 401 o 403, con un messaggio su credenziali o permessi.

  • HIAPI_API_KEY è davvero impostata nella shell che esegue il comando? echo $HIAPI_API_KEY — una stringa vuota assomiglia molto a una chiave sbagliata.
  • L'header è esattamente Authorization: Bearer <key>? Un Bearer mancante, virgolette in eccesso o un a capo incollato nella chiave causano tutti un fallimento.
  • La chiave è stata revocata o è limitata a un ambiente diverso? In caso di dubbio, rigenerala e ritesta con una chiamata curl.

Payload della richiesta malformato

Sintomo: 400, con un messaggio su corpo, campi o parsing JSON.

  • Valida il JSON prima dell'invio. In curl, una virgoletta non sfuggita nel prompt rovina il corpo. In Python, json= se ne occupa per te — un altro motivo per preferirlo.
  • Verifica la presenza di Content-Type: application/json.
  • Controlla i nomi dei campi contro il riferimento API. Un valore scritto correttamente sotto il nome di campo sbagliato resta comunque un 400.
  • Torna al payload minimo — solo modello e prompt — conferma che funzioni, poi aggiungi i campi uno alla volta.

Identificatore del modello errato

Sintomo: 404, o un 400 che indica modello sconosciuto o non disponibile.

  • Confronta la tua stringa carattere per carattere con krea-3/text-to-image. Il prefisso del namespace, i trattini e i segmenti del percorso contano.
  • Verifica di non aver introdotto spazi indesiderati o virgolette tipografiche copiando e incollando dalla documentazione.
  • Conferma che il valore non sia sovrascritto da un valore predefinito di configurazione da qualche parte nel codice.

Risposte di rate limit e quota

Sintomo: 429, o un messaggio su limiti o saldo insufficiente.

  • Fai backoff e riprova dopo un breve ritardo, anziché martellare l'endpoint.
  • Controlla il tuo utilizzo e saldo nella dashboard.
  • Se questo accade durante lo sviluppo, cerca un ciclo di retry che scatta più velocemente di quanto pensi — una richiesta fallita dentro un blocco try più un retry aggressivo esaurisce rapidamente i limiti.

Se nulla di quanto sopra risolve, cattura l'ID completo della richiesta e il corpo dell'errore dalla risposta e inviali al supporto. I corpi di errore su un'API aggregata sono di solito abbastanza specifici da indicare il problema; l'errore è parafrasarli anziché incollarli.

Passare alla produzione

La tua richiesta attuale è un prototipo. Quattro pratiche la trasformano in qualcosa che può funzionare in modo continuativo.

Gestire gli errori per categoria, non per stringa

Mappa i codici di stato HTTP ai comportamenti: gli errori di autenticazione sono difetti di configurazione che richiedono l'intervento di qualcuno; gli errori di payload 4xx sono difetti del codice, fai fallire la richiesta rumorosamente; 429 e 5xx sono transitori, riprova con backoff esponenziale e jitter. Non riprovare mai un 400 — sprecheresti solo quota per confermare lo stesso difetto. Imposta timeout espliciti e tratta i timeout come transitori.

if response.status_code == 429 or response.status_code >= 500:
    raise TransientError(response.status_code)
response.raise_for_status()

Registrare i prompt e versionarli

Ogni immagine generata dovrebbe essere riconducibile al prompt esatto che l'ha prodotta. Archivia il prompt, l'identificatore del modello, i parametri e l'ID della richiesta di risposta insieme. Tratta il testo del prompt come configurazione versionata — una stringa prompt_v3 inserita in un file di configurazione, non un valore letterale sepolto in una funzione. Quando la qualità dell'output cambia, devi sapere se è cambiato il prompt, i parametri o il modello.

Mantenere il nome del modello nella configurazione

krea-3/text-to-image dovrebbe comparire una sola volta, in una costante o in una voce di configurazione. È proprio questo il ritorno del modello aggregato: sostituire il modello, eseguire confronti o fare rollback diventano modifiche di configurazione, non il deployment di un nuovo percorso di codice. Rende anche banale instradare diversi carichi di lavoro verso modelli diversi in futuro.

Testare contro fixture

Salva come fixture le risposte riuscite catturate in questo tutorial. Verifica che il tuo codice di parsing le gestisca e usa i corpi di errore registrati per testare la mappatura degli errori. Scoprirai la deriva della struttura delle risposte prima dei tuoi utenti.

Inizia dalla chiamata curl minima, conferma la struttura della risposta, trasferiscila così com'è in Python, poi itera sul prompt una dimensione alla volta — e consulta il riferimento API di HiAPI per i dettagli dell'endpoint che possono cambiare.

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