# Guida all’integrazione di Wan API (https://wanapi.app/it/docs/integration) ## Connettiti a Wan API [#connettiti-a-wan-api] Usa `https://api.wanapi.app` come URL di base dell’API. Crea una chiave nelle [impostazioni delle chiavi API](/it/settings/apikeys) e inviala come `Authorization: Bearer YOUR_API_KEY`. Conserva le chiavi sul tuo server. Il playground usa la tua sessione del sito e addebita i costi sul saldo dello stesso account; non richiede di incollare una chiave nel browser. L’accesso richiede un account abilitato con saldo sufficiente. Consulta i [prezzi](/it/pricing) per le tariffe attuali. Ogni modello ha il proprio endpoint e la propria [pagina](/it/models). `GET /v1/models` elenca i modelli disponibili per la tua chiave. Scegliere una risoluzione più alta non cambia automaticamente il modello. | Modello | ID del modello nell’URL | Valori di risoluzione | | ----------------------------------------------- | ----------------------- | ----------------------- | | [Wan 3.0](/it/docs/wan-3-0) | `wan3.0-video` | `480p`, `720p`, `1080p` | | [Wan 3.0 Prime](/it/docs/wan-3-0-prime) | `wan3.0-video-prime` | `480p`, `720p`, `1080p` | | [Wan 3.0 Pro](/it/docs/wan-3-0-pro) | `w3.0-video-pro` | `1080p`, `2k`, `4k` | | [Wan 3.0 Prime Pro](/it/docs/wan-3-0-prime-pro) | `w3.0-video-prime-pro` | `1080p`, `2k`, `4k` | ## Campi della richiesta [#campi-della-richiesta] Tutti e quattro i modelli condividono questi 14 campi nativi. Fornisci un prompt o almeno un input multimediale. I fotogrammi non possono essere combinati con input di riferimento, `file` o `link`; `file` e `link` si escludono a vicenda. | Campo | Tipo | Specifica | | ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------- | | `prompt` | string | Fino a 20.000 caratteri. | | `first_frame` | string | URL HTTP(S) di un’immagine, URI data di un’immagine o Base64. | | `last_frame` | string | URL HTTP(S) di un’immagine, URI data di un’immagine o Base64. | | `reference_images` | string\[] | Fino a 10 immagini, negli stessi formati accettati per i fotogrammi. | | `reference_videos` | string\[] | Fino a 5 URL pubblici di video MP4/MOV; da 1 a 15 secondi per clip e non più di 15 secondi di riferimento in totale. | | `reference_audios` | string\[] | Fino a 5 URL HTTP(S) di file audio. | | `file` | string | URL pubblico di un documento. | | `link` | string | URL pubblico di una pagina web. | | `resolution` | string | Consulta la tabella dei modelli. Valore predefinito: `1080p`. | | `ratio` | string | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Valore predefinito: `adaptive`. | | `duration` | integer | Da 2 a 30 secondi di output, oppure `-1` per la durata automatica. Valore predefinito: `5`. | | `audio` | boolean | Genera l’audio. Valore predefinito: `true`. Disattivarlo non riduce la tariffa. | | `seed` | integer | 0–2147483647. Omettilo per una generazione casuale. | | `prompt_extend` | boolean | Espande il prompt. Valore predefinito: `true`. | Usa URL multimediali stabili e accessibili direttamente, che restino disponibili fino al termine dell’attività. La durata dei video viene verificata tramite letture HTTP Range limitate; i server che ospitano i video devono supportarle ed esporre metadati leggibili sulla durata dei file MP4/MOV. Durante queste verifiche non vengono seguiti i reindirizzamenti. Gli URL di reti private non sono supportati. La somma delle durate dei video di riferimento e dell’output non deve superare 30 secondi. Il playground accetta un corpo JSON della richiesta fino a 32 MiB; per input più grandi, usa URL. ## Controlla lo stato e scarica il video [#controlla-lo-stato-e-scarica-il-video] L’endpoint di invio di ogni modello restituisce un ID pubblico dell’attività. Salvalo prima di proseguire. ```json { "task_info": { "id": "task_EXAMPLE", "status": "pending" } } ``` Usa l’esempio di query nel capitolo del modello corrispondente. Inizia con un intervallo di cinque secondi e aumenta l’attesa dopo errori temporanei. Conserva l’ID del modello insieme all’ID di ogni attività; non interrogarla tramite l’endpoint di un modello diverso. Gli stati nativi sono `pending`, `processing`, `completed` e `failed`. Una risposta completata include `videos`, un array contenente un URL firmato completo di Bunny CDN. ```json { "task_info": { "id": "task_EXAMPLE", "status": "completed" }, "videos": ["https://reapiflexible.b-cdn.net/flexible/v1/expires/2026-11/20261113T06/wanapi-task_EXAMPLE/video.mp4?token=HS256_SIGNATURE&expires=1794550071"] } ``` Usa direttamente l’URL restituito per riprodurre o scaricare il video; questo URL non richiede una chiave API né un header Authorization. I file seguono la politica di conservazione esistente dello spazio di archiviazione. Interrogare un’attività non genera un altro video, non comporta ulteriori addebiti e non prolunga la disponibilità del file. Salva i file da conservare nel tuo spazio di archiviazione. Le query delle attività richiedono la tua chiave API e restituiscono solo le attività del tuo account. ## Responses sincrone e in background [#responses-sincrone-e-in-background] Per i client che usano l’API Responses, `POST /v1/responses` accetta un ID del modello, una stringa `input` e gli stessi campi nativi di generazione. Usa `input` al posto di `prompt`. I campi multimediali nativi, come `reference_images`, restano al livello principale del JSON. ```json { "model": "wan3.0-video", "input": "A blue ball rolls across a white table.", "resolution": "480p", "duration": 2, "background": true } ``` Con `background: true`, salva l’ID della risposta e controlla lo stato tramite `GET /v1/responses/{response_id}`. Senza `background`, la richiesta HTTP attende il completamento. `stream: true` usa eventi inviati dal server (SSE) durante l’attesa. L’output finale dell’assistente contiene un URL firmato del video: trattalo come un link privato che concede l’accesso e non pubblicarlo per errore. Per generazioni lunghe o proxy con timeout restrittivi, sono consigliati l’invio di attività tramite l’API nativa e le Responses in background. Una richiesta sincrona interrotta o scaduta non annulla la generazione. L’attività rimane sul server. Non inviare di nuovo la stessa generazione in automatico. ## Fatturazione e gestione degli errori [#fatturazione-e-gestione-degli-errori] Il prezzo è la tariffa del modello per la risoluzione scelta moltiplicata per i secondi fatturabili. Contano sia i secondi dei video di riferimento sia quelli dell’output; gli input di testo, immagini e audio non aggiungono secondi video. Le richieste a durata fissa senza video di riferimento riservano l’importo per la durata di output richiesta. Le richieste con durata automatica o video di riferimento riservano l’importo per un massimo di 30 secondi fatturabili; al termine, il costo viene calcolato sull’utilizzo misurato e la parte inutilizzata dell’importo riservato viene restituita. Se la generazione fallisce, l’importo riservato viene liberato. Il controllo dello stato non crea un’altra generazione e non comporta un nuovo addebito. * **Parametri non validi:** correggi la richiesta prima di inviarla di nuovo. I campi nativi sconosciuti vengono rifiutati. * **Saldo insufficiente:** aggiungi fondi prima di una nuova richiesta a pagamento. Il limite di una chiave non concede credito all’account. * **Limiti di frequenza o errori temporanei nel controllo dello stato:** riprova solo la query, aumentando progressivamente l’attesa e fissando un tempo massimo. * **Timeout all’invio, interruzione di rete o ID dell’attività mancante:** l’esito potrebbe essere incerto. Non ripetere automaticamente la POST: potresti creare una seconda attività a pagamento. * **Attività fallita:** mostra lo stato di errore separatamente da un controllo dello stato non disponibile. * **Download non riuscito:** riprova a scaricare il risultato dell’attività già completata prima di avviare un’altra generazione. Le richieste di generazione non vengono ritentate automaticamente né trasferite a un altro modello. Non è previsto un contratto pubblico per annullamento, webhook o chiavi di idempotenza. Conserva l’ID dell’attività e contatta l’[assistenza](/it/contact) se occorre verificare l’esito incerto di un invio.