Blog

Tutoriale

Come usare seedream-4.5/text-to-image tramite l'API HiAPI: esempi curl e Python

Guida pratica all'integrazione minima funzionante per sviluppatori

Nov 17, 2026
Immagine di copertina del blog di hiapi.ai: superfici in cemento grigio caldo si intersecano sotto la luce solare radente, con facce in ombra blu-grigio scuro e sottili giunture verde salvia che compongono una geometria minimalista.
In questa pagina

Cosa ti offre seedream-4.5/text-to-image

seedream-4.5/text-to-image è l'endpoint di generazione di immagini da testo disponibile tramite l'API HiAPI. Invii un prompt testuale e alcuni parametri opzionali, e il modello restituisce un'immagine generata. Puoi usarlo per creare illustrazioni di scene, mockup di prodotti, concept art o qualsiasi contenuto visivo che richieda testo leggibile renderizzato all'interno dell'immagine, come insegne, etichette o titoli brevi. L'endpoint è stateless: ogni richiesta è una generazione indipendente, quindi il controllo di ripetizioni e variazioni resta nel codice della tua applicazione.

Poiché viene eseguito dietro la stessa interfaccia unificata degli altri modelli HiAPI, ti autentichi una sola volta, usi lo stesso URL di base e le stesse convenzioni sugli errori, e non devi imparare un nuovo schema di integrazione quando cambi modello. La pagina di dettaglio del modello seedream-4.5/text-to-image elenca i nomi dei parametri e i valori accettati attuali: usa quella pagina come fonte autorevole per i campi, non questo articolo.

Struttura della richiesta: cosa invii e cosa ricevi

Ogni chiamata di generazione da testo ha la stessa struttura: invii una richiesta POST con corpo JSON all'endpoint HiAPI del modello. Il corpo della richiesta contiene i campi richiesti dal modello; la risposta contiene l'immagine generata e i metadati relativi alla richiesta.

Cosa invii

  • prompt (stringa, obbligatorio): la descrizione dell'immagine. È il principale punto di controllo; vedi la sezione sui prompt più sotto.
  • aspect_ratio oppure un campo relativo alle dimensioni (opzionale): controlla la forma della tela in output. Usa il nome esatto del campo indicato nella pagina di dettaglio del modello: non dare per scontato che coincida con il nome del parametro di altri modelli.
  • Qualsiasi opzione specifica del modello documentata nella pagina del modello (ad esempio suggerimenti su stile o qualità). Ometti i campi che non ti servono; l'API applicherà i valori predefiniti.

Cosa ricevi

Una risposta riuscita è un oggetto JSON. I campi che nel codice leggerai effettivamente sono in genere:

  • Il payload dell'immagine: a seconda dello schema di risposta, può essere l'URL dell'immagine generata oppure una stringa di immagine codificata in base64. Il tuo codice dovrebbe gestire il formato che l'endpoint restituisce effettivamente; la pagina del modello indica quale sia.
  • Metadati della richiesta, come un identificatore o uno stato, utili per il logging e l'assistenza.

Non tutti i campi sono garantiti in tutte le versioni, quindi valida la struttura della risposta invece di assumere uno schema fisso. Se costruisci un parser che cerca solo i campi che ti servono e tratta gli altri come opzionali, la tua integrazione resisterà a piccole variazioni della risposta.

La tua prima richiesta curl funzionante

La chiamata minima valida invia solo un prompt, nient'altro. Sostituisci la chiave segnaposto e il prompt con i tuoi, poi eseguila.

curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "un tranquillo caffè di strada al crepuscolo, calda luce dalle finestre, una lavagna con la scritta OPEN",
    "aspect_ratio": "1:1"
  }'

Riga per riga:

  • L'URL punta all'endpoint HiAPI del modello. Mantieni l'identificatore del modello esattamente come nella documentazione.
  • L'header Authorization trasporta la tua chiave API. Usare una variabile d'ambiente evita che la chiave finisca nella cronologia della shell e nei file sorgente.
  • Content-Type: application/json indica al server di analizzare il corpo della richiesta come JSON.
  • Il corpo JSON contiene il prompt e una proporzione opzionale. Inizia con una sola immagine e un solo prompt; itera sulla formulazione prima di aggiungere opzioni.

Se la chiamata riesce, la risposta conterrà i dati dell'immagine descritti nella sezione precedente. Salva l'output su file (o apri l'URL restituito) e controllalo prima di costruire altro. Se ricevi un errore di autenticazione, verifica che la chiave esista e che l'header sia scritto correttamente; se ricevi un errore sui parametri, ricontrolla i nomi dei campi sulla pagina del modello.

La stessa richiesta in Python

La versione Python usa la libreria standard requests: nessun SDK necessario.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"

payload = {
    "prompt": "un tranquillo caffè di strada al crepuscolo, calda luce dalle finestre, una lavagna con la scritta OPEN",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)

Due dettagli sono importanti. Primo, passa json=payload invece di una stringa costruita a mano: requests imposterà il content type e serializzerà correttamente. Secondo, imposta un timeout esplicito. La generazione di immagini può richiedere più tempo di una tipica chiamata API, quindi un timeout generoso con una modalità di errore esplicita è meglio di una richiesta che resta bloccata.

Il risultato stampato è la risposta grezza. Nel codice reale, estrai il campo immagine restituito dal tuo endpoint (URL o base64), poi scarica quell'URL con una seconda richiesta oppure decodifica il base64 in byte e scrivilo su disco. Metti questa logica di estrazione in una piccola funzione ausiliaria, così test e codice di produzione condividono la stessa logica di parsing.

Scrivere prompt per il fotorealismo e per testo leggibile

La qualità del prompt determina la qualità dell'output più di qualsiasi altro parametro. I due obiettivi più frequenti sono: scene fotorealistiche e testo chiaramente leggibile all'interno dell'immagine.

Fotorealismo

Descrivi la scena come farebbe un fotografo che compone l'inquadratura: soggetto, luce, ora del giorno, sensazione di obiettivo e ambiente. I sostantivi concreti battono gli aggettivi astratti. Invece di "un bel bar", scrivi "l'interno di un bar stretto e lungo, luce di mezzogiorno che entra da grandi finestre, bancone in legno, profondità di campo ridotta". Aggiungi un breve accenno di stile, come "photograph" o "documentary photo", per orientare il modello lontano dallo stile illustrazione. Mantieni un soggetto principale per prompt; soggetti in competizione producono spesso composizioni confuse.

Testo leggibile

Quando l'immagine deve contenere testo, metti il testo esatto tra virgolette e mantienilo breve. Un'insegna con la scritta OPEN o un'etichetta con la scritta FRESH BREAD è molto più affidabile di un intero paragrafo. Indica dove compare il testo, ad esempio "una lavagna sopra il bancone con la scritta OPEN", così il modello sa che quel testo appartiene a un oggetto. Se il testo esce illeggibile, accorcialo, semplifica la scena circostante e rigenera. Piccoli aggiustamenti alla formulazione sono normali; aspettati qualche iterazione.

Iterazione

Cambia una sola variabile alla volta: prima il prompt, poi la proporzione, infine qualsiasi opzione di stile. Salva i tuoi prompt e le impostazioni che hanno prodotto buoni risultati. Questo registro diventerà la tua base per le rigenerazioni ed eviterà che il debug si riduca a tentativi alla cieca.

Scegliere proporzioni e impostazioni di output

La proporzione decide la composizione prima ancora che il modello disegni qualcosa. Sceglila in base all'uso previsto, non per corrispondere a un valore predefinito.

  • Quadrata (1:1): post social, avatar, schede prodotto. Semplice e sicura.
  • Orizzontale (ad esempio 16:9): banner, key visual, slide di presentazione. Favorisce scene ampie: orizzonti, vetrine, interni spaziosi.
  • Verticale (ad esempio 9:16): schermi mobile, storie, poster. Funzionano meglio i prompt con un soggetto verticale chiaro: una persona in piedi, un edificio alto.

Se il tuo prompt descrive una scena ampia ma richiedi una tela verticale, il modello dovrà ritagliare o distorcere la composizione. Fai corrispondere la descrizione al formato. Per le pipeline a valle, genera alla dimensione adatta al tuo caso d'uso più grande e riduci successivamente; ingrandire immagini piccole raramente appare corretto. Quando ti servono più formati, fai una chiamata separata per ogni proporzione invece di ritagliare un'immagine in vari layout.

Le impostazioni di output oltre alla proporzione (suggerimenti di qualità, controlli di stile) sono specifiche del modello. Imposta solo ciò che è documentato nella pagina del modello e tratta ogni parametro aggiuntivo come una variabile da testare, non come un valore predefinito da copiare.

Gestire errori e limiti di frequenza

Le cause di errore in un'integrazione di produzione sono prevedibili: chiave errata, parametri non validi, timeout e limiti di frequenza. Gestisci ciascuna categoria in modo esplicito.

Valida prima di analizzare

Controlla prima il codice di stato HTTP. 2xx indica successo: allora analizza il corpo della risposta. 4xx di solito significa che c'è un problema nella tua richiesta: chiave non autorizzata, JSON malformato o valore di parametro non supportato. Questi problemi non si risolvono riprovando; registra il corpo della risposta, segnalalo al chiamante e correggi la richiesta. 5xx indica un problema lato server, di solito temporaneo.

Riprova con backoff

Riprova solo i fallimenti che potrebbero riuscire in seguito: risposte 429, timeout, errori di connessione e la maggior parte degli stati 5xx. Usa un backoff esponenziale con jitter: attendi un breve intervallo base, raddoppialo a ogni tentativo e imponi un limite al numero totale di tentativi. Non riprovare mai su 400 o 401; consumeresti solo quota inutilmente.

import time, random

def generate(payload, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
        except requests.RequestException:
            pass  # errore di rete: riprova qui sotto
        else:
            if r.status_code == 200:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                raise RuntimeError(f"non recuperabile: {r.status_code} {r.text}")
        time.sleep(min(2 ** attempt + random.random(), 30))
    raise RuntimeError("tentativi esauriti")

Rispetta i limiti

Mantieni il volume di richieste sotto il limite di frequenza indicato per il tuo account e considera il 429 come un segnale per rallentare, non per riprovare con più forza. Aggiungi un limite alla concorrenza nei worker e registra l'ID della richiesta a ogni tentativo, così da poter diagnosticare a posteriori limitazioni e fallimenti. Poiché le chiamate di generazione di immagini vengono fatturate in base all'output prodotto, i tentativi che generano immagini non sono gratuiti: valida l'input prima di inviare la richiesta.

Da chiamata di test a checklist di produzione

Prima di andare in produzione, verifica i seguenti punti operativi:

  • Gestione delle chiavi: le chiavi risiedono in variabili d'ambiente o in un gestore di segreti, mai nel controllo di versione. Ruota le chiavi secondo una pianificazione e immediatamente in caso di sospetta compromissione.
  • Timeout: ogni chiamata in uscita ha un timeout esplicito e il tuo chiamante ha un piano per quando il timeout scatta.
  • Logging: registra per ogni chiamata l'ID della richiesta, la versione del prompt, i parametri, lo stato e la latenza. Oscura chiavi e payload completi quando necessario.
  • Versionamento dei prompt: salva i prompt e le impostazioni che hanno prodotto output accettati, così da poterli riprodurre e ripristinare.
  • Consapevolezza dei costi: la generazione viene fatturata in base all'output, quindi limita la dimensione dei batch, evita tentativi non necessari e memorizza nella cache i risultati che riutilizzerai.
  • Degrado controllato: quando la generazione fallisce anche dopo i tentativi, passa a un'immagine in cache o a un segnaposto invece di rompere la pagina.

Inizia dalla singola chiamata curl di questa guida, spostala in una piccola funzione ausiliaria Python e solo dopo aggiungi concorrenza e batch. Man mano che l'integrazione cresce, la pagina di riferimento del modello seedream-4.5/text-to-image è il posto dove confermare i nomi dei campi.

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