Come usare seedream-4.5/image-to-image tramite l'API hiapi: curl, Python e richieste disponibili

Per modificare un'immagine con seedream-4.5 basta inviare un singolo POST all'API unificata delle attività di hiapi, eseguire un breve polling e scaricare il risultato. Questa guida fornisce richieste curl funzionanti e uno script Python completo per seedream-4.5/image-to-image, con una descrizione precisa dei campi di input (verificata rispetto all'API online), l'uso con più immagini di riferimento e gli errori che incontrerai realmente.

Cosa costruirai e cosa ti serve

Obiettivo: inviare una o più immagini sorgente con un'istruzione di modifica a seedream-4.5/image-to-image e recuperare l'URL dell'immagine completata.

Prerequisiti:

• Una chiave API hiapi, ottenibile dalla tua console. Ogni richiesta seguente la usa come token Bearer.
• Immagini sorgente ospitate su un URL accessibile pubblicamente. L'API le recupera lato server; percorsi di file locali o URL privati non funzionano.

Il modello gira sull'endpoint delle attività asincrone: POST /v1/tasks crea l'attività, GET /v1/tasks/<taskId> riporta lo stato e l'immagine completata compare in data.output[0].url.

Descrizione dei campi di input (verificata)

seedream-4.5/image-to-image ha quattro campi di input obbligatori e non accetta altri campi: la descrizione dei campi è rigida e i campi sconosciuti vengono rifiutati con un 400:

Campo	Tipo	Vincolo
prompt	string	Istruzione di modifica
image_urls	array di stringhe	URL pubblici, massimo 14 immagini
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

Due cose da notare: non esiste il parametro n (un output per attività; per più varianti, crea più attività in parallelo); e a differenza di image-to-image di seedream-5.0-pro (che accetta 1K/2K), la 4.5 richiede 2K o 4K. Inviare 1K qui restituisce un errore di validazione.

Richiesta minima funzionante: curl

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

Una creazione riuscita restituisce l'ID attività in data.taskId. Esegui il polling:

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

Quando data.status raggiunge success, l'URL dell'immagine è in data.output[0].url. Se è fail, il motivo è in data.error.

Script Python completo

Non serve alcun SDK: bastano requests e un ciclo di polling:

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. Create the task
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # public URLs, max 14
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" or "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    # 2. Poll until terminal state
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}",
                            headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. Output URLs expire -- download immediately
            return requests.get(url, timeout=120).content
        if task["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} did not finish in 600s")

png = edit_image(
    "Turn this product shot into a clean studio photo on a seamless white background",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

Nota il commento al punto 3: gli URL di output hanno un timestamp di scadenza. Non appena l'attività ha successo, salva subito i byte nel tuo storage: non limitarti a conservare l'URL restituito e sperare che domani funzioni ancora.

Modifica con più immagini di riferimento

image_urls accetta fino a 14 immagini in una singola attività. È un'arma potente per attività di trasferimento di stile e composizione: passa l'immagine che vuoi modificare insieme alle immagini di riferimento e descrivi nel prompt come combinarle.

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Apply the color grading and lighting style of the second image to the first image, keep the subject unchanged",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

L'ordine è importante per il prompt, non per l'API: fai riferimento alle immagini per posizione ("prima immagine", "seconda immagine") così il modello sa quale è quale.

Considerazioni per la produzione

Usa un callback invece del polling. Per qualsiasi scenario al di fuori di uno script, aggiungi un oggetto callback a livello radice al momento della creazione dell'attività e salta del tutto il ciclo di polling:

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

Al completamento dell'attività, hiapi invierà via POST lo stato finale dell'attività al tuo URL. Il polling va bene per strumenti CLI e notebook; per un backend web il callback è la scelta corretta, altrimenti occuperai un processo worker per le decine di secondi necessarie a una modifica 2K.

Idempotenza. La creazione di attività non è idempotente: riprovare dopo un timeout di rete può generare (e fatturare) due attività. Salva il taskId nel momento in cui lo ricevi e, in caso di nuovo tentativo, verifica prima se esiste già un'attività attiva, poi creane una nuova.

Gestione degli errori. I due tipi di errore che incontrerai per primi:

• 401 permission_denied: chiave errata o chiave senza accesso a questo modello. Il corpo della risposta è simile a {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}}. Includi il request_id quando contatti il supporto.
• 400 INVALID_REQUEST: violazione della descrizione dei campi, con un messaggio preciso: valore di resolution errato, image_urls con più di 14 elementi, campo sconosciuto o image_urls non un array. Questi errori vengono intercettati prima dell'esecuzione dell'attività, quindi non comportano costi.

Le attività fallite riportano status: "fail" sull'attività stessa, con un oggetto error: gestiscilo come caso distinto dagli errori HTTP, come fa lo script Python sopra.

Prezzi

Il costo per immagine dipende dalla risoluzione. Consulta le tariffe attuali nella pagina dei prezzi. Le richieste rifiutate in fase di validazione (400) non avviano mai un'attività, quindi durante l'integrazione gli errori nella descrizione dei campi sono gratuiti.

Letture correlate

• Pagina del modello seedream-4.5/image-to-image: area di prova, prezzi e riferimento completo dei parametri
• seedream-4.5/text-to-image: stessa serie, generazione solo da prompt
• Guida a seedream-5.0-pro image-to-image: livello più recente, con enum di risoluzione diversa
• Documentazione hiapi: riferimento dell'API delle attività e autenticazione

Domande frequenti

Posso passare un file locale o un'immagine base64 invece di un URL? No. image_urls deve essere un array di URL accessibili pubblicamente: la piattaforma li recupera e li normalizza lato server. Carica prima nel tuo storage (S3, R2, qualsiasi CDN), poi passa l'URL.

Quante immagini di riferimento supporta seedream-4.5 image-to-image? Fino a 14 per attività. Superato il limite si ottiene un 400 con il messaggio image_urls: maxItems.

Perché ricevo un 400 quando imposto resolution a 1K? L'endpoint image-to-image della 4.5 accetta solo 2K o 4K. L'opzione 1K appartiene a image-to-image di seedream-5.0-pro: serie di livelli diverse hanno enum diversi.

Posso generare più varianti in una sola richiesta? No: la descrizione dei campi non prevede il parametro n e rifiuta i campi sconosciuti. Crea un'attività per ogni variante ed eseguile in parallelo; ogni attività restituisce un solo output.

Quanto dura l'URL del risultato? Gli URL di output hanno una firma e una scadenza. Dopo il successo dell'attività scarica subito l'immagine e archiviala tu, invece di fare hotlink dell'output dell'attività.

Qual è la differenza tra un errore HTTP e un'attività fallita? Un errore HTTP (400/401) indica che la richiesta non è mai diventata un'attività: correggi il payload o la chiave e invia di nuovo. Le attività terminate con status: "fail" sono state accettate ma non sono riuscite a completarsi; il motivo è nell'oggetto error dell'attività e, per i fallimenti transitori, riprovare con gli stessi input è di solito la scelta corretta.