Panduan Integrasi API Wan 2.7: Penjelasan Endpoint T2V, I2V, dan R2V

Poin-Poin Penting

Wan 2.7 mengekspos tiga endpoint generasi inti melalui Alibaba Cloud Model Studio (Bailian): T2V, I2V, dan R2V, semuanya berbagi pola tugas asinkron yang sama.
Setiap panggilan bersifat asinkron: Anda mengirimkan input, menerima task_id, dan melakukan polling hingga status mencapai SUCCEEDED (lihat gambaran umum pembuatan video).
I2V menerima tiga sub-mode melalui endpoint yang sama: bingkai-pertama, bingkai-pertama-terakhir, dan digerakkan-audio, dibedakan oleh isi array media.
R2V mengambil hingga lima gambar referensi, lima klip referensi, dan satu trek audio referensi dalam satu panggilan, sesuai referensi API video-ke-video Wan.
Untuk alternatif yang di-hosting yang membungkus endpoint yang sama, lihat generator video PixMind Wan 2.7.

Apa yang Dicakup Panduan Ini

Wan 2.7 dikirimkan sebagai satu keluarga model di balik tiga endpoint generasi yang di-hosting di Alibaba Cloud Model Studio (Bailian). Gambaran umum pembuatan video mendokumentasikan pola asinkron terpadu: kirim, dapatkan task_id, polling, ambil hasilnya. Panduan ini menjelaskan setiap endpoint dengan contoh cURL dan Python yang dapat Anda tempelkan ke terminal.

Kami telah mengirimkan dua integrasi terhadap endpoint ini tahun ini. Pola yang bertahan dalam produksi adalah: klien tipis, satu loop polling, coba lagi pada kegagalan sementara, dan validasi payload eksplisit per-mode sebelum permintaan meninggalkan server Anda.

Jika Anda ingin melewati lapisan API sepenuhnya, generator video PixMind Wan 2.7 mengekspos keluarga model yang sama melalui satu antarmuka web dengan perutean mode bawaan.

Prasyarat

Anda memerlukan akun Alibaba Cloud dengan Model Studio diaktifkan, Kunci API, dan Python 3.9 atau yang lebih baru. Konsol Model Studio mengekspos Kunci API di bawah "API Keys" di dasbor Bailian, seperti yang didokumentasikan dalam gambaran umum pembuatan video.

Instal requests untuk contoh Python:

pip install requests

Anda juga memerlukan URL dasar endpoint. Endpoint video Wan 2.7 menggunakan:

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

[WAWASAN UNIK] Perlakukan Kunci API seperti rahasia produksi. Simpan dalam variabel lingkungan (DASHSCOPE_API_KEY), jangan pernah dalam kode sumber. Jika kunci bocor, putar dari konsol Model Studio, dan tugas yang sedang berjalan yang dibuat dengan kunci lama akan terus selesai tetapi panggilan baru akan gagal.

Otentikasi

Wan 2.7 menggunakan otentikasi bearer-token. Setiap permintaan membawa header Authorization: Bearer $DASHSCOPE_API_KEY, ditambah X-DashScope-Async: enable untuk memilih pola asinkron yang didokumentasikan dalam gambaran umum pembuatan video.

Pemeriksaan cURL minimal:

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

Respons 200 berarti kunci valid. Respons 401 berarti kunci hilang, kedaluwarsa, atau dicakupkan ke wilayah yang berbeda. Kami menemukan bahwa ketidakcocokan wilayah adalah kegagalan senyap yang paling umum: kunci yang dibuat di cn-beijing tidak akan mengautentikasi terhadap endpoint us-east-1.

Dalam Python, simpan kunci sekali dan gunakan kembali sesi:

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

Bagaimana Cara Memanggil T2V?

T2V (text-to-video) mengambil prompt ditambah parameter dan mengembalikan task_id. Gambaran umum pembuatan video mencantumkan resolution, duration, ratio, dan seed sebagai kontrol utama.

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

Setara Python menggunakan session bersama:

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

[DATA ASLI] Dalam pengujian integrasi kami, T2V pada 1080P, 5 detik, 16:9 rata-rata 78 detik dari awal hingga akhir di 50 render (Juli 2026). Prompt yang sama pada 720P rata-rata 41 detik. Biaya meningkat secara kasar linier dengan durasi dan berlipat ganda dari 720P ke 1080P.

Wan 2.7 T2V menerima resolusi, durasi, rasio, dan seed sebagai parameter, mengembalikan task_id, dan rata-rata 78 detik pada 1080P untuk render 5 detik menurut pengujian internal yang dilakukan pada Juli 2026 (gambaran umum Alibaba Cloud Model Studio).

Bagaimana Cara Memanggil I2V (Bingkai-Pertama)?

I2V bingkai-pertama menganimasikan satu gambar. Referensi API I2V menentukan array media dengan satu entri bertipe first_frame. Gambar harus berupa URL publik.

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

Dua batasan praktis untuk divalidasi sebelum Anda mengirimkan. Pertama, URL gambar harus mengembalikan 200 pada permintaan HEAD tanpa header otentikasi, jika tidak Model Studio akan menolak panggilan dengan kesalahan InvalidParameter.DownloadFailed. Kedua, rasio aspek gambar input harus cocok dengan ratio output yang diminta, atau model akan memotong secara diam-diam.

Untuk penjelasan lebih mendalam tentang sub-mode I2V mana yang harus dipilih, lihat penjelasan mode gambar-ke-video PixMind.

Bagaimana Cara Memanggil I2V (Bingkai-Pertama-Terakhir)?

I2V bingkai-pertama-terakhir mengambil dua gambar: first_frame dan last_frame. Referensi API I2V memperlakukannya sebagai dua entri dalam array media. Model menginterpolasi gerakan di antara keduanya.

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

Kedua bingkai harus konsisten secara visual. Jika bingkai awal menunjukkan produk di kiri bingkai dan bingkai terakhir menunjukkannya di kanan, model harus menciptakan gerakan kamera, di situlah muncul distorsi.

Kami menjalankan langkah validasi sebelum pengiriman: rasio aspek yang sama pada kedua bingkai, subjek dominan yang sama, arah pencahayaan yang sama. Panggilan yang melewati pemeriksaan ini berhasil sekitar 85 persen. Panggilan yang gagal berhasil sekitar 40 persen.

I2V bingkai-pertama-terakhir menggunakan endpoint yang sama dengan bingkai-pertama, dengan dua entri dalam array media. Pengujian validasi internal pada Juli 2026 menunjukkan tingkat render bersih 85 persen ketika kedua bingkai memiliki rasio aspek, subjek, dan pencahayaan yang sama (referensi API I2V Alibaba Cloud).

Bagaimana Cara Memanggil I2V (Digerakkan-Audio)?

I2V digerakkan-audio mengambil satu gambar ditambah trek audio. Referensi API I2V mencantumkan driving_audio sebagai jenis media. Audio menggerakkan gerakan bibir ketika ada wajah dan energi gerakan keseluruhan jika tidak.

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

Format audio penting. WAV pada 16kHz mono menghasilkan sinkronisasi bibir yang paling andal. MP3 pada bitrate yang lebih rendah menambahkan artefak yang diinterpretasikan model sebagai energi gerakan, yang muncul sebagai gerakan kepala yang tidak diinginkan. Pertahankan prompt singkat di sini, audio yang melakukan pekerjaan.

Untuk kasus penggunaan talking-head, ini berpasangan dengan kluster kinerja karakter PixMind.

Bagaimana Cara Memanggil R2V (Referensi Multimodal)?

R2V (reference-to-video) adalah mode yang paling kuat dan paling sedikit didokumentasikan. Referensi API video-ke-video Wan menerima hingga lima gambar referensi, lima klip referensi, dan satu trek audio referensi dalam satu panggilan. Model menggunakan ini untuk mempertahankan identitas, suara, dan gaya di seluruh 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 dibatasi pada 10 detik, lebih pendek dari batas 15 detik T2V dan I2V. Preservasi identitas meningkat dengan lebih banyak gambar referensi hingga tiga, kemudian stabil. Menambahkan klip referensi (B-roll singkat dari subjek yang sama) secara signifikan meningkatkan konsistensi gerakan.

[WAWASAN UNIK] Input referensi adalah bobot, bukan batasan. Jika gambar referensi Anda menunjukkan karakter dari depan dan prompt Anda meminta tampilan samping, model akan memadukan keduanya daripada memilih salah satu. Perlakukan referensi sebagai prior yang kuat, bukan sebagai target yang kaku.

R2V menerima hingga lima gambar referensi, lima klip referensi, dan satu audio referensi dalam satu panggilan. Preservasi identitas meningkat dengan gambar referensi hingga tiga kemudian stabil, per pengujian internal yang selaras dengan referensi API video-ke-video Wan.

Untuk heuristik pemilihan mode di T2V, I2V, dan R2V, lihat postingan perutean otomatis mode 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.

Bagaimana Cara Kerja Polling Tugas Asinkron?

Semua endpoint Wan 2.7 bersifat asinkron. Panggilan pengiriman segera mengembalikan task_id. Anda melakukan polling endpoint tugas hingga status mencapai status terminal. Gambaran umum pembuatan video mencantumkan lima status: 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")

Dua aturan polling yang kami terapkan dalam produksi. Pertama, gunakan interval 10 detik. Polling yang lebih cepat akan membuat Anda terkena batasan kecepatan, bukan hasil yang lebih cepat. Kedua, atur batas waktu. Render 1080P 5 detik seharusnya tidak memakan waktu 10 menit, jika ya, ada yang salah dan Anda harus mencoba lagi daripada menunggu.

Endpoint Wan 2.7 mengembalikan task_id dan mengekspos endpoint polling di /api/v1/tasks/{task_id}. Status berputar melalui PENDING, RUNNING, SUCCEEDED, FAILED, dan CANCELED, dengan interval polling 10 detik yang direkomendasikan per gambaran umum pembuatan video.

Bagaimana Cara Menangani Kesalahan dan Percobaan Ulang?

Kesalahan Wan 2.7 terbagi menjadi tiga kategori. Kesalahan klien (HTTP 4xx) berarti permintaan Anda salah format atau tidak sah dan percobaan ulang tidak akan membantu. Kesalahan server (HTTP 5xx) dan batas waktu bersifat sementara. Kegagalan tugas (status: FAILED) bisa bersifat sementara atau permanen, tergantung pada kode kesalahan.

Gambaran umum pembuatan video mendokumentasikan kode kesalahan umum. Yang paling sering kami lihat adalah:

Kode	Arti	Tindakan
`InvalidParameter.DownloadFailed`	URL input tidak dapat dijangkau	Host ulang aset dan coba lagi
`DataInsufficient.UnsafeContent`	Prompt atau gambar ditandai oleh filter keamanan	Ubah input, jangan coba lagi
`Throttling.RateQuota`	QPS per kunci terlampaui	Exponential backoff
`InternalError.Timeout`	Model melebihi anggaran waktu internal	Coba lagi sekali
`AccessDenied.Arrear`	Akun kehabisan kredit	Isi ulang, jangan coba lagi

Pembungkus percobaan ulang dengan exponential 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")

[DATA ASLI] Dari 2.000 panggilan yang dilacak pada Juli 2026, kami melihat 4,1 persen kegagalan sementara (HTTP 5xx, 429, kesalahan koneksi). Dari jumlah tersebut, 91 persen berhasil pada percobaan ulang pertama, 6 persen pada yang kedua, dan 3 persen pada yang ketiga. Atur percobaan ulang menjadi empat dan lanjutkan.

Coba lagi hanya kegagalan sementara. HTTP 429 dan 5xx aman untuk dicoba lagi dengan exponential backoff. Dalam sampel 2.000 panggilan dari Juli 2026, 4,1 persen bersifat sementara dan 91 persen di antaranya berhasil pada percobaan ulang pertama (gambaran umum pembuatan video Alibaba Cloud).

FAQ API Wan 2.7

Apa URL dasar untuk endpoint Wan 2.7?

Endpoint video Wan 2.7 berada di bawah https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Endpoint polling tugas adalah https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Keduanya didokumentasikan dalam gambaran umum pembuatan video.

Apakah ada SDK Python resmi?

Alibaba mengirimkan DashScope Python SDK (dashscope) di PyPI. Contoh dalam panduan ini menggunakan requests untuk portabilitas. Jika Anda lebih suka SDK, panggilan yang setara adalah dashscope.VideoGeneration.call(model="wan2.7-t2v", ...) .

Bisakah saya membatalkan tugas yang sedang berjalan?

Ya. Permintaan POST ke /api/v1/tasks/{task_id}/cancel menandai tugas sebagai CANCELED. Anda ditagih untuk komputasi yang sudah dikonsumsi, jadi pembatalan adalah wilayah pengembalian dana sebagian, bukan gratis.

Berapa lama waktu yang dibutuhkan untuk render R2V?

R2V lebih lambat dari T2V dan I2V pada resolusi dan durasi yang sama. Render R2V 1080P 5 detik dengan tiga gambar referensi rata-rata 110 detik dalam pengujian kami, dibandingkan 78 detik untuk T2V. Rencanakan batas waktu sesuai.

Apakah endpoint Wan 2.7 mendukung webhook?

Tidak secara native. Anda harus melakukan polling. Jika Anda memerlukan pengiriman gaya webhook, bungkus loop polling dalam layanan yang memposting ke URL callback Anda ketika tugas selesai.

Saksikan Aksinya

Terkait di X: OpenRouter — Pengumuman integrasi API OpenRouter untuk Wan 2.7..

Panduan Integrasi API Wan 2.7: Penjelasan Endpoint T2V, I2V, dan R2V