Panduan Cepat API WAN 2.7 di WaveSpeed (2026)

Hei, semuanya. Saya Dora. Saya terus menunda ini. WAN 2.7 sudah rilis. Saya punya proyek yang membutuhkannya, dan saya bilang pada diri sendiri akan mengintegrasikannya “setelah semuanya stabil.” Itu biasanya insting yang salah. Permukaan API-nya mudah dipahami setelah kamu melewati penamaan versinya — dan sebagian besar friksi berasal dari satu atau dua keputusan yang kamu buat di awal yang secara diam-diam mempengaruhi segalanya ke depannya.

Ini bukan pameran fitur. Ini adalah apa yang sebenarnya saya butuhkan di hari pertama.

WAN 2.7 di Platform: Model ID & Ketersediaan

Sebelum menulis satu baris kode pun, saya menghabiskan sepuluh menit hanya untuk mengonfirmasi string model. Ini terdengar jelas, tapi WAN memiliki pola penamaan yang membingungkan orang — wan2.5-i2v, wan2.6-i2v, wan2.7-flf2v — dan menggunakan ID yang sudah usang menghasilkan 404 yang bersih tanpa pesan error yang membantu.

Katalog model adalah tempat pertama yang harus diperiksa. Navigasi ke bagian pembuatan video, filter berdasarkan versi 2.7, dan salin string model ID yang tepat. Jangan ketik dari ingatan.

Waktu ketersediaan juga penting. WAN 2.7 diluncurkan pada Maret 2026 dengan serangkaian kemampuan baru yang berarti — kontrol frame pertama/terakhir, sintesis image-to-video grid 3×3, hingga lima referensi video, dan pengeditan berbasis instruksi. Menurut ikhtisar pembuatan video Alibaba Cloud Model Studio, endpoint inferensi yang di-hosting untuk versi WAN baru biasanya aktif dalam beberapa hari setelah rilis resmi — tetapi tidak selalu pada hari yang sama, jadi periksa halaman status platform sebelum membangun sesuatu yang sensitif terhadap waktu.

Auth & Pengaturan API Key

Bagian ini cepat. API key kamu masuk ke header Authorization sebagai Bearer token. URL dasar mengikuti wilayah yang kamu pilih saat pengaturan akun — Singapura, Virginia, atau Beijing untuk deployment Tiongkok Daratan. Panggilan lintas wilayah akan gagal, tidak secara keras, hanya dengan error auth yang menghabiskan dua puluh menit jika kamu tidak mengantisipasinya.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Satu hal yang saya lakukan dari awal: simpan API key dalam variabel lingkungan dan jangan pernah hardcode, bahkan tidak dalam skrip uji lokal. Kunci yang bocor adalah kejutan tagihan yang tidak kamu inginkan.

Struktur URL dasar mengikuti konvensi REST standar seperti yang didefinisikan dalam IETF RFC 9110 (HTTP Semantics). Jika kamu pernah bekerja dengan API AI modern mana pun, ini akan terasa familiar — JSON masuk, JSON keluar, kode status yang berperilaku seperti yang diharapkan.

Parameter Request Inti

Di sinilah saya mendorong kamu untuk sedikit memperlambat. Parameter yang diperlukan kecil — model ID, prompt, tipe input — tetapi yang opsional membentuk kualitas output lebih dari yang kamu duga.

Wajib:

model — string model yang tepat, diverifikasi dari katalog
prompt — deskripsi teks kamu; untuk video, kekhususan lebih penting daripada panjang
Input: baik image_url (untuk I2V) atau teks saja untuk T2V

Opsional tapi praktis penting:

resolution — menerima "480P", "720P", "1080P"; WAN 2.7 mendukung output 1080P native hingga 15 detik
duration — 2 hingga 15 detik; klip yang lebih panjang lebih mahal dan membutuhkan waktu lebih lama untuk diproses
seed — kunci ini setelah kamu menemukan output yang bagus. Ini adalah satu-satunya parameter yang membuat hasilmu dapat direproduksi di berbagai run
negative_prompt — berguna untuk menekan flicker, blur, dan artefak gerak

Parameter khusus WAN 2.7 yang perlu diverifikasi saat rilis dokumen resmi:

first_frame_url + last_frame_url — untuk mode FLF2V (first-and-last-frame)
image_grid — struktur input 9-grid untuk komposisi I2V yang lebih kaya
edit_instruction — pengeditan bahasa alami pada video yang sudah ada

Tiga yang terakhir baru di versi 2.7. Nama parameter dapat berubah antara preview dan ketersediaan umum. Referensi API resmi adalah sumber yang otoritatif — membangun berdasarkan nama parameter pra-rilis adalah risiko yang kamu tanggung sendiri.

Pola Request Pertama

Text-to-video (minimal)

response = VideoSynthesis.async_call(
    model="wan2.7-t2v",      # verifikasi string tepat saat peluncuran
    prompt="A slow dolly shot through a foggy pine forest at dawn.",
    resolution="720P",
    duration=5,
    seed=42
)
task_id = response.output.task_id

Image-to-video standar

response = VideoSynthesis.async_call(
    model="wan2.7-i2v",
    img_url="https://your-cdn.com/input.jpg",
    prompt="Camera holds still. Subject turns slowly toward light.",
    resolution="720P",
    duration=5
)

Frame pertama + frame terakhir (FLF2V)

Di sinilah WAN 2.7 melakukan sesuatu yang tidak bisa dilakukan versi sebelumnya dengan bersih. Kamu mendefinisikan frame pembuka dan penutup; model mengisi gerakan di antaranya. Ini bukan animasi dalam arti tradisional — ini adalah inferensi terstruktur dari dua endpoint semantik.

response = VideoSynthesis.async_call(
    model="wan2.7-flf2v",   # verifikasi string tepat saat peluncuran
    first_frame_url="https://your-cdn.com/start.png",
    last_frame_url="https://your-cdn.com/end.png",
    prompt="Fixed camera. Smooth transition. Natural lighting.",
    resolution="720P",
    seed=99
)

Kualitas pasangan frame kamu lebih penting daripada promptnya. Pasangan yang cocok dengan baik dengan hubungan spasial yang jelas akan secara konsisten mengungguli prompt yang dipoles pada frame input yang tidak cocok. Saya sudah cukup banyak menguji untuk mengatakannya dengan yakin. Sebagai referensi tentang bagaimana varian open-weight menangani frame conditioning, repositori model WAN di Hugging Face mendokumentasikan arsitekturnya secara detail — berguna bahkan jika kamu hanya memanggil API yang di-hosting.

Image-to-video 9-grid

Input 9-grid memungkinkan kamu melewatkan susunan 3×3 gambar diam sebagai referensi komposisi untuk satu generasi. Verifikasi struktur payload yang tepat saat peluncuran — parameter kemungkinan menerima array sembilan URL gambar, tetapi perlakukan dokumentasi pra-rilis mana pun sebagai provisional.

Penanganan Job Async: Submit → Poll → Result

Pembuatan video tidak pernah sinkron. Bahkan untuk klip pendek, perkirakan 1–5 menit per job. Polanya selalu sama: submit → dapatkan task_id → poll → ambil URL hasil.

import time

def poll_for_result(task_id, interval=15, timeout=600):
    elapsed = 0
    while elapsed < timeout:
        result = VideoSynthesis.fetch(task_id)
        status = result.output.task_status
        if status == "SUCCEEDED":
            return result.output.video_url
        if status == "FAILED":
            raise Exception(f"Task failed: {result}")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Job exceeded timeout")

Interval polling: 15 detik adalah rekomendasi terdokumentasi dari referensi API Alibaba sendiri untuk endpoint image-to-video Wan. Jangan poll lebih cepat — itu tidak akan mempercepat apapun dan kamu akan menghabiskan batas rate.

Transisi status task: PENDING → RUNNING → SUCCEEDED atau FAILED. URL hasil valid selama 24 jam setelah generasi. Unduh dan simpan segera — jika kamu melewatkan jendela itu, task ID juga kedaluwarsa setelah 24 jam dan mengembalikan UNKNOWN pada kueri berikutnya. Saya mempelajari ini dengan cara yang canggung pada batch run pertama saya.

Penanganan Error

Error yang paling sering kamu temui:

Error	Kemungkinan penyebab	Solusi
404 pada model	Model ID salah atau sudah usang	Verifikasi string tepat dari katalog
400 pada input	Format gambar ditolak atau URL tidak dapat diakses	Gunakan URL HTTPS publik; verifikasi format
429 Too Many Requests	Batas rate tercapai	Exponential backoff dengan jitter
Status task UNKNOWN	Task ID kedaluwarsa (jendela 24 jam)	Poll lebih cepat; unduh hasil segera

Untuk 429: mundur, tambahkan jitter, jangan retry dalam loop ketat. Dokumentasi HTTP MDN tentang perilaku header Retry-After menjelaskan pola standar — header respons sering memberi tahu kamu kapan tepatnya harus retry.

Batas rate job video untuk WAN 2.7 dipublikasikan secara terpisah dari batas pembuatan gambar. Job dengan resolusi tinggi atau durasi lebih panjang biasanya dihitung terhadap batas job bersamaan, bukan hanya batas permintaan per menit. Verifikasi terhadap dokumentasi tier akun kamu.

Estimasi Biaya

Harga WAN 2.7 belum final pada saat penulisan. Dari apa yang konsisten di seluruh keluarga model WAN, biaya berskala pada tiga dimensi:

Resolusi — 1080P secara berarti lebih mahal daripada 720P per detik output
Durasi — ditagih per detik video yang dihasilkan
Kompleksitas input — input multi-referensi mungkin membawa pengganda; konfirmasi saat peluncuran

Formula estimasi kasar:

estimated cost = duration (seconds) × resolution multiplier × unit price per second

Sebelum menjalankan batch, uji satu klip di setiap kombinasi resolusi dan durasi yang kamu rencanakan untuk digunakan. Ikhtisar penagihan Alibaba Cloud untuk Model Studio akan memiliki biaya unit per detik setelah tarif WAN 2.7 resmi dipublikasikan. Biaya pembuatan video bertambah lebih cepat daripada pembuatan gambar — resolusi adalah tuas terbesar.

FAQ

Apakah WAN 2.7 tersedia pada hari yang sama dengan peluncuran resmi Alibaba?

Tidak selalu. Endpoint API yang di-hosting biasanya aktif dalam beberapa hari setelah rilis open-weight, kadang hari yang sama, kadang seminggu kemudian. Pantau changelog platform secara langsung. Repositori GitHub model WAN secara historis adalah tempat tim Alibaba pertama kali mendokumentasikan perubahan skema untuk rilis open-weight baru.

Apakah panggilan API WAN 2.5 kompatibel dengan WAN 2.7?

Payload T2V standar dan I2V gambar tunggal seharusnya kompatibel secara struktural — fitur baru 2.7 tampaknya bersifat aditif daripada breaking. Meskipun demikian, kamu perlu memperbarui string model ID, dan kode apa pun yang menggunakan parameter khusus 2.5 harus diuji sebelum diperlakukan sebagai drop-in. Mode 9-grid dan FLF2V memerlukan struktur payload baru sepenuhnya.

Berapa batas rate untuk job video WAN 2.7?

Verifikasi terhadap tier akun kamu saat runtime. Sebagai default yang berfungsi: antrikan job dengan aliran yang stabil daripada burst. Tangani 429 dengan exponential backoff. Log request_id dari setiap respons — ini adalah field yang paling berguna ketika sesuatu salah dan kamu perlu melacaknya.

Mekanismenya di sini tidak rumit. Yang sebenarnya membutuhkan waktu adalah membangun aset input yang bagus — pasangan frame, gambar referensi, prompt yang tetap spesifik tanpa menjadi kaku. Setelah itu stabil, sisi API menjadi rutinitas.

Saya akan memperbarui ini setelah dokumentasi parameter resmi WAN 2.7 aktif dan saya mendapat kesempatan untuk menguji format 9-grid dari awal hingga akhir. Itu bagian yang paling ingin saya ketahui.

Postingan Sebelumnya: