API Wan 3.0 Video Prime

Utilizza wan3.0-video-prime tramite l'API video asincrona APIMaster. L'integrazione attuale fornisce 480P / 720P / 1080P, 2–30 secondi interi e un video per attività. Revisione di parametri e integrazione: 2026-10-26.

Endpoint e autenticazione

Operazione	Metodo e URL
Creazione	POST https://apimaster.ai/v1/videos
Query	GET https://apimaster.ai/v1/videos/{task_id}
Download	GET https://apimaster.ai/v1/videos/{task_id}/content

Usa Authorization: Bearer YOUR_API_KEY per ogni richiesta e Content-Type: application/json quando crei un'attività. Usa una chiave API APIMaster, non una chiave Alibaba Cloud. APIMaster fornisce l'header asincrono upstream; non serve X-DashScope-Async.

L'endpoint di creazione compatibile /videos/generations restituisce un envelope di risposta diverso; gli esempi seguenti usano coerentemente /videos.

Funzionalità attuali delle route

Due integrazioni servono attualmente questo modello: la route nativa Alibaba Cloud e la route GMI. I campi avanzati richiedono la route corrispondente; l'invio di un campo non seleziona quella route. Verifica quale route può accedere la tua chiave API prima di usare esempi specifici per route.

Funzionalità	Nativa Alibaba Cloud	GMI
Testo-to-video, primo frame, primo/ultimo frame, immagini di riferimento	Integrata	Integrata, con campi media diversi
Audio di riferimento	metadata.input.media	audio_url
Documento / pagina web pubblica	I campi media nativi vengono inoltrati; non coperti dal controllo di generazione completata	Non supportata
Video di riferimento, editing, estensione	Bloccati prima dell'invio	Non supportati
Durata automatica -1	Bloccata	Bloccata
Aspect ratio 21:9	Accettato	Rifiutato
Interruttore audio esplicito	generate_audio / audio	Non supportato; omettere questi campi
Disattivazione riscrittura prompt / seed fisso 0	La serializzazione attuale non preserva prompt_extend: false né seed: 0; non fare affidamento su di essi	false e 0 espliciti sono preservati

Un video silenzioso di 5 secondi a 720P sulla route nativa è stato completato, scaricato e decodificato correttamente nel controllo di accettazione del 2026-10-24. Altre combinazioni media sono descritte in base all'adattatore e al contratto ufficiale, anziché essere presentate come combinazioni testate in generazione. La disponibilità delle route e i prezzi possono cambiare; vedi la scheda del modello.

Parametri comuni completi della richiesta

Invia questi campi a livello superiore. Per la massima compatibilità, usa duration, resolution e aspect_ratio espliciti, un prompt non vuoto di massimo 5.000 caratteri, e ometti le opzioni specifiche per route.

Campo	Tipo	Obbligatorio / predefinito	Comportamento APIMaster
model	string	Obbligatorio	Esattamente wan3.0-video-prime
prompt	string	Obbligatorio su entrambe le route	Non vuoto, inclusa la generazione di immagini. GMI valida 1–5.000 caratteri; l'adattatore nativo richiede testo non vuoto. Il limite nativo ufficiale è 20.000; evita di fare affidamento su quel limite superiore tra le route
duration	integer	5	2–30 secondi; niente -1, frazioni o durata automatica
seconds	string	Opzionale	Alias stringa, es. "5"; deve concordare con duration se entrambi forniti
resolution	string	720P	480P, 720P, 1080P; i valori minuscoli a livello superiore vengono normalizzati. Questo predefinito APIMaster differisce dal predefinito nativo ufficiale
aspect_ratio	string	16:9	Valori comuni: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4. 21:9 solo sulla route nativa
ratio	string	Opzionale	Alias di aspect_ratio; usa un solo campo e non inviare valori in conflitto
size	string	Opzionale	Alias di dimensione come 1280x720; si applica la validazione specifica della route. Preferisci resolution e aspect_ratio. GMI richiede che il lato più corto corrisponda al livello di risoluzione; la nativa accetta solo i suoi mapping di dimensione supportati
input_reference	string	Opzionale	URL dell'immagine del primo frame. Usa un URL HTTP(S) pubblicamente scaricabile per compatibilità tra route; non combinare con altri input di primo frame
prompt_extend	boolean	Nativa true; GMI lascia il predefinito del provider se omesso	Riscrittura del prompt. La nativa attualmente non può disattivarla in modo affidabile con false; GMI inoltra un booleano esplicito
watermark	boolean	Predefinito nativo ufficiale false; GMI lascia il predefinito del provider se omesso	Interruttore filigrana
seed	integer	Casuale se omesso	Intervallo fisso portabile: 1–2147483647. La nativa accetta anche -1 per casuale; il 0 nativo viene omesso durante la serializzazione. GMI accetta 0–2147483647 e rifiuta -1. Un seed fisso non garantisce output identico

Gli alias di dimensione nativi sono 832x480, 480x832, 1280x720, 720x1280, 1920x1080 e 1080x1920 per i soliti casi orizzontale/verticale. Alcuni mapping di dimensioni quadrate si riducono a 1:1; altre dimensioni mappate potrebbero comunque fallire la validazione dell'aspect ratio. Non usare size per richiedere dimensioni arbitrarie.

Tabelle dei parametri specifici per route

Campi GMI

Questi sono campi a livello superiore in aggiunta alla tabella comune. L'adattatore GMI rifiuta campi non riconosciuti, inclusi metadata, images, image_urls, audio, generate_audio, video_urls e reference_video.

Campo	Tipo	Obbligatorio / predefinito	Comportamento
negative_prompt	string	Opzionale	Al massimo 500 caratteri
first_frame	string	Opzionale	URL immagine HTTP(S) pubblica; alternativa a input_reference
last_frame	string	Opzionale	URL immagine finale HTTP(S) pubblica; fornisci anche un primo frame
reference_image	string o string[]	Opzionale	1–10 URL di immagini di riferimento HTTP(S) pubbliche; usa un array per più immagini
audio_url	string	Opzionale	URL audio di riferimento HTTP(S) pubblico; soggetto alla validazione media del provider

Usa controlli dei frame o immagini di riferimento in una sola richiesta. Il metadata.input.media nativo non viene tradotto in questi campi su GMI.

Campi nativi Alibaba Cloud

Gli input strutturati nativi appartengono all'interno di metadata. Inviare gli oggetti input o parameters ufficiali direttamente a livello superiore non è il contratto APIMaster. Mantieni sempre il prompt obbligatorio a livello superiore.

Campo	Tipo	Obbligatorio / predefinito	Comportamento
generate_audio	boolean	Predefinito nativo ufficiale true	Indica se l'output contiene una traccia audio; false viene preservato
audio	boolean	Opzionale	Alias di generate_audio; fornisci solo uno
images	string[]	Opzionale	Convertito in voci media reference_image; non sono ordinati come primo/ultimo frame. Non combinare con input_reference
metadata	object	Opzionale	Contiene input e parameters nativi; non può cambiare model
metadata.input	object	Opzionale	Contenitore input nativo
metadata.input.prompt	string	Opzionale	Override prompt nativo; preferisci il solo prompt a livello superiore
metadata.input.media	object[]	Opzionale	Collezione media nativa, con type e url in ogni elemento
metadata.input.media[].type	string	Obbligatorio per elemento	first_frame, last_frame, reference_image, reference_audio, file, link; reference_video è attualmente rifiutato
metadata.input.media[].url	string	Obbligatorio per elemento	Posizione del media; gli URL HTTP(S) pubblici sono raccomandati. Gli URL temporanei OSS ufficiali richiedono un contesto di upload upstream separatamente valido; APIMaster non fornisce quel contesto di upload
metadata.parameters	object	Opzionale	Contenitore parametri nativo; non deve essere null
metadata.parameters.resolution	string	720P	Maiuscolo 480P, 720P, 1080P
metadata.parameters.ratio	string	16:9	Aspect ratio nativi inclusi adaptive e 21:9
metadata.parameters.duration	integer	5	2–30; niente -1
metadata.parameters.audio	boolean	Predefinito nativo ufficiale true	Interruttore audio output
metadata.parameters.prompt_extend	boolean	true	Deve rimanere true per file / link; false esplicito ha la limitazione di serializzazione sopra
metadata.parameters.watermark	boolean	Predefinito nativo ufficiale false	Interruttore filigrana
metadata.parameters.seed	integer	Casuale	-1 o 0–2147483647; 0 ha la limitazione di serializzazione sopra

Le opzioni native a livello superiore sovrascrivono i corrispondenti parametri metadata. input_reference a livello superiore sostituisce l'array media nativo; images aggiunge voci di immagini di riferimento quando input_reference è assente. Usa uno stile di input e uno stile di parametri per evitare sovrascritture accidentali. Non usare i campi legacy img_url, first_frame_url, last_frame_url o audio_url all'interno di input nativo; l'adattatore rifiuta quei campi media legacy per Wan 3.0.

Vincoli sui media

Le regole media native ufficiali seguenti spiegano anche la validazione lato provider; un adattatore che accetta un URL non dimostra che il media sia valido.

Media	Limiti / note di integrazione
Primo / ultimo frame	Al massimo uno ciascuno; un ultimo frame richiede un primo frame. Non mescolare i controlli dei frame con reference_image
Immagini di riferimento	Al massimo 10; JPEG/JPG, PNG senza trasparenza, BMP o WEBP; ogni lato 240–8.000 px, aspect ratio al massimo 8:1, al massimo 20 MB per immagine
Audio di riferimento	Nativo: al massimo 5, WAV/MP3, ciascuno 1–15 secondi, combinati al massimo 15 secondi, al massimo 15 MB per file. GMI espone un solo audio_url
File / pagina web	Solo nativo: al massimo un file o una pagina leggibile pubblicamente; non combinare file e link. Formati file ufficiali: DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS, MD; al massimo 100 MB, con limite di 50 pagine per i formati impaginabili applicabili. Mantieni prompt_extend: true
Video di riferimento	Ufficialmente disponibile, ma attualmente bloccato dalla validazione di fatturazione nativa APIMaster; non esposto su GMI. Non usare qui esempi di editing video o estensione dall'API ufficiale

Il tetto combinato media nativo ufficiale è di 20 elementi; i limiti individuali e combinati restano validi. Gli URL di dati Base64 delle immagini fanno parte del formato input nativo ufficiale, ma non sono accettati dalla validazione URL GMI. Preferisci URL HTTP(S) scaricabili tra le route.

Esempi

Testo-to-video, campi comuni

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'

Primo frame, campi comuni

{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}

GMI primo / ultimo frame

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}

Nativo primo / ultimo frame e output silenzioso

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}

Nativo immagine di riferimento e audio

{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood of audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}

Sostituisci gli URL media di esempio con file pubblici reali. Gli esempi specifici per route richiedono la route corrispondente e restano soggetti ai controlli di combinazione upstream.

Risposta, polling e download

La creazione restituisce un ID attività APIMaster, ad esempio:

{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}

Campo	Significato
id / task_id	Identificatore attività APIMaster, non un identificatore attività upstream
status	queued, in_progress, completed, failed
progress	Avanzamento riportato; non è una garanzia di completamento
error.code / error.message	Dettagli dell'errore quando applicabile
metadata.url	Indirizzo del contenuto autenticato quando restituito al completamento

Esegui polling ogni 10–20 secondi con la stessa chiave API fino a uno stato terminale; il successo della creazione significa solo accettazione. La generazione può richiedere diversi minuti. Fai polling di un'attività accettata invece di creare ripetutamente attività a pagamento.

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o wan-prime.mp4

Scarica e salva il video completato tempestivamente; gli URL dei risultati upstream possono scadere. Il polling ripetuto non crea un altro addebito di generazione.

Fatturazione ed errori comuni

La fatturazione avviene al secondo alla risoluzione richiesta, con prezzi per route/account mostrati nella scheda del modello. L'invio riserva il costo stimato. Il completamento nativo usa la durata fatturabile restituita e il prezzo di invio congelato; GMI segue il contratto di durata prenotata. Le attività fallite rilasciano/rimborsano la loro prenotazione di generazione. Audio disattivato non implica un livello più economico. Usa il registro di utilizzo per l'importo finale.

Errore / sintomo	Azione
duration must be an integer from 2 to 30	Usa un intero esplicito; -1 non è integrato
unsupported Wan request field ...	Rimuovi un campo non supportato da GMI o verifica l'accesso alla route nativa corrispondente
unsupported aspect ratio	Usa un rapporto comune; 21:9 richiede il routing nativo
reference video requires an input-duration quote	Rimuovi il video di riferimento; questa funzionalità è attualmente bloccata
prompt is required / errore di recupero media	Aggiungi testo a livello superiore; usa media pubblicamente scaricabili e validi
prompt_extend: false o seed: 0 non ha effetto sulla nativa	Limitazione di serializzazione attuale; usa un seed positivo e non dipendere dalla disattivazione della riscrittura

Fonti: informazioni ufficiali sul modello, riferimento API nativa ufficiale e guida all'uso ufficiale. La funzionalità ufficiale non significa che lo stesso campo sia esposto su ogni route APIMaster.