Wan 2.7 API-integrasjonsguide: T2V-, I2V- og R2V-endepunkter forklart

Wan 2.7 API-integrasjonsguide: T2V-, I2V- og R2V-endepunkter forklart

Nøkkelpunkter

• Wan 2.7 eksponerer tre kjernegenererings-endepunkter gjennom Alibaba Cloud Model Studio (Bailian): T2V, I2V og R2V, som alle deler det samme asynkrone oppgavemønsteret.
• Hvert kall er asynkront: du sender inn input, mottar en task_id, og poller til statusen når SUCCEEDED (se oversikten over videogenerering).
• I2V aksepterer tre undermoduser gjennom det samme endepunktet: første-ramme, første-siste-ramme og lyddrevet, skilt av innholdet i media-arrayet.
• R2V tar opptil fem referansebilder, fem referanseklipp og ett referanselydspor i et enkelt kall, i henhold til Wan video-til-video API-referansen.
• For et hostet alternativ som omslutter de samme endepunktene, se PixMind Wan 2.7 videogenerator.

Hva denne guiden dekker

Wan 2.7 leveres som én modellfamilie bak tre genererings-endepunkter hostet på Alibaba Cloud Model Studio (Bailian). Oversikten over videogenerering dokumenterer det enhetlige asynkrone mønsteret: send inn, få en task_id, poll, hent resultatet. Denne guiden går gjennom hvert endepunkt med cURL- og Python-eksempler du kan lime inn i en terminal.

Vi har levert to integrasjoner mot disse endepunktene i år. Mønsteret som overlever i produksjon er: tynn klient, enkelt polling-loop, gjenta ved midlertidige feil, og eksplisitt validering av nyttelast per modus før forespørselen forlater serveren din.

Hvis du vil hoppe over API-laget helt, eksponerer PixMind Wan 2.7 videogenerator den samme modellfamilien gjennom en enkelt webflate med innebygd modus-ruting.

Forutsetninger

Du trenger en Alibaba Cloud-konto med Model Studio aktivert, en API-nøkkel og Python 3.9 eller nyere. Model Studio-konsollen eksponerer API-nøkkelen under "API Keys" i Bailian-dashbordet, som dokumentert i oversikten over videogenerering.

Installer requests for Python-eksemplene:

pip install requests

Du trenger også endepunktets base-URL. Wan 2.7 video-endepunkter bruker:

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

[UNIKE INNSIKTER] Behandle API-nøkkelen som en produksjonshemmelighet. Lagre den i en miljøvariabel (DASHSCOPE_API_KEY), aldri i kildekoden. Hvis en nøkkel lekker, roter den fra Model Studio-konsollen, og eventuelle pågående oppgaver opprettet med den gamle nøkkelen vil fortsette til fullførelse, men nye kall vil mislykkes.

Autentisering

Wan 2.7 bruker bearer-token autentisering. Hver forespørsel bærer en Authorization: Bearer $DASHSCOPE_API_KEY header, pluss X-DashScope-Async: enable for å velge det asynkrone mønsteret dokumentert i oversikten over videogenerering.

En minimal cURL-sjekk:

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

En 200-respons betyr at nøkkelen er gyldig. En 401 betyr at nøkkelen mangler, er utløpt eller er begrenset til en annen region. Vi har funnet ut at region-uoverensstemmelser er den vanligste stille feilen: nøkler opprettet i cn-beijing vil ikke autentisere mot us-east-1 endepunkter.

I Python, lagre nøkkelen én gang og gjenbruk sesjonen:

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 kaller du T2V?

T2V (tekst-til-video) tar en prompt pluss parametere og returnerer en task_id. Oversikten over videogenerering lister resolution, duration, ratio og seed som de primære justeringsmulighetene.

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-ekvivalent ved bruk av 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 våre integrasjonstester, T2V ved 1080P, 5 sekunder, 16:9, hadde et gjennomsnitt på 78 sekunder ende-til-ende over 50 gjengivelser (juli 2026). Den samme prompten ved 720P hadde et gjennomsnitt på 41 sekunder. Kostnaden skalerer omtrent lineært med varighet og dobles fra 720P til 1080P.

Wan 2.7 T2V aksepterer oppløsning, varighet, forhold og seed som parametere, returnerer en task_id, og har et gjennomsnitt på 78 sekunder ved 1080P for en 5-sekunders gjengivelse ifølge interne tester utført i juli 2026 (Alibaba Cloud Model Studio oversikt).

Hvordan kaller du I2V (første-ramme)?

Første-ramme I2V animerer et enkelt bilde. I2V API-referansen spesifiserer media-arrayet med én oppføring av typen first_frame. Bildet må 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 begrensninger å validere før du sender inn. For det første må bilde-URL-en returnere en 200 på en HEAD-forespørsel uten autentiserings-headers, ellers vil Model Studio avvise kallet med en InvalidParameter.DownloadFailed-feil. For det andre bør innbildets sideforhold samsvare med det forespurte ratio-et, ellers vil modellen beskjære stille.

For en dypere gjennomgang av hvilken I2V-undermodus du skal velge, se PixMind bilde-til-video moduser forklart.

Hvordan kaller du I2V (første-siste-ramme)?

Første-siste-ramme I2V tar to bilder: en first_frame og en last_frame. I2V API-referansen behandler dem som to oppføringer i media-arrayet. Modellen interpolerer bevegelsen mellom 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 rammene bør være visuelt konsistente. Hvis startrammen viser et produkt til venstre i rammen og den siste rammen viser det til høyre, må modellen finne opp en kamerabevegelse, noe som er der forvrengning oppstår.

Vi kjører et valideringstrinn før innsending: samme sideforhold på begge rammene, samme dominerende motiv, samme lysretning. Kall som passerer denne sjekken lander rent omtrent 85 prosent av tiden. Kall som feiler lander rent omtrent 40 prosent av tiden.

Første-siste-ramme I2V bruker samme endepunkt som første-ramme, med to oppføringer i media-arrayet. Interne valideringstester i juli 2026 viste en 85 prosent ren-gjengivelsesrate når begge rammene deler sideforhold, motiv og belysning (Alibaba Cloud I2V API-referanse).

Hvordan kaller du I2V (lyddrevet)?

Lyddrevet I2V tar et enkelt bilde pluss et lydspor. I2V API-referansen lister driving_audio som medietype. Lyden driver leppebevegelse når et ansikt er til stede og generell bevegelsesenergi 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 er viktig. WAV ved 16kHz mono produserer den mest pålitelige leppesynkroniseringen. MP3 ved lavere bitrater legger til artefakter som modellen tolker som bevegelsesenergi, noe som viser seg som uønsket hodebevegelse. Hold prompter korte her, lyden gjør jobben.

For "talking-head" brukstilfeller, passer dette med PixMind karakterytelsesklyngen.

Hvordan kaller du R2V (multimodal referanse)?

R2V (referanse-til-video) er den kraftigste og minst dokumenterte modusen. Wan video-til-video API-referansen aksepterer opptil fem referansebilder, fem referanseklipp og ett referanselydspor i et enkelt kall. Modellen bruker disse til å bevare identitet, stemme og stil på tvers av utdataene.

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 har en grense på 10 sekunder, kortere enn taket på 15 sekunder for T2V og I2V. Identitetsbevaring forbedres med flere referansebilder opptil tre, deretter flater det ut. Å legge til referanseklipp (korte B-ruller av samme motiv) øker bevegelseskonsistensen merkbart.

[UNIKE INNSIKTER] Referanseinputene er vekter, ikke begrensninger. Hvis referansebildet ditt viser en karakter forfra og prompten din ber om en sidevisning, vil modellen blande de to i stedet for å velge én. Behandle referanser som sterke forhåndsantakelser, ikke som harde mål.

R2V aksepterer opptil fem referansebilder, fem referanseklipp og ett referanselydspor i ett kall. Identitetsbevaring forbedres med referansebilder opptil tre, deretter flater det ut, per interne tester i tråd med Wan video-til-video API-referansen.

For heuristikker for modusvalg på tvers av T2V, I2V og R2V, se PixMind modus auto-ruting innlegget.

Hvordan fungerer asynkron oppgave-polling?

Alle Wan 2.7 endepunkter er asynkrone. Innsendingskallet returnerer umiddelbart med en task_id. Du poller oppgave-endepunktet til status når en terminaltilstand. Oversikten over videogenerering lister fem statuser: 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åndhever i produksjon. For det første, bruk et 10-sekunders intervall. Raskere polling fører til rate-begrensning, ikke raskere resultater. For det andre, sett en timeout. En 5-sekunders 1080P-gjengivelse bør ikke ta 10 minutter; hvis den gjør det, er noe galt, og du bør prøve på nytt i stedet for å vente.

Wan 2.7 endepunkter returnerer en task_id og eksponerer et polling-endepunkt på /api/v1/tasks/{task_id}. Statuser sykluser gjennom PENDING, RUNNING, SUCCEEDED, FAILED og CANCELED, med et anbefalt 10-sekunders polling-intervall per oversikten over videogenerering.

Hvordan håndterer du feil og nye forsøk?

Wan 2.7-feil deles inn i tre kategorier. Klientfeil (HTTP 4xx) betyr at forespørselen din er feilformet eller uautorisert, og et nytt forsøk vil ikke hjelpe. Serverfeil (HTTP 5xx) og tidsavbrudd er midlertidige. Oppgavefeil (status: FAILED) kan være midlertidige eller permanente, avhengig av feilkoden.

Oversikten over videogenerering dokumenterer de vanlige feilkodene. De hyppigste vi ser er:

En retry-wrapper med eksponentiell 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] Over 2000 sporede kall i juli 2026, så vi 4,1 prosent midlertidige feil (HTTP 5xx, 429, tilkoblingsfeil). Av disse lyktes 91 prosent ved første forsøk, 6 prosent ved andre, og 3 prosent ved tredje. Sett antall forsøk til fire og gå videre.

Prøv kun på nytt ved midlertidige feil. HTTP 429 og 5xx er trygge å prøve på nytt med eksponentiell backoff. I et utvalg på 2000 kall fra juli 2026 var 4,1 prosent midlertidige, og 91 prosent av disse lyktes ved første forsøk (Alibaba Cloud videogenerering oversikt).

Wan 2.7 API FAQ

Hva er base-URL-en for Wan 2.7 endepunkter?

Wan 2.7 video-endepunkter ligger under https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Oppgave-polling-endepunktet er https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Begge er dokumentert i oversikten over videogenerering.

Finnes det en offisiell Python SDK?

Alibaba leverer DashScope Python SDK (dashscope) på PyPI. Eksemplene i denne guiden bruker requests for portabilitet. Hvis du foretrekker SDK-en, er det tilsvarende kallet dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).n

Kan jeg avbryte en pågående oppgave?

Ja. En POST til /api/v1/tasks/{task_id}/cancel markerer oppgaven som CANCELED. Du blir fakturert for allerede forbrukt datakraft, så kansellering er delvis refusjon, ikke gratis.

Hvor lang tid tar en R2V-gjengivelse?

R2V er tregere enn T2V og I2V ved samme oppløsning og varighet. En 5-sekunders 1080P R2V-gjengivelse med tre referansebilder tar i gjennomsnitt 110 sekunder i våre tester, mot 78 sekunder for T2V. Planlegg tidsavbrudd deretter.

Støtter Wan 2.7 endepunkter webhooks?

Ikke natively. Du må polle. Hvis du trenger webhook-lignende levering, pakk polling-loopen inn i en tjeneste som poster til din callback-URL når oppgaven er fullført.

Se det i aksjon

Relatert på X: OpenRouter — OpenRouter API-integrasjonskunngjøring for Wan 2.7..