Guida all'API Seedream 5.5: prezzi, parametri ed esempi di chiamata

Cosa può fare Seedream 5.5

Seedream 5.5 è un modello di immagini su HiAPI: un unico ID modello (seedream-5.5) copre due utilizzi. Se scrivi solo il prompt, generi un'immagine da testo; se alleghi anche immagini di riferimento, modifichi secondo le immagini di riferimento o ne preservi il contenuto visivo. Entrambi gli utilizzi passano dalla stessa interfaccia e dallo stesso set di parametri; la differenza sta solo nella presenza o meno di image_urls nella richiesta.

Ogni chiamata restituisce un'immagine. Di seguito spieghiamo nell'ordine «come si calcola il prezzo → come compilare i parametri → come inviare la richiesta → quali limitazioni esistono»; tutti i numeri fanno riferimento alla definizione dell'interfaccia al momento della stesura di questo articolo.

Prezzo: fatturazione a fasce di pixel, supplemento per ogni immagine di riferimento

Il costo è composto da due parti: il prezzo base della fascia di output più il costo delle immagini di riferimento.

• 1K / 1.5K: $0.0186 / immagine
• 2K (fascia predefinita): $0.0325 / immagine
• Immagine di riferimento: $0.0075 per immagine, anche la prima è a pagamento, massimo 10 immagini

Qualche esempio:

• Generazione da testo 1K, senza immagini di riferimento: $0.0186
• 2K, con 1 immagine di riferimento: $0.0325 + $0.0075 = $0.04
• 2K, con 10 immagini di riferimento (limite massimo): $0.0325 + $0.075 = $0.1075

Se non specifichi size, l'immagine viene generata in 2K e fatturata come 2K. Se ti servono solo bozze o immagini di piccole dimensioni, specificare esplicitamente "size": "1K" permette di risparmiare circa il 40%. In caso di fallimento dell'attività, il costo viene rimborsato integralmente.

Panoramica dei parametri

Oltre a model e prompt, tutti gli altri sono parametri opzionali:

• prompt: obbligatorio, da 1 a 5000 caratteri. Descrivi l'immagine da generare; con immagini di riferimento, indica chiaramente cosa modificare e cosa preservare.
• size: 1K, 1.5K, 2K, predefinito 2K.
• aspect_ratio: 10 opzioni disponibili — 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9, 2:1, 1:2. Se non specificato, il modello lo sceglie automaticamente in base al prompt e alle immagini di riferimento.
• image_urls: da 1 a 10 URL http(s) di immagini accessibili pubblicamente. Se non specificato, è una generazione puramente testuale.
• output_format: png o jpeg, predefinito png.
• background: auto, transparent, opaque, predefinito auto. Scegliendo transparent, il formato di output può essere solo png; abbinato a jpeg viene rifiutato.

Inviare una richiesta

Le attività di immagini di HiAPI sono asincrone: prima si crea l'attività, poi si consulta il risultato. model va al livello superiore, gli altri parametri vanno dentro input.

Generazione da testo (2K, 16:9):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.5",
    "input": {
      "prompt": "Un faro sulla costa al mattino presto, nebbia leggera, luce laterale morbida, stile fotografia realistica",
      "size": "2K",
      "aspect_ratio": "16:9"
    }
  }'

Modifica con immagine di riferimento (1K, sfondo trasparente, PNG):

{
  "model": "seedream-5.5",
  "input": {
    "prompt": "Mantieni la bottiglia e l'etichetta, rimuovi lo sfondo, sostituisci con una luce dall'alto morbida",
    "image_urls": ["https://example.com/bottle.jpg"],
    "size": "1K",
    "background": "transparent",
    "output_format": "png"
  }
}

Il costo di questo ordine è $0.0186 + $0.0075 = $0.0261. Dopo la creazione, usa l'ID attività restituito per chiamare GET https://api.hiapi.ai/v1/tasks/{taskId} in polling; quando lo stato diventa di successo, recupera l'URL dell'immagine dall'output e scaricala.

Limitazioni attuali

• Massimo 2K, nessuna fascia 4K.
• Non supporta l'output a livelli di immagine.
• Ogni chiamata produce una sola immagine; per averne più di una, invia più attività in parallelo.
• Le immagini di riferimento devono essere URL http(s) accessibili da Internet; non sono accettati percorsi di file locali o base64.
• Lo sfondo trasparente supporta solo PNG.

Come scegliere la fascia

Per poster pronti da pubblicare e immagini principali di prodotti, usa il 2K predefinito; per bozze di revisione interne, prove di stile in batch e miniature di piccole dimensioni, usa 1K o 1.5K (hanno lo stesso prezzo; 1.5K è più nitido, quindi se non hai motivo di scegliere 1K, usa direttamente 1.5K). Le immagini di riferimento sono fatturate per immagine: includi solo quelle che influenzano davvero il risultato; per più angolazioni dello stesso prodotto, prova prima con 1–2 immagini e aggiungine altre se il risultato non è sufficiente.