Wan 2.7 API Integratiegids: T2V, I2V en R2V Endpoints Uitgelegd

Wan 2.7 API Integratiegids: T2V, I2V en R2V Endpoints Uitgelegd

Belangrijkste Punten

• Wan 2.7 exposeert drie kern generatie-endpoints via Alibaba Cloud Model Studio (Bailian): T2V, I2V en R2V, die allemaal hetzelfde asynchrone taakpatroon delen.
• Elke aanroep is asynchroon: u dient invoer in, ontvangt een task_id en pollt totdat de status SUCCEEDED bereikt (zie het overzicht van videogeneratie).
• I2V accepteert drie submodi via hetzelfde endpoint: first-frame, first-last-frame en audio-driven, onderscheiden door de inhoud van de media array.
• R2V accepteert tot vijf referentieafbeeldingen, vijf referentieclips en één referentie-audiotrack in één enkele aanroep, volgens de Wan video-naar-video API-referentie.
• Voor een gehost alternatief dat dezelfde endpoints omvat, zie de PixMind Wan 2.7 videogenerator.

Wat Deze Gids Behandelt

Wan 2.7 wordt geleverd als één modelfamilie achter drie generatie-endpoints die worden gehost op Alibaba Cloud Model Studio (Bailian). Het overzicht van videogeneratie documenteert het uniforme asynchrone patroon: indienen, een task_id krijgen, pollen, het resultaat ophalen. Deze gids doorloopt elk endpoint met cURL- en Python-voorbeelden die u in een terminal kunt plakken.

We hebben dit jaar twee integraties tegen deze endpoints geleverd. Het patroon dat in productie overleeft, is: dunne client, enkele polling-lus, opnieuw proberen bij tijdelijke storingen en expliciete payload-validatie per modus voordat de aanvraag uw server verlaat.

Als u de API-laag volledig wilt overslaan, exposeert de PixMind Wan 2.7 videogenerator dezelfde modelfamilie via één webinterface met ingebouwde modusroutering.

Vereisten

U heeft een Alibaba Cloud-account nodig met Model Studio ingeschakeld, een API-sleutel en Python 3.9 of nieuwer. De Model Studio-console exposeert de API-sleutel onder "API Keys" in het Bailian-dashboard, zoals gedocumenteerd in het overzicht van videogeneratie.

Installeer requests voor de Python-voorbeelden:

pip install requests

U heeft ook de basis-URL van het endpoint nodig. Wan 2.7 video-endpoints gebruiken:

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

[UNIEK INZICHT] Behandel de API-sleutel als een productiegeheim. Sla deze op in een omgevingsvariabele (DASHSCOPE_API_KEY), nooit in de broncode. Als een sleutel lekt, roteer deze dan vanuit de Model Studio-console, en alle lopende taken die met de oude sleutel zijn gemaakt, zullen worden voltooid, maar nieuwe aanroepen zullen mislukken.

Authenticatie

Wan 2.7 gebruikt bearer-token authenticatie. Elke aanvraag bevat een Authorization: Bearer $DASHSCOPE_API_KEY header, plus X-DashScope-Async: enable om te kiezen voor het asynchrone patroon dat is gedocumenteerd in het overzicht van videogeneratie.

Een minimale cURL-controle:

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

Een 200-antwoord betekent dat de sleutel geldig is. Een 401 betekent dat de sleutel ontbreekt, is verlopen of is gekoppeld aan een andere regio. We hebben ontdekt dat regiomisovereenkomsten de meest voorkomende stille fout zijn: sleutels die zijn gemaakt in cn-beijing zullen niet authenticeren tegen us-east-1 endpoints.

In Python, sla de sleutel eenmaal op en hergebruik de sessie:

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

Hoe Roept U T2V Aan?

T2V (text-to-video) neemt een prompt plus parameters en retourneert een task_id. Het overzicht van videogeneratie noemt resolution, duration, ratio en seed als de primaire instellingen.

cURL-voorbeeld:

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-equivalent met behulp van de gedeelde 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"]

[ORIGINELE GEGEVENS] In onze integratietests duurde T2V op 1080P, 5 seconden, 16:9 gemiddeld 78 seconden end-to-end over 50 renders (juli 2026). Dezelfde prompt op 720P duurde gemiddeld 41 seconden. De kosten schalen ruwweg lineair met de duur en verdubbelen van 720P naar 1080P.

Wan 2.7 T2V accepteert resolutie, duur, verhouding en seed als parameters, retourneert een task_id en duurt gemiddeld 78 seconden op 1080P voor een render van 5 seconden volgens interne tests uitgevoerd in juli 2026 (Alibaba Cloud Model Studio overzicht).

Hoe Roept U I2V Aan (Eerste-Frame)?

First-frame I2V animeert één enkele afbeelding. De I2V API-referentie specificeert de media array met één item van het type first_frame. De afbeelding moet een openbare URL zijn.

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

Twee praktische beperkingen om te valideren voordat u indient. Ten eerste moet de afbeeldings-URL een 200 retourneren bij een HEAD-aanvraag zonder authenticatieheaders, anders zal Model Studio de aanroep weigeren met een InvalidParameter.DownloadFailed fout. Ten tweede moet de beeldverhouding van de invoerafbeelding overeenkomen met de gevraagde uitvoer ratio, anders zal het model stilzwijgend bijsnijden.

Voor een diepere uitleg over welke I2V-submodus u moet kiezen, zie de PixMind image-to-video modi uitleg.

Hoe Roept U I2V Aan (Eerste-Laatste-Frame)?

First-last-frame I2V neemt twee afbeeldingen: een first_frame en een last_frame. De I2V API-referentie behandelt ze als twee items in de media array. Het model interpoleert de beweging ertussen.

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 twee frames moeten visueel consistent zijn. Als het startframe een product aan de linkerkant van het frame toont en het laatste frame het aan de rechterkant toont, moet het model een camerabeweging uitvinden, wat resulteert in vervorming.

We voeren een validatiestap uit vóór indiening: dezelfde beeldverhouding op beide frames, hetzelfde dominante onderwerp, dezelfde belichtingsrichting. Aanroepen die deze controle doorstaan, slagen ongeveer 85 procent van de tijd. Aanroepen die falen, slagen ongeveer 40 procent van de tijd.

First-last-frame I2V gebruikt hetzelfde endpoint als first-frame, met twee items in de media-array. Interne validatietests in juli 2026 toonden een 85 procent schone-render-rate wanneer beide frames dezelfde beeldverhouding, onderwerp en belichting delen (Alibaba Cloud I2V API-referentie).

Hoe Roept U I2V Aan (Audio-Gestuurd)?

Audio-driven I2V neemt één enkele afbeelding plus een audiotrack. De I2V API-referentie vermeldt driving_audio als het mediatype. De audio stuurt lipbeweging aan wanneer een gezicht aanwezig is en anders de algehele bewegingsenergie.

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

Audioformaat is belangrijk. WAV op 16kHz mono produceert de meest betrouwbare lipsynchronisatie. MP3 op lagere bitrates voegt artefacten toe die het model interpreteert als bewegingsenergie, wat zich uit in ongewenste hoofdbewegingen. Houd prompts hier kort, de audio doet het werk.

Voor talking-head use cases, past dit bij de PixMind karakterprestatiecluster.

Hoe Roept U R2V Aan (Multimodale Referentie)?

R2V (reference-to-video) is de krachtigste en minst gedocumenteerde modus. De Wan video-naar-video API-referentie accepteert tot vijf referentieafbeeldingen, vijf referentieclips en één referentie-audiotrack in één enkele aanroep. Het model gebruikt deze om identiteit, stem en stijl te behouden over de uitvoer.

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 is beperkt tot 10 seconden, korter dan het maximum van 15 seconden voor T2V en I2V. Identiteitsbehoud verbetert met meer referentieafbeeldingen tot drie, en stagneert daarna. Het toevoegen van referentieclips (korte B-roll van hetzelfde onderwerp) verhoogt de bewegingsconsistentie merkbaar.

[UNIEK INZICHT] De referentie-inputs zijn gewichten, geen beperkingen. Als uw referentieafbeelding een personage van voren toont en uw prompt vraagt om een zijaanzicht, zal het model de twee mengen in plaats van er één te kiezen. Behandel referenties als sterke priors, niet als harde doelen.

R2V accepteert tot vijf referentieafbeeldingen, vijf referentieclips en één referentie-audio in één aanroep. Identiteitsbehoud verbetert met referentieafbeeldingen tot drie, en stagneert daarna, volgens interne tests die overeenkomen met de Wan video-naar-video API-referentie.

Voor heuristieken voor modusselectie over T2V, I2V en R2V, zie de PixMind modus auto-routing post.

Hoe Werkt Asynchrone Taakpolling?

Alle Wan 2.7 endpoints zijn asynchroon. De indieningsaanroep retourneert onmiddellijk een task_id. U pollt het taak-endpoint totdat de status een terminale staat bereikt. Het overzicht van videogeneratie vermeldt vijf statussen: 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")

Twee pollingregels die we in productie afdwingen. Ten eerste, gebruik een interval van 10 seconden. Sneller pollen leidt tot rate-limiting, niet tot snellere resultaten. Ten tweede, stel een timeout in. Een 5-seconden 1080P render zou geen 10 minuten moeten duren; als dat wel het geval is, is er iets mis en moet u het opnieuw proberen in plaats van te wachten.

Wan 2.7 endpoints retourneren een task_id en exposeren een polling-endpoint op /api/v1/tasks/{task_id}. Statussen doorlopen PENDING, RUNNING, SUCCEEDED, FAILED en CANCELED, met een aanbevolen polling-interval van 10 seconden volgens het overzicht van videogeneratie.

Hoe Gaat U Om Met Fouten en Opnieuw Proberen?

Wan 2.7 fouten vallen uiteen in drie categorieën. Clientfouten (HTTP 4xx) betekenen dat uw aanvraag onjuist is geformuleerd of ongeautoriseerd is en een nieuwe poging zal niet helpen. Serverfouten (HTTP 5xx) en timeouts zijn tijdelijk. Taakfouten (status: FAILED) kunnen tijdelijk of permanent zijn, afhankelijk van de foutcode.

Het overzicht van videogeneratie documenteert de veelvoorkomende foutcodes. De meest voorkomende die we zien zijn:

Een retry wrapper met exponentiële 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")

[ORIGINELE GEGEVENS] Over 2.000 gevolgde aanroepen in juli 2026 zagen we 4,1 procent tijdelijke storingen (HTTP 5xx, 429, verbindingsfouten). Daarvan slaagde 91 procent bij de eerste poging, 6 procent bij de tweede en 3 procent bij de derde. Stel het aantal nieuwe pogingen in op vier en ga verder.

Probeer alleen tijdelijke storingen opnieuw. HTTP 429 en 5xx zijn veilig om opnieuw te proberen met exponentiële backoff. In een steekproef van 2.000 aanroepen uit juli 2026 was 4,1 procent tijdelijk en 91 procent daarvan slaagde bij de eerste poging (Alibaba Cloud videogeneratie overzicht).

Wan 2.7 API Veelgestelde Vragen

Wat is de basis-URL voor Wan 2.7 endpoints?

Wan 2.7 video-endpoints bevinden zich onder https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Het taakpolling-endpoint is https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Beide zijn gedocumenteerd in het overzicht van videogeneratie.

Is er een officiële Python SDK?

Alibaba levert de DashScope Python SDK (dashscope) op PyPI. De voorbeelden in deze gids gebruiken requests voor portabiliteit. Als u de SDK verkiest, is de equivalente aanroep dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).

Kan ik een lopende taak annuleren?

Ja. Een POST naar /api/v1/tasks/{task_id}/cancel markeert de taak als CANCELED. U wordt gefactureerd voor reeds verbruikte rekenkracht, dus annulering is gedeeltelijke terugbetaling, niet gratis.

Hoe lang duurt een R2V render?

R2V is langzamer dan T2V en I2V bij dezelfde resolutie en duur. Een 5-seconden 1080P R2V render met drie referentieafbeeldingen duurt gemiddeld 110 seconden in onze tests, versus 78 seconden voor T2V. Plan timeouts dienovereenkomstig.

Ondersteunen Wan 2.7 endpoints webhooks?

Niet native. U moet pollen. Als u webhook-achtige levering nodig heeft, wikkel dan de polling-lus in een service die naar uw callback-URL post wanneer de taak is voltooid.

Bekijk Het in Actie

Gerelateerd op X: OpenRouter — OpenRouter API integratie aankondiging voor Wan 2.7..