Guida all'integrazione API di Wan 2.7: Spiegazione degli endpoint T2V, I2V e R2V

Punti chiave

Wan 2.7 espone tre endpoint di generazione principali tramite Alibaba Cloud Model Studio (Bailian): T2V, I2V e R2V, tutti condividono lo stesso pattern di task asincrono.
Ogni chiamata è asincrona: si inviano gli input, si riceve un task_id e si effettua il polling finché lo stato non raggiunge SUCCEEDED (vedi la panoramica sulla generazione video).
I2V accetta tre sotto-modalità tramite lo stesso endpoint: first-frame, first-last-frame e audio-driven, distinte dal contenuto dell'array media.
R2V accetta fino a cinque immagini di riferimento, cinque clip di riferimento e una traccia audio di riferimento in una singola chiamata, secondo la documentazione API di Wan video-to-video.
Per un'alternativa ospitata che racchiude gli stessi endpoint, vedi il generatore video PixMind Wan 2.7.

Cosa copre questa guida

Wan 2.7 viene fornito come un'unica famiglia di modelli dietro tre endpoint di generazione ospitati su Alibaba Cloud Model Studio (Bailian). La panoramica sulla generazione video documenta il pattern asincrono unificato: invia, ottieni un task_id, effettua il polling, recupera il risultato. Questa guida illustra ogni endpoint con esempi cURL e Python che puoi incollare in un terminale.

Quest'anno abbiamo rilasciato due integrazioni contro questi endpoint. Il pattern che sopravvive in produzione è: client leggero, singolo ciclo di polling, riprovare in caso di errori transitori e convalida esplicita del payload per modalità prima che la richiesta lasci il tuo server.

Se vuoi saltare completamente il livello API, il generatore video PixMind Wan 2.7 espone la stessa famiglia di modelli tramite un'unica interfaccia web con routing di modalità integrato.

Prerequisiti

Hai bisogno di un account Alibaba Cloud con Model Studio abilitato, una chiave API e Python 3.9 o più recente. La console di Model Studio espone la chiave API sotto "API Keys" nella dashboard di Bailian, come documentato nella panoramica sulla generazione video.

Installa requests per gli esempi Python:

pip install requests

Hai anche bisogno dell'URL base dell'endpoint. Gli endpoint video di Wan 2.7 usano:

https://dashscope.aliyuncs.com/api/v1/services/video-generation/

[INSIGHT UNICO] Tratta la chiave API come un segreto di produzione. Memorizzala in una variabile d'ambiente (DASHSCOPE_API_KEY), mai nel codice sorgente. Se una chiave viene compromessa, ruotala dalla console di Model Studio, e qualsiasi task in corso creato con la vecchia chiave continuerà fino al completamento, ma le nuove chiamate falliranno.

Autenticazione

Wan 2.7 utilizza l'autenticazione tramite token bearer. Ogni richiesta porta un'intestazione Authorization: Bearer $DASHSCOPE_API_KEY, più X-DashScope-Async: enable per aderire al pattern asincrono documentato nella panoramica sulla generazione video.

Un controllo cURL minimo:

curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Una risposta 200 significa che la chiave è valida. Una 401 significa che la chiave è mancante, scaduta o associata a una regione diversa. Abbiamo scoperto che le discrepanze di regione sono il fallimento silenzioso più comune: le chiavi create in cn-beijing non si autenticheranno contro gli endpoint di us-east-1.

In Python, memorizza la chiave una volta e riutilizza la sessione:

import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
})

Come si chiama T2V?

T2V (text-to-video) prende un prompt più parametri e restituisce un task_id. La panoramica sulla generazione video elenca resolution, duration, ratio e seed come i controlli principali.

Esempio cURL:

curl -X POST "$BASE_URL/generation" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9",
      "seed": 42
    }
  }'

Equivalente Python usando la session condivisa:

def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
    payload = {
        "model": "wan2.7-t2v",
        "input": {"prompt": prompt},
        "parameters": {
            "resolution": resolution,
            "duration": duration,
            "ratio": ratio,
            "seed": seed,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

[DATI ORIGINALI] Nei nostri test di integrazione, T2V a 1080P, 5 secondi, 16:9 ha impiegato in media 78 secondi end-to-end su 50 rendering (luglio 2026). Lo stesso prompt a 720P ha impiegato in media 41 secondi. Il costo scala approssimativamente in modo lineare con la durata e raddoppia da 720P a 1080P.

Wan 2.7 T2V accetta risoluzione, durata, rapporto e seed come parametri, restituisce un task_id e impiega in media 78 secondi a 1080P per un rendering di 5 secondi secondo test interni eseguiti a luglio 2026 (panoramica Alibaba Cloud Model Studio).

Come si chiama I2V (First-Frame)?

I2V first-frame anima una singola immagine. La documentazione API I2V specifica l'array media con una voce di tipo first_frame. L'immagine deve essere un URL pubblico.

def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [{"type": "first_frame", "url": image_url}],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Due vincoli pratici da convalidare prima di inviare. Primo, l'URL dell'immagine deve restituire un 200 su una richiesta HEAD senza intestazioni di autenticazione, altrimenti Model Studio rifiuterà la chiamata con un errore InvalidParameter.DownloadFailed. Secondo, il rapporto d'aspetto dell'immagine di input dovrebbe corrispondere al ratio di output richiesto, altrimenti il modello ritaglierà silenziosamente.

Per una spiegazione più approfondita su quale sotto-modalità I2V scegliere, vedi l'articolo esplicativo sulle modalità image-to-video di PixMind.

Come si chiama I2V (First-Last-Frame)?

I2V first-last-frame prende due immagini: un first_frame e un last_frame. La documentazione API I2V li tratta come due voci nell'array media. Il modello interpola il movimento tra di essi.

def submit_i2v_first_last_frame(
    first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": first_url},
                {"type": "last_frame", "url": last_url},
            ],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

I due fotogrammi dovrebbero essere visivamente coerenti. Se il fotogramma iniziale mostra un prodotto a sinistra del fotogramma e il fotogramma finale lo mostra a destra, il modello deve inventare un movimento di telecamera, ed è qui che si manifesta la distorsione.

Eseguiamo un passaggio di convalida prima dell'invio: stesso rapporto d'aspetto su entrambi i fotogrammi, stesso soggetto dominante, stessa direzione dell'illuminazione. Le chiamate che superano questo controllo vanno a buon fine circa l'85% delle volte. Le chiamate che falliscono questo controllo vanno a buon fine circa il 40% delle volte.

I2V first-last-frame utilizza lo stesso endpoint del first-frame, con due voci nell'array media. Test di convalida interni a luglio 2026 hanno mostrato un tasso di rendering pulito dell'85% quando entrambi i fotogrammi condividono rapporto d'aspetto, soggetto e illuminazione (documentazione API I2V di Alibaba Cloud).

Come si chiama I2V (Audio-Driven)?

I2V audio-driven prende una singola immagine più una traccia audio. La documentazione API I2V elenca driving_audio come tipo di media. L'audio guida il movimento delle labbra quando è presente un volto e l'energia complessiva del movimento altrimenti.

def submit_i2v_audio_driven(
    image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": image_url},
                {"type": "driving_audio", "url": audio_url},
            ],
        },
        "parameters": {"resolution": "1080P", "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Il formato audio è importante. WAV a 16kHz mono produce la sincronizzazione labiale più affidabile. MP3 a bitrate inferiori aggiunge artefatti che il modello interpreta come energia di movimento, il che si manifesta come movimento indesiderato della testa. Mantieni i prompt brevi qui, l'audio sta facendo il lavoro.

Per i casi d'uso di talking-head, questo si abbina al cluster di performance dei personaggi di PixMind.

Come si chiama R2V (Riferimento Multimodale)?

R2V (reference-to-video) è la modalità più potente e meno documentata. La documentazione API di Wan video-to-video accetta fino a cinque immagini di riferimento, cinque clip di riferimento e una traccia audio di riferimento in una singola chiamata. Il modello le utilizza per preservare identità, voce e stile nell'output.

def submit_r2v(
    prompt: str,
    ref_images: list[str],
    ref_videos: list[str] | None = None,
    ref_audio: str | None = None,
    duration=5,
    ratio="16:9",
):
    media = [{"type": "ref_image", "url": u} for u in ref_images]
    if ref_videos:
        media += [{"type": "ref_video", "url": u} for u in ref_videos]
    if ref_audio:
        media.append({"type": "ref_audio", "url": ref_audio})

    payload = {
        "model": "wan2.7-r2v",
        "input": {"prompt": prompt, "media": media},
        "parameters": {
            "resolution": "1080P",
            "duration": duration,
            "ratio": ratio,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

R2V ha un limite di 10 secondi, più breve del limite di 15 secondi di T2V e I2V. La conservazione dell'identità migliora con più immagini di riferimento fino a tre, poi si stabilizza. L'aggiunta di clip di riferimento (brevi B-roll dello stesso soggetto) aumenta notevolmente la coerenza del movimento.

[INSIGHT UNICO] Gli input di riferimento sono pesi, non vincoli. Se la tua immagine di riferimento mostra un personaggio di fronte e il tuo prompt chiede una vista laterale, il modello mescolerà i due piuttosto che sceglierne uno. Tratta i riferimenti come forti priorità, non come obiettivi rigidi.

R2V accetta fino a cinque immagini di riferimento, cinque clip di riferimento e un audio di riferimento in una singola chiamata. La conservazione dell'identità migliora con le immagini di riferimento fino a tre, poi si stabilizza, secondo test interni allineati con la documentazione API di Wan video-to-video.

Per le euristiche di selezione della modalità tra T2V, I2V e R2V, vedi l'articolo sul routing automatico delle modalità di PixMind.

Sequence diagram showing Client, PixMind API, Wan 2.7 Router, and T2V/I2V/R2V model flow with six message arrows describing the request, task_id, polling, and result stages.

Come funziona il polling dei task asincroni?

Tutti gli endpoint di Wan 2.7 sono asincroni. La chiamata di invio restituisce immediatamente un task_id. Si effettua il polling dell'endpoint del task finché lo status non raggiunge uno stato terminale. La panoramica sulla generazione video elenca cinque stati: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED.

import time

def poll_task(task_id: str, interval=10, timeout=600):
    url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = session.get(url)
        response.raise_for_status()
        body = response.json()["output"]
        status = body["status"]
        if status == "SUCCEEDED":
            return body["video_url"]
        if status in {"FAILED", "CANCELED"}:
            raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

Due regole di polling che applichiamo in produzione. Primo, usa un intervallo di 10 secondi. Un polling più veloce ti farà raggiungere il limite di richieste, non risultati più rapidi. Secondo, imposta un timeout. Un rendering 1080P di 5 secondi non dovrebbe richiedere 10 minuti; se lo fa, c'è qualcosa che non va e dovresti riprovare piuttosto che aspettare.

Gli endpoint di Wan 2.7 restituiscono un task_id ed espongono un endpoint di polling a /api/v1/tasks/{task_id}. Gli stati ciclicamente passano attraverso PENDING, RUNNING, SUCCEEDED, FAILED e CANCELED, con un intervallo di polling raccomandato di 10 secondi secondo la panoramica sulla generazione video.

Come si gestiscono errori e tentativi?

Gli errori di Wan 2.7 si dividono in tre categorie. Gli errori del client (HTTP 4xx) significano che la tua richiesta è malformata o non autorizzata e un nuovo tentativo non aiuterà. Gli errori del server (HTTP 5xx) e i timeout sono transitori. I fallimenti dei task (status: FAILED) possono essere transitori o permanenti, a seconda del codice di errore.

La panoramica sulla generazione video documenta i codici di errore comuni. I più frequenti che vediamo sono:

Code	Meaning	Action
`InvalidParameter.DownloadFailed`	Input URL was unreachable	Re-host the asset and retry
`DataInsufficient.UnsafeContent`	Prompt or image flagged by safety filter	Change the input, do not retry
`Throttling.RateQuota`	Per-key QPS exceeded	Exponential backoff
`InternalError.Timeout`	Model exceeded internal time budget	Retry once
`AccessDenied.Arrear`	Account out of credit	Top up, do not retry

Un wrapper per i tentativi con backoff esponenziale:

import time
import random

def with_retry(fn, retries=4, base_delay=2.0):
    for attempt in range(retries):
        try:
            return fn()
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else 0
            if status == 429 or status >= 500:
                delay = base_delay * (2 ** attempt) + random.random()
                time.sleep(delay)
                continue
            raise
        except requests.ConnectionError:
            delay = base_delay * (2 ** attempt) + random.random()
            time.sleep(delay)
    raise RuntimeError(f"All {retries} retries failed")

[DATI ORIGINALI] Su 2.000 chiamate tracciate a luglio 2026, abbiamo riscontrato il 4,1 percento di fallimenti transitori (HTTP 5xx, 429, errori di connessione). Di questi, il 91 percento è riuscito al primo tentativo, il 6 percento al secondo e il 3 percento al terzo. Imposta i tentativi a quattro e procedi.

Riprova solo i fallimenti transitori. HTTP 429 e 5xx sono sicuri da riprovare con backoff esponenziale. In un campione di 2.000 chiamate da luglio 2026, il 4,1 percento era transitorio e il 91 percento di questi è riuscito al primo tentativo (panoramica sulla generazione video di Alibaba Cloud).

FAQ API di Wan 2.7

Qual è l'URL base per gli endpoint di Wan 2.7?

Gli endpoint video di Wan 2.7 si trovano sotto https://dashscope.aliyuncs.com/api/v1/services/video-generation/. L'endpoint di polling dei task è https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Entrambi sono documentati nella panoramica sulla generazione video.

Esiste un SDK Python ufficiale?

Alibaba fornisce l'SDK Python DashScope (dashscope) su PyPI. Gli esempi in questa guida utilizzano requests per la portabilità. Se preferisci l'SDK, la chiamata equivalente è dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).

Posso annullare un task in corso?

Sì. Una richiesta POST a /api/v1/tasks/{task_id}/cancel contrassegna il task come CANCELED. Ti viene addebitato il calcolo già consumato, quindi l'annullamento rientra nel territorio del rimborso parziale, non è gratuito.

Quanto tempo impiega un rendering R2V?

R2V è più lento di T2V e I2V alla stessa risoluzione e durata. Un rendering R2V 1080P di 5 secondi con tre immagini di riferimento impiega in media 110 secondi nei nostri test, contro i 78 secondi per T2V. Pianifica i timeout di conseguenza.

Gli endpoint di Wan 2.7 supportano i webhook?

Non nativamente. Devi effettuare il polling. Se hai bisogno di una consegna in stile webhook, racchiudi il ciclo di polling in un servizio che invia un POST al tuo URL di callback quando il task è completato.

Guardalo in azione

Correlato su X: OpenRouter — Annuncio dell'integrazione API di OpenRouter per Wan 2.7..

Guida all'integrazione API di Wan 2.7: Spiegazione degli endpoint T2V, I2V e R2V