WaveSpeedAI

Genjutsu API: Kirim Satu Video Object Swap

Gunakan Genjutsu API untuk satu permintaan Object Swap: siapkan klip sumber, kirim tugasnya, lalu ambil video hasil editnya.

By John6 min read
Genjutsu API: Kirim Satu Video Object Swap

Fitur penyuntingan video bisa mengembalikan job yang berhasil, tetapi tim Anda tetap mendapat aset yang tidak bisa dipakai: bagian klip yang salah diproses, penggantinya bergeser antar frame, atau tidak ada yang menyimpan hasilnya. Untuk integrasi Genjutsu API, saya akan membuat satu pengeditan dapat dilacak dari input sampai file yang disetujui. Panduan memulai API Higgsfield menjelaskan alur kirim–polling–ambil hasil; panduan ini menerapkannya pada satu permintaan Object Swap.

Higgsfield menyediakan model dan endpoint-nya. Jika produk Anda menggunakan WaveSpeedAI, periksa direktori modelnya untuk operasi persis ini beserta skema permintaannya sendiri. Jangan berasumsi model video-swap lain menerima permintaan Higgsfield.

Apa yang Dibutuhkan Satu Permintaan Genjutsu Object Swap?

Satu permintaan membutuhkan URL video sumber dan satu hingga delapan URL gambar referensi. Prompt bersifat opsional. resolution secara default 720p; 480p dan 1080p juga tercantum. Referensi API Object Swap mengidentifikasi model ini sebagai higgsfield/genjutsu/object-swap/v1.0. Model ini mensyaratkan video berdurasi minimal empat detik dan minimal 409.600 piksel per frame.

Periksa klip sebelum mengirimkannya. Video yang lebih panjang dari 30 detik dipotong menjadi 30 detik, dan hasilnya mengikuti durasi yang sudah disiapkan itu. Jika pengeditan yang dimaksud terjadi pada detik ke-34, permintaan yang berhasil tetap tidak dapat menghasilkannya. Pilih segmennya terlebih dahulu, lalu catat segmen mana yang Anda kirim.

Permintaan dari sisi server dapat berbentuk seperti berikut. URL dan variabel lingkungan hanya sebagai ilustrasi:

curl -X POST \
  "https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
  -H "Authorization: Key ${HF_KEY}" \
  -H "Idempotency-Key: ${EDIT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/approved-source.mp4",
    "image_urls": ["https://example.com/approved-object.png"],
    "prompt": "Replace the featured cup with the reference cup.",
    "resolution": "720p"
  }'

Simpan kredensial di server Anda. Beri setiap pengeditan logis kunci idempotensi yang stabil, sehingga pengiriman yang ambigu dapat dicoba ulang tanpa sengaja membuat job kedua. Jika sumber menampilkan orang yang dapat diidentifikasi, atau menggunakan rekaman atau karya seni yang dilindungi, dapatkan hak dan persetujuan yang diperlukan sebelum mengunggahnya. Ini adalah pengingat untuk produksi, bukan nasihat hukum.

Kirim Pengeditan dan Lacak Statusnya

POST yang berhasil berarti pekerjaan diterima; bukan berarti video jadi dikembalikan. Simpan request_id, status_url, dan cancel_url dari respons pada catatan pengeditan produk Anda. Gunakan URL yang dikembalikan itu, jangan membuatnya sendiri.

Dokumentasi siklus permintaan Higgsfield mencantumkan queued dan in_progress sebagai status non-terminal. Berhenti menunggu ketika status menjadi completed, failed, nsfw, atau canceled. Tampilkan hasil-hasil tersebut secara terpisah di UI Anda. “Masih diproses” adalah umpan balik yang buruk ketika penyedia sudah menolak job-nya.

Mulai polling dengan interval sekitar dua detik, lalu perpanjang interval untuk penantian yang lebih lama. Jika pengecekan status mengalami error jaringan sementara, ulangi pengecekan status tersebut. Jangan melakukan POST pengeditan lagi hanya karena satu poll gagal. Simpan status akhir dan error yang dikembalikan bersama ID permintaan, agar tim dukungan dapat membedakan generasi yang gagal dari sesi browser yang berakhir lebih awal.

Ambil dan Periksa Video yang Sudah Selesai

Ketika status completed, baca video.url dari hasilnya. Unduh file ke penyimpanan yang Anda kendalikan, lalu periksa bahwa file dapat diputar dan sesuai dengan pengeditan yang dimaksud. Job API yang selesai adalah kandidat pengiriman, bukan keputusan persetujuan.

Tinjau lebih dari sekadar thumbnail. Periksa penggantinya di awal, tengah, dan akhir klip, terutama saat objek bergerak ke belakang subjek lain atau melintasi frame. Bandingkan durasi yang diproses dengan segmen yang Anda kirim. Jika suara penting bagi fitur Anda, periksa juga trek audio keluarannya; referensi Object Swap tidak menjanjikan audio sumber dipertahankan.

Satu hasil yang bagus tidak berarti alur kerja produksi sudah siap. Penyelesaian dari penyedia hanya menyatakan bahwa sebuah file ada. Pemeriksaan penerimaan Anda yang menentukan apakah file itu boleh masuk ke produk.

Membuat Object Swap Dapat Direproduksi di Produksi

Simpan Manifes Pengeditan yang Dapat Diputar Ulang

Simpan versi aset sumber, rentang waktu yang dipilih, versi gambar referensi, prompt, resolusi, ID model, kunci idempotensi, ID permintaan, dan status akhir dalam satu tempat. Tambahkan lokasi penyimpanan hasil yang disetujui. Satu orang bisa mengingat parameter. Sebuah tim tidak bisa.

Catatan ini membantu ketika seorang editor meminta “swap yang sama, tapi dengan produk biru.” Tim dapat mengubah satu input secara sengaja, alih-alih merekonstruksi permintaan sebelumnya dari file bernama final-v3.mp4.

Arsipkan Video Asli dan Hasil yang Disetujui

Simpan klip asli untuk rollback, dan simpan hasil yang disetujui di luar lokasi media sementara milik penyedia. Ketentuan API tentang retensi dan persetujuan Higgsfield menyatakan media yang dihasilkan tersedia selama minimal tujuh hari, tetapi dapat dihapus setelahnya. Itu bukan jaminan URL permanen. Catat apakah hasil diterima, ditolak, atau dikembalikan untuk revisi, beserta alasannya.

FAQ

Apakah Object Swap mempertahankan audio dari klip sumber?

Referensi Object Swap yang dipublikasikan tidak menyebutkannya. Jangan menjanjikan audio passthrough di produk Anda. Uji dengan klip yang diotorisasi dan memiliki trek audio yang mudah dikenali, lalu periksa file yang dikembalikan sebelum membuat klaim fitur tersebut.

Bisakah permintaan Genjutsu yang masih antre dibatalkan?

Bisa, selama permintaan masih memenuhi syarat di antrean. Kirim permintaan pembatalan ke cancel_url yang dikembalikan; sekadar menghentikan poller Anda tidak membatalkan job. Setelah pemrosesan dimulai, pembatalan tidak lagi tersedia menurut siklus yang didokumentasikan.

Apa yang terjadi jika URL sumber kedaluwarsa selama persiapan?

Dokumentasi tidak menentukan satu titik kegagalan universal untuk URL input Object Swap yang kedaluwarsa. Pastikan sumber tetap dapat diakses selama Higgsfield mungkin perlu mengambilnya. Jika persiapan gagal, catat status permintaan dan error yang sebenarnya. Diterimanya POST tidak membuktikan bahwa file sudah diunduh.

Apakah kegagalan persiapan input menghabiskan unit penagihan?

Tergantung pada kegagalan yang dilaporkan. Panduan penagihan dan retensi Higgsfield menyatakan permintaan yang berakhir failed atau nsfw tidak dikenai biaya dan kredit yang dicadangkan dikembalikan. “Kegagalan persiapan input” bukan status penagihan tersendiri, jadi periksa respons dan catatan penagihan, jangan menerapkan aturan yang sama pada setiap error semacam itu.

Berapa lama URL video yang sudah selesai tetap tersedia?

Media yang dihasilkan dapat diakses minimal tujuh hari dan mungkin dihapus setelahnya. Unduh video yang disetujui sesegera mungkin. Untuk fitur Genjutsu API yang mungkin dikunjungi kembali pengguna berminggu-minggu kemudian, sajikan salinan yang sudah disimpan dari penyimpanan Anda sendiri.


Postingan sebelumnya:

Bagikan