Come usare seedream-5.0-pro/image-to-image tramite l'API hiapi: curl, Python e un esempio di richiesta eseguibile

Seedream 5.0 Pro è il modello immagine di punta di ByteDance; il suo endpoint image-to-image riceve una o più immagini di riferimento e un'istruzione testuale e restituisce il risultato modificato: ridipintura dello stile, sostituzione dello sfondo, pulizia di foto prodotto, composizione di più immagini. Su hiapi gira sopra l'API asincrona unificata tasks: prima crei un'attività, poi esegui il polling (oppure ricevi un callback) e infine scarichi l'output. Ogni parametro, valore enum e messaggio di errore riportato qui sotto è stato verificato rispetto all'API live prima della pubblicazione di questa guida.

Cosa costruirai e cosa devi preparare

Obiettivo: inviare un'immagine di riferimento e un'istruzione di modifica a seedream-5.0-pro/image-to-image, recuperare l'immagine modificata e salvarla in locale.

Ti servono due cose:

1. Una chiave API hiapi — ottienila dalla tua console. Va inserita nell'header Authorization: Bearer sk-....
2. URL di immagini accessibili pubblicamente — l'API recupera le tue immagini di riferimento lato server, quindi devono essere raggiungibili via HTTPS. Gli URL precompilati (presigned) del tuo bucket funzionano perfettamente; localhost o percorsi privati no. Se l'URL non è recuperabile, riceverai un errore normalizzato invece di un fallimento silenzioso.

Parametri (verificati)

L'ID del modello è seedream-5.0-pro/image-to-image, identico a quello restituito da GET /v1/models. Tutti e quattro i campi di input sono obbligatori:

Campo	Tipo	Obbligatorio	Valore / descrizione
prompt	string	Sì	L'istruzione di modifica.
image_urls	array di stringhe	Sì	Da 1 a 10 URL di immagini accessibili pubblicamente. Sempre un array, anche con una sola immagine.
aspect_ratio	string	Sì	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	Sì	1K oppure 2K

Ci sono due punti che generano facilmente errori:

• Lo schema è rigido. I campi sconosciuti vengono rifiutati: inviare n, size o seed restituisce 400 con additional properties ... not allowed. Ogni modello su hiapi ha uno schema di input diverso (alcuni modelli usano size, altri aspect_ratio), quindi non copiare i campi tra famiglie di modelli.
• Qui resolution supporta solo 1K/2K. Altri endpoint seedream accettano insiemi di risoluzioni diversi: conviene verificarli endpoint per endpoint invece di darli per scontati.

Esempio minimo eseguibile: curl

Crea l'attività:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

In caso di creazione riuscita, l'ID dell'attività viene restituito in data.taskId (risposta semplificata):

{ "data": { "taskId": "<your-task-id>" } }

Esegui il polling finché l'attività non raggiunge uno stato terminale:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Alla fine data.status sarà success — l'URL della tua immagine si trova in data.output[0].url — oppure fail, con i dettagli in data.error.code e data.error.message.

Script Python completo: crea, esegui polling, scarica

Usa solo la libreria standard — non serve installare nulla:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


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


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

Considerazioni per la produzione

Su un server, preferisci i callback al polling. Aggiungi un oggetto di primo livello callback durante la creazione dell'attività e hiapi farà una POST una sola volta al tuo endpoint al raggiungimento dello stato terminale:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

Nel gestore, tratta il callback come un segnale, non come fonte di verità: estrai l'ID dell'attività, poi richiedi di nuovo tu stesso GET /v1/tasks/<id> e agisci in base a quello. Per script, notebook e attività una tantum il polling resta la scelta giusta — basta mantenere l'intervallo intorno ai 5 secondi.

Rendi idempotenti i tentativi. Quando crei un'attività, salva la tua mappatura immagine sorgente → taskId. Se il processo si interrompe a metà polling, riagganciati al taskId salvato invece di inviare di nuovo la modifica — un nuovo invio genera una seconda attività fatturata.

Scarica subito l'output. L'URL in data.output[0].url è a tempo (ha una scadenza). Scarica i byte e salvali nel tuo bucket; non fare mai hotlinking diretto degli URL di output delle attività nei contenuti rivolti agli utenti.

Errori che incontrerai davvero:

• 401 con permission_denied — chiave API mancante o malformata. Verifica che l'header sia esattamente Authorization: Bearer sk-....
• 400 con INVALID_REQUEST — violazione dello schema di input. I messaggi di errore sono precisi, ad esempio resolution: value must be one of '1K', '2K' o image_urls: maxItems: got 11, want 10.
• image_urls must be an array — hai passato una stringa nuda. Anche con una sola immagine, avvolgila in una lista.

Passi successivi

• Pagina del modello: seedream-5.0-pro/image-to-image — capacità e stato attuale.
• Il prezzo per immagine è indicato nella pagina dei prezzi.
• Un'opzione di modifica più economica per pipeline ad alta concorrenza: come usare seedream-5.0-lite image-to-image.
• Per scegliere tra i modelli: Le migliori API image-to-image del 2026 confronta le stesse attività di modifica su tre modelli.
• Riferimento completo dell'API: documentazione hiapi.

Domande frequenti

Quante immagini di riferimento posso inviare al massimo? Fino a 10 URL in image_urls. Il limite è applicato lato server — 11 immagini restituiscono maxItems: got 11, want 10.

L'output può mantenere le proporzioni dell'immagine di input? Sì — imposta aspect_ratio su match_input_image. Per modifiche e ridipinture questo è di solito ciò che vuoi; scegli un rapporto esplicito come 16:9 solo quando ricomponi deliberatamente l'inquadratura.

seedream-5.0-pro image-to-image supporta il 4K? No. Questo endpoint accetta solo 1K e 2K. Se richiedi qualsiasi altro valore, riceverai un 400 con l'elenco dei valori consentiti.

Gli URL delle mie immagini devono essere pubblici? Devono essere recuperabili dai server hiapi via HTTPS. Gli URL precompilati (S3, R2, GCS) funzionano bene e ti permettono di mantenere privato il bucket stesso.

Quanto costa seedream-5.0-pro image-to-image per immagine? Il prezzo è calcolato per immagine generata con successo e varia in base alla risoluzione — consulta la pagina dei prezzi aggiornata per le tariffe attuali.

In cosa si differenzia da seedream-5.0-lite image-to-image? Pro è il livello di punta, pensato per modifiche più difficili e ad alta fedeltà; lite è l'opzione più rapida ed economica per grandi volumi. La struttura della richiesta è simile, quindi il modo più chiaro per decidere è eseguire la stessa attività di modifica su entrambi — parti dalla guida a lite e confronta i risultati con le tue immagini di riferimento.