WAN 2.5 API Quickstart di WaveSpeed: Auth, Parameters, dan Contoh Request

Hai, saya Dora. Awalnya, saya tidak berencana untuk mencoba WAN 2.5 API di WaveSpeed minggu ini. Sebuah gangguan kecil mendorong saya ke sana: saya membutuhkan beberapa variasi gambar yang konsisten untuk draf, dan alat biasa saya terlalu banyak klik atau terlalu pintar untuk kebaikannya sendiri. Saya menginginkan sesuatu yang membosankan dan dapat diandalkan, dapat ditulis skrip, tersertifikasi, mudah untuk dikembalikan.

Jadi saya membuka dokumentasi, menyeduh teh, dan membuat skrip kecil. Ini adalah apa yang saya catat selama perjalanan, diuji pada Januari 2026, tanpa kilau. Ini bukan tentang “fitur” tetapi lebih tentang bagian-bagian yang membuat pekerjaan terasa lebih ringan setelah diterapkan.

Gambaran umum API

Jika Anda pernah menyentuh API AI modern, pendekatan WaveSpeed untuk WAN 2.5 akan terasa familiar. HTTP masuk, JSON keluar. Anda mengirim prompt (dan terkadang gambar), hasilnya adalah artefak yang selesai atau ID pekerjaan yang dapat Anda polling.

Beberapa detail dasar yang saya perhatikan sebelum menulis kode apa pun:

Versioning: WAN 2.5 diekspos sebagai versi yang berbeda, penting untuk dapat direproduksi. Saya mengikuti jalur versi eksplisit dalam URL daripada alias “terbaru”. Pilihan kecil itu menyelamatkan saya di masa depan dari perubahan perilaku senyap.
Mode: Beberapa beban kerja bersifat sinkron (kecil, cepat), yang lain muncul sebagai pekerjaan. Jika Anda melakukan generasi resolusi lebih tinggi atau pekerjaan batch, harapkan aliran asinkron dengan titik akhir status atau webhook.
Format: Respons JSON biasanya mencakup status, URL aset atau muatan base64, dan beberapa metadata (seed, langkah, waktu). Saya menyimpan metadata, berguna ketika Anda ingin mereproduksi tampilan nanti.
Batas: Ukuran gambar, jumlah langkah, dan konkursi dibatasi. Default sudah cukup untuk draf, tetapi saya mencapai batas ketika mencoba meningkatkan resolusi. Lebih lanjut tentang batasan laju di bawah.

Versi pendeknya: jalur langsung jika Anda nyaman dengan REST. Triknya adalah mendapatkan beberapa hal membosankan (kunci, parameter, pengulangan) dengan benar sehingga Anda bisa melupakannya.

Kesederhanaan itu adalah bagian dari mengapa kami membangun WaveSpeed dengan cara kami. Saya menginginkan WAN 2.5 (dan model lainnya) terasa dapat ditulis skrip, tersertifikasi, dan membosankan dengan cara terbaik. Jika Anda menghubungkan ini sendiri, Anda dapat menjelajahinya di sini.

Auth & kunci

Saya membuat kunci API WaveSpeed di dasbor dan meletakkannya ke variabel lingkungan. Tidak ada yang mewah, tetapi itu menyelamatkan saya dari mengejar rahasia di seluruh file.

Dapatkan kunci dari pengaturan akun Anda di WaveSpeed. Ini terikat pada organisasi/proyek Anda.
Simpan secara lokal sebagai variabel env: WAVESPEED_API_KEY. Saya menggunakan file .env untuk dev dan penyimpanan rahasia CI untuk menjalankan.
Gunakan auth Bearer di header: Authorization: Bearer $WAVESPEED_API_KEY.
Jika Anda memutar kunci, lakukan selama jam lalu lintas rendah. Saya belajar dengan cara yang tenang ketika rotasi berjangka waktu mengganggu pekerjaan yang lama.

Jika tim Anda memerlukan kunci scoped, periksa pengaturan dasbor. Saya lebih suka rute privilege terendah untuk apa pun yang terikat pada otomasi. Satu gesekan kecil: jika Anda menjalankan dari beberapa mesin, beri label kunci dengan jelas berdasarkan host atau layanan, membantu ketika Anda mengaudit penggunaan nanti.

Parameter yang diperlukan

Nama yang tepat dapat berbeda menurut titik akhir, tetapi ini adalah bentuk minimal yang saya gunakan untuk Wan 2.5 di WaveSpeed. Anggap ini sebagai kerangka, konfirmasi nama bidang di dokumen resmi untuk akun Anda.

model: Saya menetapkan ini secara eksplisit ke wan-2.5 (atau string yang paling tepat dalam rencana Anda). Ini menjaga perilaku stabil di seluruh pembaruan.
input: String prompt. Saya membuatnya pendek dan konkrit. WAN cenderung merespons lebih baik terhadap frasing yang jelas dan sederhana daripada sup sifat.
mode atau task: Pembuatan gambar versus variasi/upscale. Jika Anda melewatkan gambar sumber, ini penting.
output: Saya minta URL gambar secara default. Base64 ada di sana, tetapi URL lebih baik untuk memori.

Ketika saya lupa menetapkan model secara eksplisit, saya mendapat default yang masuk akal, tetapi hasil saya bergeser halus di seluruh run. Tidak salah, hanya tidak dapat direproduksi. Mengunci versi menghilangkan guncangan itu.

Parameter opsional

Di sinilah kontrol sebenarnya berada. Saya hanya menyentuh segelintir pada hari pertama.

seed: Saya aktifkan setelah saya menyukai tampilan. Itu menstabilkan vibe untuk variasi.
steps: Langkah yang lebih tinggi dapat mendorong detail dengan mengorbankan waktu dan kredit. Saya meningkatkan dalam kenaikan kecil (misalnya, 24 → 32) dan menonton pengembalian.
guidance atau cfg_scale: Memperketat kepatuhan terhadap prompt. Terlalu tinggi dan itu menjadi rapuh.
size atau resolution: Di sinilah biaya melompat. Saya draf kecil, lalu jalankan ulang final pada ukuran target.
image: Untuk variasi, berikan URL gambar sumber atau unggah. Pasang dengan parameter kekuatan jika didukung.
safety atau moderation flags: Biarkan mereka aktif kecuali alur kerja Anda benar-benar membutuhkan penanganan khusus.
user atau metadata: Saya menambahkan ID permintaan atau tag proyek untuk melacak jalankan dalam log nanti.

Pengamatan kecil: mengubah dua tombol sekaligus membuat sulit untuk mengatakan apa yang membantu. Saya mengubah satu hal per run dan membuat catatan dalam komentar. Cara lama, tetapi berhasil.

Pola permintaan sampel

Saya mencoba tiga bentuk sederhana: curl cepat, skrip Python kecil, dan pekerjaan latar belakang untuk async.

Draf sinkron (curl)

Ini cukup untuk melakukan pemeriksaan akal untuk kunci dan prompt saya sebelum menghubungkan apa pun.

Contoh titik akhir, konfirmasi jalur yang tepat dalam dokumentasi untuk akun dan wilayah Anda:

POST https://api.wavespeed.ai/wan/v2.5/generations

Headers:

Authorization: Bearer $WAVESPEED_API_KEY
Content-Type: application/json

Body (minimal):

{
  "model": "wan-2.5",
  "input": "quiet studio light, sketch on kraft paper",
  "output": { "format": "url" }
}

Apa yang saya perhatikan:

200 dengan hasil dan metadata → Anda baik-baik saja.
202 dengan id pekerjaan → beralih ke alur async.
4xx → sesuatu dalam muatan atau auth mati.

Pembantu Python kecil

Saya menulis fungsi kecil untuk menangani header, timeout, dan json. Ini mengembalikan URL atau memunculkan pengecualian yang bersih. Tidak ada yang ajaib, hanya jenis pembungkus yang Anda tidak pikirkan dua kali.

Bit praktis:

Atur timeout koneksi pendek dan timeout baca sedikit lebih lama.
Tangani 429 dengan retry dan jitter.
Catat seed, langkah, dan ukuran untuk setiap run.

Alur asinkron (pekerjaan)

Untuk gambar yang lebih besar atau batch, saya mendapat 202 dan id pekerjaan. Lingkaran itu sederhana:

POST pekerjaan,

Poll GET /jobs/{id} setiap beberapa detik,
Berhenti pada status terminal (berhasil/gagal),
Ambil URL aset.

Jika tumpukan Anda menyukai webhook, WaveSpeed juga mengekspos callback. Saya tetap dengan polling pada awalnya, itu adalah satu bagian bergerak lebih sedikit selama setup.

Kode kesalahan

Saya menyimpan peta kecil di samping editor saya. Itu terbayar lebih cepat dari yang saya harapkan.

400 Bad Request: Biasanya nama bidang atau ketidakcocokan jenis. Saya sekali mengirim ukuran sebagai string, bukan objek. Perbaikannya jelas setelah saya memperlambat dan membaca pesan.
401 Unauthorized: Kunci hilang atau salah bentuk. Periksa header Bearer Anda dan spasi tertinggal.
403 Forbidden: Kunci ada tetapi kurang ruang lingkup untuk titik akhir atau tier model.
404 Not Found: Jalur titik akhir salah atau id pekerjaan yang kedaluwarsa.
409 Conflict: Anda kadang-kadang akan melihat ini saat memperbarui pekerjaan yang sudah diselesaikan. Poll lagi, jangan terus mendorong.
429 Too Many Requests: Anda melampaui batas per menit atau per-org. Mundur dengan retry eksponensial.
500/503 Server Errors: Jarang dalam tes saya, tetapi rencana untuk mereka. Lingkaran retry pendek membuat skrip saya tenang.

Kebiasaan kecil yang membantu: saya memasukkan kode kesalahan dan id permintaan (jika ada) ke dalam log saya. Ketika sesuatu terasa aneh, dukungan dapat menggunakan id itu untuk melacaknya.

Batasan laju

Saya terhenti pada batasan laju setelah saya menjadi malas dengan konkurensi. Mudah dilakukan, lebih mudah dihindari.

Apa yang berhasil:

Hormati header: Banyak titik akhir mengembalikan header laju (misalnya, sisa, waktu reset). Nama header dapat bervariasi, periksa dokumentasi, tetapi mereka patut dibaca.
Gunakan token bucket atau antrian sederhana. Saya membatasi skrip saya ke aliran kecil yang stabil daripada ledakan. Sistem bernafas lebih mudah, begitu juga saya.
Draf terpisah dari final. Draf dapat berjalan kecil dan cepat: final dapat berjalan satu demi satu di latar belakang.
Cache berulang. Jika Anda menguji prompt, simpan hasil sebelumnya selama beberapa menit sehingga Anda tidak membakar panggilan yang sama.

Saya juga membangun backoff yang sangat sederhana: penundaan dasar 1 detik, penggandaan pada setiap 429, dengan batas 30 detik dan maksimal 4 retry. Ini terasa tidak terburu-buru dan menghindari dogpiling layanan.

Perlindungan biaya

Ini adalah kekhawatiran utama saya. Pekerjaan gambar dapat menggigit kredit di latar belakang saat Anda sedang menyeduh teh.

Beberapa perlindungan yang saya atur pada hari pertama:

Batas anggaran di dasbor: Saya menetapkan batas bulanan dan peringatan email sedikit di bawahnya. Jika tim Anda berbagi kunci, peringatan membantu Anda menangkap loop lebih awal.
Batas per-permintaan: Saya memaksa ukuran dan langkah untuk hidup di bawah maksimum kecuali saya melewatkan bendera override. Ini menyelamatkan saya dari “oops, 4K semuanya.”
Alur kerja draf-pertama: Saya menjalankan pratinjau kecil (resolusi lebih rendah, langkah lebih sedikit) dan hanya upscale penjaga. Ini mengurangi pengeluaran saya lebih dari setengah pada sore pertama.
Disiplin benih: Setelah saya menemukan arah yang saya sukai, saya memperbaiki benih dan mengubah satu parameter sekaligus. Lebih sedikit run buta: lebih banyak yang disengaja.
Log dengan biaya: Jika respons mencakup bidang kredit atau penggunaan (beberapa titik akhir lakukan), simpan. Ketika itu tidak, perkirakan berdasarkan resolusi dan langkah dan catat bahwa itu adalah perkiraan.

Saya juga memasang saklar pembunuh lembut dalam skrip saya: jika penggunaan hari itu melampaui ambang batas, pekerjaan baru dijeda dan memposting pesan di Slack. Ini tidak elegan, tetapi jujur tentang batasan.

Ini tidak menghemat waktu pada awalnya. Ini menghemat perhatian. Setelah beberapa run, perlindungan memudar ke latar belakang, dan saya bisa berpikir tentang pekerjaan lagi daripada meteran.