# API Seedream 5.5 (https://wanapi.app/it/docs/seedream-5-5)





Seedream 5.5 genera un'immagine da testo o da fino a 10 immagini di riferimento. La scomposizione in livelli riceve un'immagine e restituisce una base più livelli trasparenti, con un risultato facoltativo di riconoscimento del testo stampato.

[Prova il Playground](/it/models/seedream-5-5#playground) · [JSON OpenAPI](/models/seedream-5-5/openapi.json) · [Tutorial di integrazione](/it/blog/seedream-5-5-api-guide)

## Autenticazione ed endpoint [#autenticazione-ed-endpoint]

Usa la tua chiave Wan API come token Bearer. Una chiave accede a tutti i modelli e gruppi disponibili; non selezioni un gruppo sulla chiave.

| Metodo | URL                                                       | Scopo                      |
| ------ | --------------------------------------------------------- | -------------------------- |
| POST   | `https://api.wanapi.app/seedream55/v1/images/generations` | Invia un'attività immagine |
| GET    | `https://api.wanapi.app/seedream55/v1/tasks/{id}`         | Leggi l'attività           |

L'ID modello è &#x2A;*`seedream-5-5`**. Questi endpoint sono asincroni. Invia una sola volta, salva l'ID attività ed esegui il polling fino a `completed` o `failed`. Una risposta di rete incerta non autorizza un nuovo invio.

## Genera un'immagine [#genera-unimmagine]

```bash
curl https://api.wanapi.app/seedream55/v1/images/generations \
  -H "Authorization: Bearer $WAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning light. No text.",
    "size": "1K"
  }'
```

Una richiesta accettata restituisce un'attività anziché i byte dell'immagine:

```json
{"id":"task_example","model":"seedream-5-5","status":"processing","created_at":1794432000}
```

```bash
curl https://api.wanapi.app/seedream55/v1/tasks/task_example \
  -H "Authorization: Bearer $WAN_API_KEY"
```

Esegui il polling dello stesso ID ogni pochi secondi. Conservalo se l'applicazione smette di attendere, così potrà riprendere in seguito. Gli ID attività e i timestamp di questa guida sono illustrativi.

## Parametri [#parametri]

| Parametro                                      | Tipo               | Predefinito                     | Regole                                                                                                                  |
| ---------------------------------------------- | ------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `model`                                        | stringa            | obbligatorio                    | `seedream-5-5`                                                                                                          |
| `prompt`                                       | stringa            | obbligatorio per la generazione | Facoltativo per la scomposizione in livelli.                                                                            |
| `image`                                        | URL o array di URL | nessuno                         | Fino a 10 riferimenti; esattamente uno per i livelli. Ogni riferimento viene addebitato.                                |
| `size`                                         | stringa            | `2K`, o `auto` per i livelli    | Vedi le regole sulle dimensioni sotto.                                                                                  |
| `output_format`                                | stringa            | `png`                           | `png` o `jpeg`. Per i livelli controlla solo l'immagine di base.                                                        |
| `background`                                   | stringa            | `auto`                          | `auto`, `opaque`, `transparent`. La trasparenza richiede PNG. Ometti completamente questo campo nella modalità livelli. |
| `layer_decomposition`                          | booleano           | `false`                         | Separa un riferimento in un'immagine di base e livelli PNG trasparenti.                                                 |
| `layer_decomposition_options.max_images`       | intero             | `30`                            | Limite totale di 2–100 immagini, base inclusa. Solo per la modalità livelli.                                            |
| `layer_decomposition_options.text_recognition` | booleano           | `false`                         | Richiedi metadati del testo stampato nei livelli. Solo per la modalità livelli.                                         |
| `optimize_prompt_options.mode`                 | stringa            | `standard`                      | L'unica modalità supportata è `standard`.                                                                               |
| `watermark`                                    | booleano           | `false`                         | Richiedi una filigrana di contenuto generato con IA.                                                                    |
| `content_filter`                               | booleano           | `true`                          | L'API clienti accetta false. Nel Playground solo gli amministratori possono disattivarlo.                               |

I parametri `n`, `seed`, `stream`, `resolution`, `aspect_ratio`, `image_urls` e `response_format` non sono supportati. I campi non documentati vengono scartati e non attivano queste funzioni. Caricamenti multipart, Base64 e URI data vengono rifiutati.

## Dimensioni di output [#dimensioni-di-output]

La generazione accetta `1K`, `1.5K`, `2K` o dimensioni esatte in pixel `WIDTHxHEIGHT`. Le dimensioni esatte devono totalizzare **921.600–4.624.220 pixel** e avere un rapporto d'aspetto da **1:16 a 16:1**. Per esempio, `2048x1152` è valido. Un rapporto come `16:9` non è un valore di dimensione.

La scomposizione in livelli accetta `auto`, `1K`, `1.5K` o `2K`; questa modalità non supporta dimensioni esatte in pixel. `auto` segue l'input e riserva la tariffa di output superiore. Il modello non offre dimensioni predefinite 3K o 4K.

<span id="reference-images-and-editing" />

## Immagini di riferimento e modifica [#immagini-di-riferimento-e-modifica]

Fornisci URL HTTP(S) pubblici ospitati da te, senza credenziali incorporate. I formati supportati sono JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC e HEIF, fino a 30 MB per immagine e al massimo 36.000.000 pixel totali. AVIF e JP2 non sono supportati. Un URL deve fornire direttamente un'immagine senza accesso o verifica del browser.

```json
{
  "model": "seedream-5-5",
  "prompt": "Change the scene to a snowy winter night. Keep the lighthouse and its composition.",
  "image": "https://your-cdn.example/lighthouse.jpg",
  "size": "2K"
}
```

Per più riferimenti, passa un array di URL e spiega il ruolo di ciascuna immagine nel prompt. Il risultato resta una sola immagine. Gli URL di riferimento negli esempi sono segnaposto: sostituiscili con i tuoi file raggiungibili.

## Scomposizione in livelli e riconoscimento del testo [#scomposizione-in-livelli-e-riconoscimento-del-testo]

```json
{
  "model": "seedream-5-5",
  "image": "https://your-cdn.example/poster.png",
  "size": "1K",
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 4,
    "text_recognition": true
  }
}
```

Il limite include l'immagine di base; `4` significa al massimo quattro immagini restituite, non quattro livelli più una base. Il modello può restituirne meno. Ometti `prompt` per la separazione automatica o indica gli elementi da separare. Un prompt può sopprimere il testo che esclude.

I livelli sono file PNG trasparenti. Ricostruisci l'immagine in ordine `z_index` crescente, con la base a 0. Se viene fornito un riquadro di delimitazione, ridimensiona il livello a quel riquadro prima di posizionarlo: le dimensioni in pixel del file possono differire dalle dimensioni di posizionamento.

Il campo facoltativo `text_recognition` contiene il `text` completo e `lines`. Ogni riga può includere un `bounding_box` e segmenti `runs` con stile. Lo `style` di un segmento può includere `similar_font_family`, `foreground_color` (`#RRGGBB`), `bold`, `italic`, `underline`, `strikethrough`, `shadow` e `translucent`. Sono stime del modello. Scritte artistiche o manoscritte potrebbero non produrre testo; considera il campo facoltativo.

## Risposta completata [#risposta-completata]

```json
{
  "id": "task_example",
  "model": "seedream-5-5",
  "status": "completed",
  "created_at": 1794432000,
  "output": {
    "data": [
      {
        "url": "https://api.wanapi.app/v1/tasks/task_example/artifacts/image-1/content?access=EXAMPLE",
        "size": "1248x832",
        "output_format": "png"
      }
    ]
  }
}
```

Ogni immagine ha `url` e `size`. Altri campi possono includere `output_format`, `background`, `z_index`, `name`, `description`, `bounding_box` e `text_recognition`. `bounding_box.absolute` è `[left, top, right, bottom]` in pixel dell'immagine di base. `bounding_box.normalized` usa le stesse coordinate riportate sulla scala 0–1000. Non presumere che i metadati facoltativi esistano per ogni immagine.

Tratta gli URL delle immagini come link privati di download e salva i file necessari. Un URL con token `access` può essere aperto senza esporre la chiave API dell'account.

## Prezzi [#prezzi]

<Seedream55ModelPricing />

La soglia di pixel di output è **2.610.000 pixel**. Calcola l'addebito così:

```text
lower-band output count × lower-band rate
+ higher-band output count × higher-band rate
+ reference image count × reference rate
```

Ogni riferimento viene addebitato, inclusi il primo e l'immagine sorgente per i livelli. Generazione e livelli usano le stesse tariffe di output. L'invio riserva un output, oppure il limite `max_images` dei livelli, più i riferimenti. Il completamento usa le dimensioni in pixel proprie di ogni immagine restituita e rilascia la prenotazione inutilizzata. L'attività accettata mantiene la propria istantanea dei prezzi anche se cambiano durante l'esecuzione. Le attività fallite vengono rimborsate.

## Errori e nuovi tentativi [#errori-e-nuovi-tentativi]

I parametri non validi vengono rifiutati prima dell'invio. Saldo o quota della chiave insufficienti impediscono la generazione. I controlli di autenticazione e proprietà si applicano sia all'invio sia al polling. Un'attività fallita restituisce `status: "failed"` con un oggetto `error`.

Riprova una lettura dello stato fallita con lo stesso ID attività. **Non ripetere automaticamente un POST di generazione**, nemmeno dopo un timeout: potrebbe essere già stato accettato. Finché il sistema a monte segnala un avanzamento normale, l'attività resta in attesa. Un'attività senza stato normale a monte o consegna riuscita per tre ore consecutive fallisce e viene rimborsata.

Consulta il [tutorial Seedream 5.5](/it/blog/seedream-5-5-api-guide) per un ciclo applicativo che salva e riprende l'ID attività.
