Come chiamare seedream-5.0-lite/text-to-image tramite l'API HiAPI: guida curl e Python

Cosa fa realmente questa integrazione

Avviare una chiamata testo-immagine su HiAPI è una breve conversazione tra il tuo codice e una coda di attività asincrona. Invii una richiesta che descrive l'immagine desiderata; la piattaforma convalida la richiesta, accetta l'attività e restituisce un identificatore. L'immagine non è nella prima risposta: viene generata in seguito. Il tuo codice monitora quindi l'attività finché non segnala il completamento e infine scarica l'immagine dall'URL esposto dall'attività.

Questa struttura è importante perché determina come scrivi l'integrazione. Ci sono tre momenti distinti: invio, polling e recupero. Ognuno ha i propri modi di fallire. L'invio fallisce quando il payload è malformato o il percorso del modello non è valido. Il polling fallisce quando il ciclo è scritto male: troppo veloce, troppo breve o incapace di distinguere 'ancora in esecuzione' da 'completato'. Il recupero fallisce quando tratti l'URL di output come permanente o dimentichi di scrivere i byte su disco.

A livello tecnico, seedream-5.0-lite/text-to-image è un modello generico testo-immagine sulla piattaforma HiAPI. Lo richiami tramite quell'identificatore esatto del modello. I parametri che invii sono quelli comuni a questo tipo di chiamata: il nome del modello, il prompt e qualsiasi parametro di controllo di dimensione o quantità dell'output indicato nella documentazione dell'endpoint. Non ti serve un SDK speciale; un normale client HTTPS è sufficiente.

Al termine di questa esercitazione avrai una richiesta riproducibile con curl, una funzione Python che la incapsula, accorgimenti su come formulare i prompt per rendere il testo renderizzato leggibile e nitido, e un ciclo di polling che termina davvero. Tutto passa attraverso lo stesso endpoint HiAPI, quindi una volta che una chiamata funziona, il resto è solo ottimizzazione dei parametri.

Costruire la richiesta con curl

Inizia dalla riga di comando. Una chiamata curl funzionante è il riferimento del payload: una volta che funziona, ogni altro linguaggio è solo un esercizio di traduzione.

Prima della prima chiamata ti servono due cose: la tua chiave API HiAPI e l'URL di base dell'API. La chiave va nell'header Authorization come token bearer. Evita il più possibile che finisca nella cronologia della shell; le variabili d'ambiente sono l'abitudine più semplice.

export HIAPI_API_KEY="your_api_key_here"

La richiesta stessa è un POST con corpo JSON. L'identificatore del modello è il segmento di percorso che chiami, il prompt descrive l'immagine:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/text-to-image",
    "prompt": "A minimalist poster for a coffee shop called North Roast, warm cream background, bold dark lettering"
  }'

Imposta HIAPI_BASE_URL sull'endpoint di invio testo-immagine mostrato nella documentazione della piattaforma; il percorso varia a seconda del prodotto, quindi copialo invece di indovinarlo.

Prima di scrivere altro codice, leggi la risposta. Un invio riuscito restituisce un oggetto JSON contenente un identificatore dell'attività e un campo di stato. Di solito lo stato indica che l'attività è in coda o in elaborazione, non ancora completata. È il comportamento previsto. Annota con precisione i nomi dei campi restituiti; li userai nelle due sezioni successive.

Due errori a livello di curl causano la maggior parte dei primi fallimenti. Il primo è una chiave mancante o con ambito errato: la risposta è un errore di autenticazione, non un errore del modello. Il secondo è un corpo malformato: virgolette non escapate nel prompt, virgole finali, virgolette singole dove il JSON richiede virgolette doppie. Se la piattaforma rifiuta il payload, valida il JSON separatamente con jq e stampalo in modo leggibile prima di dare la colpa al modello.

Quando l'invio restituisce un identificatore, hai una richiesta valida. Tutto il resto è attendere e recuperare.

Portare il codice in Python

La versione Python dovrebbe essere una funzione piccola e riutilizzabile, non uno script con un singolo prompt codificato. Usa requests (o httpx, se preferisci); la chiamata in sé non richiede un client speciale.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_image(prompt: str, **params) -> dict:
    payload = {
        "model": "seedream-5.0-lite/text-to-image",
        "prompt": prompt,
        **params,
    }
    response = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=30)
    response.raise_for_status()
    return response.json()

Ci sono tre scelte deliberate qui. La chiave e l'URL di base provengono dall'ambiente, quindi la funzione può essere inviata in sicurezza. Il parametro variadico **params ti consente di passare dimensioni di output o altre opzioni documentate senza modificare la funzione. E raise_for_status() trasforma immediatamente gli errori HTTP in eccezioni, che è ciò che vuoi: un 4xx all'invio non diventerà mai un'attività valida, quindi fallire in fretta è meglio che ispezionare un corpo di risposta confuso.

Il dizionario restituito è il tuo record dell'attività. Stampalo una volta durante lo sviluppo per conoscere i nomi esatti delle chiavi dell'identificatore e dello stato. Non indicizzarlo alla cieca; un piccolo accessor mantiene leggibile il resto del codice:

job = submit_image("A flat illustration of a paper plane over a city map")
print(job)

Se stampa un'attività in coda, il porting da curl è corretto. Se solleva un'eccezione, il messaggio dell'eccezione di raise_for_status() ti dice se si tratta di un problema di autenticazione o di payload, le stesse due categorie che incontreresti nella shell.

Scrivere prompt per conoscenza del mondo e testo renderizzato

I modelli testo-immagine sono più forti quando il prompt descrive ciò che dovrebbe essere visibile e più deboli quando allude a conoscenze che il modello deve inferire. seedream-5.0-lite/text-to-image può sfruttare il contesto generale del mondo (oggetti riconoscibili, convenzioni di design comuni, stili tipografici), ma devi comunque dargli abbastanza contenuto per ancorare quel contesto.

Per i prompt di scena, descrivi soggetto, composizione e stile visivo. 'A cozy reading nook by a window, soft afternoon light, three-quarter view, muted earth tones' dice al modello sia cosa disegnare sia come impostare lo stile. I prompt vaghi producono immagini generiche; i prompt specifici producono immagini utilizzabili.

Il testo renderizzato è dove i prompt di solito falliscono. Se hai bisogno di testo nell'immagine, segui alcune regole:

• Metti tra virgolette la stringa esatta. Scrivi il testo desiderato tra virgolette, in modo che sia chiaramente letterale e non descrittivo.
• Mantienilo breve. Titoli brevi o nomi di marca vengono resi in modo affidabile; i paragrafi no.
• Specifica posizione e stile. 'The word "North" centered at the top in a bold sans-serif' è meglio di 'some text at the top'.
• Evita testi concorrenti. Più elementi testuali distinti nella stessa immagine tendono a generare caratteri confusi. Se ne servono più, mantienili brevi e distanziali tra loro.
• Itera una variabile alla volta. Cambia la formulazione, non formulazione, layout e stile insieme, altrimenti non saprai cosa ha risolto il problema.

Per qualsiasi cosa implichi un contesto riconoscibile (categoria di prodotto, tipo di poster, tipo di insegna), nominalo esplicitamente. La conoscenza pregressa del modello è più utile quando il prompt gli dà un appiglio. 'A vintage travel poster for a coastal town' porta più contesto utile di 'a poster'.

Non inventare parametri. Se il prompt non produce la posizione del testo desiderata, modifica prima la formulazione del prompt stesso, poi prova opzioni non documentate che non hai visto.

Gestire attività asincrone e scaricare l'output

Il polling è il punto in cui l'integrazione fallisce silenziosamente. Le attività sono asincrone, quindi ti serve un ciclo che controlli lo stato, attenda tra un controllo e l'altro, alla fine rinunci e sappia esattamente quali valori di stato significano 'completato'.

import time

def wait_for_job(job_id: str, poll_interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/{job_id}", headers=HEADERS, timeout=30
        )
        response.raise_for_status()
        job = response.json()

        status = job.get("status")
        if status in {"succeeded", "completed"}:
            return job
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Job {job_id} ended with status {status}")

        time.sleep(poll_interval)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

Adatta il percorso di polling e le stringhe di stato a ciò che mostra la documentazione della piattaforma: questi due dettagli sono i più propensi a differire dallo schema sopra. La struttura è ciò che conta: una scadenza monotona, un'attesa tra i controlli, insiemi espliciti di successo e fallimento, e un timeout che solleva un'eccezione invece di restituire un'attività a metà.

Una volta che l'attività segnala successo, la risposta contiene l'URL dell'output. Considera quell'URL temporaneo. Scarica i byte immediatamente invece di memorizzare il link:

def download_image(url: str, path: str) -> None:
    response = requests.get(url, timeout=60)
    response.raise_for_status()
    with open(path, "wb") as f:
        f.write(response.content)

job = wait_for_job(job_id)
download_image(job["output"]["url"], "out.png")

Prima di andare avanti, verifica che il file sia un'immagine reale: aprilo, controlla le dimensioni o almeno verifica che la lunghezza in byte non sia insolitamente piccola. Se il server chiude correttamente, un download troncato appare come un successo a requests.

Errori comuni e come risolverli

La maggior parte dei fallimenti nelle prime integrazioni rientra in quattro categorie. Affrontale in ordine.

Invio rifiutato

Se la prima chiamata restituisce un 4xx, stampa il corpo della risposta. Un errore di autenticazione significa che la chiave è mancante, scaduta o non inviata come token bearer. Un errore di schema significa che il payload è malformato: campo del modello errato, prompt mancante o parametro documentato scritto male. Valida il JSON separatamente e confrontalo con l'esempio curl funzionante.

L'attività non termina mai

Il ciclo gira all'infinito o va in timeout. Controlla prima l'intervallo di polling: martellare l'endpoint senza attesa può attivare limiti di frequenza, facendo sembrare bloccata un'attività sana. Poi controlla il confronto dello stato: se la piattaforma restituisce success e tu confronti con succeeded, ogni attività sembra incompleta. Registra un valore di stato grezzo invece di indovinare.

L'URL di output restituisce 404 o 403

Gli URL di output sono firmati e limitati nel tempo. Se hai fatto polling a lungo prima di recuperare, il link potrebbe essere scaduto. Recupera subito dopo il completamento e, se devi conservare il risultato, salva il file invece del link.

L'immagine viene resa ma il testo è confuso

Questo è un problema di prompt, non di codice. Accorcia il testo, citalo con precisione, riduci il numero di elementi testuali e rendi più esplicite le istruzioni di stile. Riesegui apportando una modifica alla volta, così saprai quale aggiustamento ha aiutato.

La richiesta si blocca o va in timeout

Imposta sempre timeout espliciti sulle chiamate di invio e polling. Una richiesta senza timeout può bloccare indefinitamente un worker, e un ciclo di polling senza scadenza trasforma un'interruzione transitoria in un processo bloccato.

Quando si verifica un comportamento inatteso, riducilo alla chiamata curl minima che continua a fallire. Se la richiesta HTTP grezza si comporta male, il livello Python non è il problema: una volta che curl funziona di nuovo, riportare in Python è meccanico. La pagina del modello seedream-5.0-lite/text-to-image elenca i parametri correnti e la forma della risposta, quindi controlla lì prima di assumere i nomi dei campi.