Tutoriale

Come usare seedream-5.0-lite image-to-image tramite l'API hiapi

Jul 7, 2026

Questo tutorial ti mostrerà come chiamare la modalità image-to-image di seedream-5.0-lite tramite l'API unificata delle attività di hiapi: la struttura esatta della richiesta, un comando curl eseguibile subito, uno script Python da inserire nel backend e le trappole di validazione che questo modello impone e che altri modelli non applicano.

Dopo aver letto questo articolo avrai uno script che riceve uno o più URL di immagini di riferimento e un prompt di modifica, e restituisce un URL dell'immagine generata scaricabile immediatamente.

Cosa ti serve

Un account hiapi e una chiave API. Puoi ottenerla nella console hiapi.
Una o più immagini di riferimento ospitate su un URL HTTPS pubblico. Il modello accetta fino a 14 immagini di riferimento per singola richiesta, ed è proprio questo che lo rende utile per i flussi di lavoro con più riferimenti: fondere il soggetto di un'immagine con lo stile o la scena di un'altra.
Un prompt testuale che descriva la modifica o la trasformazione (minimo 3 caratteri — sì, l'API lo verifica).

Tutte le richieste vengono inviate all'endpoint unificato delle attività, con la chiave nell'header Authorization:

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

Struttura della richiesta (e requisiti del modello)

L'id del modello è seedream-5.0-lite/image-to-image: passalo esattamente così com'è, identico a quello elencato in /v1/models. Il suo schema input è rigoroso: tutti e quattro i campi sono obbligatori:

Campo	Tipo	Descrizione
`prompt`	string	Istruzione di modifica. Lunghezza minima 3.
`image_urls`	string[]	URL di 1–14 immagini di riferimento.
`aspect_ratio`	string	Uno tra `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`.
`resolution`	string	Solo `2K` o `4K`. Questo modello non ha il livello 1K.

Chi migra da altri modelli della piattaforma inciampa spesso in due trappole:

resolution accetta solo 2K o 4K. Se il tuo codice condiviso di invio delle attività imposta "1K" per impostazione predefinita (cosa che funziona su molti altri modelli di immagini), questo modello lo rifiuterà con un 400.
I campi in eccesso vengono rifiutati, non ignorati. Inviare size, n o qualsiasi altra cosa al di fuori dello schema restituisce 400 INVALID_REQUEST con additional properties '<field>' not allowed. L'API delle attività valida input per modello: non riutilizzare ciecamente il payload di un altro modello.

Esempio minimo funzionante: curl

Crea l'attività:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Replace the background with a sunlit Tokyo street at golden hour, keep the subject unchanged",
      "image_urls": ["https://your-cdn.example.com/subject.png"],
      "aspect_ratio": "3:2",
      "resolution": "2K"
    }
  }'

In caso di invio riuscito, viene restituito un id attività in data:

{"code": 200, "data": {"taskId": "task_abc123..."}}

Interroga il risultato:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk-<your-key>"

Durante l'esecuzione, data.status è pending/processing. Al termine diventa "success" e l'immagine compare in data.output:

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

L'URL di output è valido per un periodo limitato (nota il campo expireAt). Scarica subito i byte e salvali autonomamente: non fare hotlink né persistere l'URL originale.

Più immagini di riferimento: passare più immagini

Per fondere più immagini di riferimento — ad esempio un'immagine di prodotto più un'immagine di riferimento di stile — basta aggiungere altri URL a image_urls e specificare nel prompt cosa contribuisce ciascuna immagine:

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "Place the product from the first image into the scene from the second image, matching its lighting and color grade",
    "image_urls": [
      "https://your-cdn.example.com/product.png",
      "https://your-cdn.example.com/scene-reference.jpg"
    ],
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}

Il limite massimo è 14 URL; il quindicesimo restituisce 400 INVALID_REQUEST: image_urls: maxItems: got 15, want 14. In pratica, 2–4 immagini di riferimento scelte con cura, accompagnate da un prompt che assegna esplicitamente un ruolo a ciascuna immagine ("mantieni il soggetto dell'immagine 1, adotta la palette dell'immagine 2"), producono modifiche molto più controllabili rispetto a una pila di immagini scarsamente correlate.

Per modifiche precise e mirate su una singola immagine — cambiare lo sfondo, cambiare i vestiti, rimuovere un oggetto — usa un solo URL di riferimento e specifica sia cosa cambiare sia cosa mantenere ("mantieni volto e posa invariati"). I modelli Seedream seguono bene le istruzioni di conservazione: essere espliciti è proprio la chiave che distingue una modifica precisa da una reinterpretazione totale.

Python pronto per la produzione: invio, polling, download

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Crea l'attività
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,  # questo modello: solo "2K" o "4K"
        },
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. Esegui il polling fino allo stato finale
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Scarica subito — l'URL scade
            img = requests.get(outputs[0]["url"], timeout=120)
            img.raise_for_status()
            return img.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} still running after 600s")


if __name__ == "__main__":
    png = edit_image(
        "Replace the background with a minimalist studio backdrop, keep the subject unchanged",
        ["https://your-cdn.example.com/subject.png"],
        aspect_ratio="3:2",
    )
    with open("edited.png", "wb") as f:
        f.write(png)
    print(f"saved edited.png ({len(png)} bytes)")

Usare i callback invece del polling

Il polling va benissimo per script e code di worker. Per un backend web, registra un callback al momento della creazione dell'attività e lascia che hiapi ti invii lo stato finale: l'oggetto callback si trova al livello superiore della richiesta, accanto a model:

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

Con "when": "final" riceverai una sola POST quando l'attività entra in stato success o fail. Due regole per il gestore:

Rendilo idempotente. Usa l'id attività come chiave di elaborazione, così le consegne duplicate del webhook non causano elaborazioni ripetute. Memorizza l'id attività al momento dell'invio e tratta il callback come una notifica "vai a prendere e completa", non come unica fonte di verità.
Mantieni un percorso di riconciliazione. Se il tuo endpoint è inattivo quando scatta il callback, scansiona periodicamente gli id non completati ed esegui GET /v1/tasks/<id> per recuperare ciò che è stato perso.

Se il tuo callback sembra non arrivare mai, controlla i modi di guasto più comuni in ordine di probabilità in Perché il tuo callback delle attività hiapi non si attiva.

Gestione degli errori: i tre fallimenti che contano davvero

401 permission_denied alla creazione — la tua chiave non può usare quel modello. Il corpo della risposta è simile a:

{"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "type": "hiapi_error"}}

Controlla i permessi di modello della chiave nella console, oppure usa una chiave con i modelli di immagini abilitati.

400 INVALID_REQUEST alla creazione — il tuo input non corrisponde allo schema del modello. Il messaggio elenca in una volta tutti i campi non validi (ad esempio resolution: value must be one of '2K', '4K'; <root>: additional properties 'size' not allowed), quindi leggilo per intero e correggi tutti i campi in un colpo solo. Sono errori permanenti: ritentare lo stesso payload fallirà sempre.

status: "fail" sull'attività — la creazione è riuscita ma la generazione è fallita (URL di riferimento non recuperabile dal backend, policy sui contenuti, capacità upstream). error.code e error.message dell'attività indicano il motivo. A differenza dei 400, alcuni di questi sono transitori e meritano un nuovo tentativo con backoff.

Vale anche la pena sapere che: eseguire GET su un id attività inesistente o scaduto restituisce 404 task not found; nella scansione di riconciliazione va trattato come stato finale, non come "ancora in attesa".

Dove andare adesso

Pagina del modello seedream-5.0-lite/image-to-image — playground e tariffazione per immagine.
Prezzi hiapi — tariffe aggiornate di tutti i modelli di immagini.
Migliori API image-to-image del 2026 — confronto tra seedream e gpt-image-2 e altri sulla stessa attività di modifica.
Tutorial image-to-image di gpt-image-2 — stessa API delle attività, schema di input diverso; ottimo esempio del perché i payload non sono intercambiabili tra modelli.
Documentazione hiapi — riferimento completo dell'API delle attività.

FAQ

Quante immagini di riferimento posso passare a seedream-5.0-lite image-to-image? L'array image_urls accetta al massimo 14 immagini. Minimo una: il campo è obbligatorio, quindi per una generazione puramente da testo usa seedream-5.0-lite/text-to-image.

Perché altri modelli accettano 1K mentre io ricevo "value must be one of '2K', '4K'"? Lo schema di input dell'API delle attività è definito per modello. La modalità image-to-image di seedream-5.0-lite offre solo output 2K e 4K; altri modelli offrono il livello 1K. Non riutilizzare il payload di un altro modello senza verificarlo.

Posso inviare le immagini di riferimento in base64 invece che come URL? Lo schema del modello accetta image_urls — un array di URL. Ospita le immagini su un URL HTTPS accessibile (qualsiasi CDN, bucket di archiviazione oggetti o URL precompilato va bene) e passa quell'URL.

Quanto dura una generazione e quanto è valido l'URL di output? Di solito molto meno del budget di polling di 600 secondi dell'esempio Python sopra. L'URL di output ha un timestamp expireAt: scarica subito i byte dopo il successo dell'attività e salvali nel tuo storage.

Lo stesso codice funziona con seedream-5.0-lite text-to-image? L'endpoint e il flusso sono gli stessi, ma text-to-image ha il proprio schema di input (senza image_urls). Sostituisci l'id del modello con seedream-5.0-lite/text-to-image e rimuovi le immagini di riferimento; poi verifica con una chiamata di test, perché i campi obbligatori differiscono tra le modalità.

Quanto costa ogni immagine? La tariffazione si basa sull'utilizzo per generazione e varia in base alla risoluzione. Controlla le tariffe in tempo reale nella pagina dei prezzi.