Guida all’integrazione di Wan API

Connettiti a Wan APICopia il link del titolo

Usa https://api.wanapi.app come URL di base dell’API. Crea una chiave nelle impostazioni delle chiavi API 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 per le tariffe attuali. Ogni modello ha il proprio endpoint e la propria pagina.

GET /v1/models elenca i modelli disponibili per la tua chiave. Scegliere una risoluzione più alta non cambia automaticamente il modello.

Campi della richiestaCopia il link del titolo

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.

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 videoCopia il link del titolo

L’endpoint di invio di ogni modello restituisce un ID pubblico dell’attività. Salvalo prima di proseguire.

{
  "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.

{
  "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 backgroundCopia il link del titolo

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.

{
  "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 erroriCopia il link del titolo

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 se occorre verificare l’esito incerto di un invio.