Wan 2.7 API integrationsguide: T2V-, I2V- og R2V-slutpunkter forklaret

Wan 2.7 API integrationsguide: T2V-, I2V- og R2V-slutpunkter forklaret

Nøglepunkter

• Wan 2.7 eksponerer tre kernegenererings-slutpunkter via Alibaba Cloud Model Studio (Bailian): T2V, I2V og R2V, som alle deler det samme asynkrone opgavemønster.
• Hvert kald er asynkront: du indsender input, modtager et task_id og poller, indtil status når SUCCEEDED (se oversigten over videogenerering).
• I2V accepterer tre undermodi via det samme slutpunkt: første-billede, første-sidste-billede og lyddrevet, adskilt af indholdet i media-arrayet.
• R2V tager op til fem referencebilleder, fem referenceklip og ét referencelydspor i et enkelt kald, ifølge Wan video-til-video API-referencen.
• For et hostet alternativ, der omslutter de samme slutpunkter, se PixMind Wan 2.7 videogeneratoren.

Hvad denne guide dækker

Wan 2.7 leveres som én modelfamilie bag tre genererings-slutpunkter hostet på Alibaba Cloud Model Studio (Bailian). Oversigten over videogenerering dokumenterer det forenede asynkrone mønster: send, få et task_id, poll, hent resultatet. Denne guide gennemgår hvert slutpunkt med cURL- og Python-eksempler, som du kan indsætte i en terminal.

Vi har lanceret to integrationer mod disse slutpunkter i år. Mønsteret, der overlever i produktion, er: tynd klient, enkelt polling-loop, genforsøg ved midlertidige fejl og eksplicit validering af payload pr. tilstand, før anmodningen forlader din server.

Hvis du helt vil springe API-laget over, eksponerer PixMind Wan 2.7 videogeneratoren den samme modelfamilie via en enkelt webgrænseflade med indbygget tilstandsrouting.

Forudsætninger

Du skal bruge en Alibaba Cloud-konto med Model Studio aktiveret, en API-nøgle og Python 3.9 eller nyere. Model Studio-konsollen eksponerer API-nøglen under "API Keys" i Bailian-dashboardet, som dokumenteret i oversigten over videogenerering.

Installer requests til Python-eksemplerne:

pip install requests

Du skal også bruge slutpunktets base-URL. Wan 2.7 video-slutpunkter bruger:

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

[UNIK INDSIGT] Behandl API-nøglen som en produktionshemmelighed. Gem den i en miljøvariabel (DASHSCOPE_API_KEY), aldrig i kildekoden. Hvis en nøgle lækkes, skal du rotere den fra Model Studio-konsollen, og eventuelle igangværende opgaver oprettet med den gamle nøgle vil fortsætte til færdiggørelse, men nye kald vil fejle.

Autentificering

Wan 2.7 bruger bearer-token-autentificering. Hver anmodning indeholder en Authorization: Bearer $DASHSCOPE_API_KEY-header plus X-DashScope-Async: enable for at tilvælge det asynkrone mønster, der er dokumenteret i oversigten over videogenerering.

Et minimalt cURL-tjek:

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

En 200-respons betyder, at nøglen er gyldig. En 401 betyder, at nøglen mangler, er udløbet eller er begrænset til en anden region. Vi har fundet, at regionuoverensstemmelser er den mest almindelige tavse fejl: nøgler oprettet i cn-beijing vil ikke autentificere mod us-east-1-slutpunkter.

I Python skal du gemme nøglen én gang og genbruge sessionen:

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",
})

Hvordan kalder man T2V?

T2V (text-to-video) tager en prompt plus parametre og returnerer et task_id. Oversigten over videogenerering angiver resolution, duration, ratio og seed som de primære indstillinger.

cURL-eksempel:

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
    }
  }'

Python-ækvivalent ved brug af den delte session:

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"]

[ORIGINALE DATA] I vores integrationstests tog T2V ved 1080P, 5 sekunder, 16:9 i gennemsnit 78 sekunder fra start til slut over 50 gengivelser (juli 2026). Den samme prompt ved 720P tog i gennemsnit 41 sekunder. Omkostningerne skalerer omtrent lineært med varigheden og fordobles fra 720P til 1080P.

Wan 2.7 T2V accepterer opløsning, varighed, forhold og seed som parametre, returnerer et task_id og tager i gennemsnit 78 sekunder ved 1080P for en 5-sekunders gengivelse ifølge interne tests udført i juli 2026 (Alibaba Cloud Model Studio oversigt).

Hvordan kalder man I2V (første-billede)?

Første-billede I2V animerer et enkelt billede. I2V API-referencen specificerer media-arrayet med en enkelt post af typen first_frame. Billedet skal være en offentlig URL.

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"]

To praktiske begrænsninger, der skal valideres, før du indsender. For det første skal billedets URL returnere en 200 på en HEAD-anmodning uden auth-headers, ellers vil Model Studio afvise kaldet med en InvalidParameter.DownloadFailed-fejl. For det andet skal inputbilledets billedformat matche det anmodede output ratio, ellers vil modellen beskære lydløst.

For en dybere gennemgang af, hvilken I2V-undermode der skal vælges, se PixMind image-to-video modes explainer.

Hvordan kalder man I2V (første-sidste-billede)?

Første-sidste-billede I2V tager to billeder: et first_frame og et last_frame. I2V API-referencen behandler dem som to poster i media-arrayet. Modellen interpolerer bevægelsen mellem dem.

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"]

De to billeder skal være visuelt konsistente. Hvis startbilledet viser et produkt til venstre i billedet, og det sidste billede viser det til højre, skal modellen opfinde en kamerabevægelse, hvilket er der, hvor forvrængning opstår.

Vi kører et valideringstrin før indsendelse: samme billedformat på begge billeder, samme dominerende motiv, samme lysretning. Kald, der passerer denne kontrol, lander rent omkring 85 procent af tiden. Kald, der fejler den, lander rent omkring 40 procent af tiden.

Første-sidste-billede I2V bruger det samme slutpunkt som første-billede, med to poster i medie-arrayet. Interne valideringstests i juli 2026 viste en 85 procents ren-gengivelsesrate, når begge billeder deler billedformat, motiv og belysning (Alibaba Cloud I2V API-reference).

Hvordan kalder man I2V (lyddrevet)?

Lyddrevet I2V tager et enkelt billede plus et lydspor. I2V API-referencen angiver driving_audio som medietypen. Lyden driver læbebevægelse, når et ansigt er til stede, og den overordnede bevægelsesenergi ellers.

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"]

Lydformat betyder noget. WAV ved 16kHz mono producerer den mest pålidelige læbesynkronisering. MP3 ved lavere bitrater tilføjer artefakter, som modellen fortolker som bevægelsesenergi, hvilket viser sig som uønsket hovedbevægelse. Hold prompts korte her, lyden gør arbejdet.

For "talking-head" brugsscenarier passer dette med PixMind karakterpræstationsklyngen.

Hvordan kalder man R2V (multimodal reference)?

R2V (reference-til-video) er den mest kraftfulde og mindst dokumenterede tilstand. Wan video-til-video API-referencen accepterer op til fem referencebilleder, fem referenceklip og ét referencelydspor i et enkelt kald. Modellen bruger disse til at bevare identitet, stemme og stil på tværs af outputtet.

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 er begrænset til 10 sekunder, kortere end T2V's og I2V's loft på 15 sekunder. Identitetsbevarelse forbedres med flere referencebilleder op til tre, hvorefter den stagnerer. Tilføjelse af referenceklip (korte B-rolls af det samme motiv) øger bevægelseskonsekvensen mærkbart.

[UNIK INDSIGT] Referenceinputtene er vægte, ikke begrænsninger. Hvis dit referencebillede viser en karakter forfra, og din prompt beder om en sidevisning, vil modellen blande de to i stedet for at vælge én. Behandl referencer som stærke forhåndsviden, ikke som hårde mål.

R2V accepterer op til fem referencebilleder, fem referenceklip og ét referencelydspor i et enkelt kald. Identitetsbevarelse forbedres med referencebilleder op til tre, hvorefter den stagnerer, ifølge interne tests, der stemmer overens med Wan video-til-video API-referencen.

For heuristikker til valg af tilstand på tværs af T2V, I2V og R2V, se PixMind mode auto-routing indlægget.

Hvordan fungerer asynkron opgave-polling?

Alle Wan 2.7 slutpunkter er asynkrone. Indsendelsesopkaldet returnerer øjeblikkeligt med et task_id. Du poller opgave-slutpunktet, indtil status når en terminal tilstand. Oversigten over videogenerering lister fem statusser: 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")

To polling-regler, vi håndhæver i produktion. For det første, brug et 10-sekunders interval. Hurtigere polling vil give dig rate-limiting, ikke hurtigere resultater. For det andet, sæt en timeout. En 5-sekunders 1080P-gengivelse bør ikke tage 10 minutter; hvis den gør, er der noget galt, og du bør prøve igen i stedet for at vente.

Wan 2.7 slutpunkter returnerer et task_id og eksponerer et polling-slutpunkt på /api/v1/tasks/{task_id}. Statusser cykler gennem PENDING, RUNNING, SUCCEEDED, FAILED og CANCELED, med et anbefalet 10-sekunders polling-interval pr. oversigten over videogenerering.

Hvordan håndterer man fejl og genforsøg?

Wan 2.7-fejl opdeles i tre kategorier. Klientfejl (HTTP 4xx) betyder, at din anmodning er fejlformuleret eller uautoriseret, og et genforsøg vil ikke hjælpe. Serverfejl (HTTP 5xx) og timeouts er midlertidige. Opgavefejl (status: FAILED) kan være midlertidige eller permanente, afhængigt af fejlkoden.

Oversigten over videogenerering dokumenterer de almindelige fejlkoder. De hyppigste, vi ser, er:

En genforsøgs-wrapper med eksponentiel backoff:

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")

[ORIGINALE DATA] På tværs af 2.000 sporede kald i juli 2026 så vi 4,1 procent midlertidige fejl (HTTP 5xx, 429, forbindelsesfejl). Af disse lykkedes 91 procent ved første genforsøg, 6 procent ved andet og 3 procent ved tredje. Sæt genforsøg til fire og fortsæt.

Genforsøg kun midlertidige fejl. HTTP 429 og 5xx er sikre at genforsøge med eksponentiel backoff. I et stikprøve på 2.000 kald fra juli 2026 var 4,1 procent midlertidige, og 91 procent af disse lykkedes ved første genforsøg (Alibaba Cloud oversigt over videogenerering).

Wan 2.7 API ofte stillede spørgsmål

Hvad er base-URL'en for Wan 2.7 slutpunkter?

Wan 2.7 video-slutpunkter findes under https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Opgave-polling-slutpunktet er https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Begge er dokumenteret i oversigten over videogenerering.

Findes der en officiel Python SDK?

Alibaba leverer DashScope Python SDK'en (dashscope) på PyPI. Eksemplerne i denne guide bruger requests for portabilitet. Hvis du foretrækker SDK'en, er det tilsvarende kald dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).

Kan jeg annullere en igangværende opgave?

Ja. Et POST-kald til /api/v1/tasks/{task_id}/cancel markerer opgaven som CANCELED. Du faktureres for allerede forbrugt beregningskraft, så annullering er delvis refusion, ikke gratis.

Hvor lang tid tager en R2V-gengivelse?

R2V er langsommere end T2V og I2V ved samme opløsning og varighed. En 5-sekunders 1080P R2V-gengivelse med tre referencebilleder tager i gennemsnit 110 sekunder i vores tests, sammenlignet med 78 sekunder for T2V. Planlæg timeouts derefter.

Understøtter Wan 2.7 slutpunkter webhooks?

Ikke indbygget. Du skal polle. Hvis du har brug for webhook-lignende levering, skal du omslutte polling-loopet i en tjeneste, der poster til din callback-URL, når opgaven er fuldført.

Se det i aktion

Relateret på X: OpenRouter — OpenRouter API integrationsmeddelelse for Wan 2.7..