Seedream 5.0 Pro API di text-to-image: curl, Python e come far scrivere bene il testo

Seedream 5.0 Pro text-to-image (seedream-5.0-pro/text-to-image) è il livello più costoso della famiglia Seedream 5.0, e il suo punto di forza è il testo nelle immagini: insegne, packaging, titoli di poster scritti lettera per lettera seguendo il prompt. Questo articolo fornisce esempi curl e Python pronti all'uso, tutti i parametri, gli errori più comuni e alcuni trucchi per far scrivere correttamente il testo.

Prima i prezzi

Risoluzione	Per immagine	100 immagini
1K	$0.05	$5
2K (predefinita)	$0.10	$10

Prezzo attuale di HiAPI, verificato il 18 ottobre 2026.

Il formato non influisce sul prezzo, e le generazioni fallite non vengono addebitate. Pro non ha 4K; per il 4K si può usare Seedream 5.0 Lite (2K/4K allo stesso prezzo di $0.035). Il confronto dei tre livelli è in Prezzi dell'API Seedream 5.0.

Un'immagine reale

16:9, 1K, testo sull'insegna al neon scritto lettera per lettera:

A neon-lit night market street in a rainy cyberpunk city, a glowing storefront sign reads "SEEDREAM 5 PRO" in crisp lettering, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range

Genera con questo prompt →

seedream-5.0-pro/text-to-image, 16:9, 1K, $0.05.

Generare la prima immagine

Preparazione: crea una API Key nella console e impostala come variabile d'ambiente:

export HIAPI_KEY="la tua Key"

curl: inviare il task

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
      "prompt": "A cozy coffee shop storefront at dusk, warm window light, a hand-painted wooden sign that reads \"THE DAILY GRIND\" in serif letters",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

Restituisce un taskId:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: controllare il risultato

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-..." \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando data.status è success, l'URL dell'immagine si trova in data.output[0].url. È un link temporaneo con scadenza: scaricalo subito:

curl -o result.png "<url in output>"

In 2K l'immagine è di solito pronta in circa un minuto.

Python (solo libreria standard)

import json, os, time, urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = os.environ["HIAPI_KEY"]

def api(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload else None,
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
        method="POST" if payload else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())

task_id = api(API, {
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
        "prompt": 'A minimalist product poster on matte black, bold white headline that reads "SHIP FASTER", small caption "batch v2.1" bottom right',
        "aspect_ratio": "3:4",
        "resolution": "2K",
    },
})["data"]["taskId"]

while True:
    task = api(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        raise RuntimeError(task)
    time.sleep(5)

urllib.request.urlretrieve(task["output"][0]["url"], "result.png")

Tutti i parametri

Campo	Obbligatorio	Valori
prompt	Sì	3–4000 caratteri, consigliato entro circa 600 parole inglesi
aspect_ratio	Sì	1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
resolution	Sì	1K ($0.05) o 2K ($0.10)
output_format	No	png (predefinito) o jpeg

I campi sono molto rigidi: seed, n, size, image_urls non sono accettati e, se passati in più, restituiscono HTTP 400. Una richiesta produce un'immagine; per averne più di una, invia più task in parallelo.

Le risoluzioni variano tra i livelli della stessa famiglia: Pro è 1K/2K, Lite è 2K/4K. Quando passi da un livello all'altro, ricorda di cambiare resolution.

Far scrivere correttamente il testo

• Metti tra virgolette il testo da scrivere: a sign that reads "OPEN 24 HOURS" è molto più affidabile di una parafrasi.
• Specifica posizione e stile: stile del carattere (serif, calligrafico, neon), posizione (in basso a destra, centrato), supporto (insegna in legno, porta a vetri).
• Non usare troppo testo: pochi testi brevi in un'immagine funzionano bene, i blocchi di testo lunghi no.
• Se il testo è importante, usa 2K: i testi piccoli sono più leggibili ad alta risoluzione.

Errori comuni

Sintomo	Risposta	Come correggere
Campo obbligatorio mancante	400, missing required field "aspect_ratio"	Invia tutti e tre i campi obbligatori
Valore enum non valido	400, resolution: value must be one of '1K', '2K'	Compila secondo la tabella sopra
seed, n e altri campi passati in più	400, additional properties ... not allowed	Rimuovi i campi superflui
Key non valida	401, permission_denied	Controlla la Key nella console

Se un task fallisce dopo la creazione, nel risultato della query appare status: "fail" e non viene addebitato nulla.

Note prima del go-live

• Usa i callback invece del polling: aggiungi al livello superiore del body della richiesta (allo stesso livello di model e input) "callback": {"url": "https://tuo-dominio/hooks/hiapi", "when": "final"}. Dopo la notifica, esegui un'altra GET del task per confermare il risultato.
• Evita addebiti duplicati: il task viene addebitato non appena viene accettato. Prima di riprovare, verifica di aver memorizzato il taskId di quel task: se ce l'hai, continua a interrogarlo invece di inviarlo di nuovo; in alternativa, includi l'header Idempotency-Key al momento dell'invio.
• Salva subito i risultati: i link di output scadono, non usarli direttamente come link esterni.

Domande frequenti

È possibile fissare il seed per riprodurre il risultato?

No, questa API non accetta seed. Per ottenere versioni simili a partire da immagini esistenti, usa seedream-5.0-pro/image-to-image, che accetta fino a 10 immagini di riferimento.

Qual è la differenza con Lite?

Lite costa $0.035 per immagine e ha risoluzione 2K/4K; Pro è 1K/2K e costa $0.10 per immagine in 2K. Il metodo di chiamata è lo stesso. Il confronto tra Flash e Lite con lo stesso prompt è in Seedream 5.0 Flash vs Lite.

È obbligatorio usare i callback?

No. Per script e task in batch va bene il polling diretto, interrogando ogni 5 secondi.

Puoi anche copiare direttamente il prompt dell'insegna al neon qui sopra e generare un'immagine per $0.05.