Panduan media
Pembuatan Video
Buat video dari teks, gambar, audio, atau klip yang sudah ada
Pembuatan video bersifat asinkron. POST /v1/videos/generations mengembalikan ID tugas dan biasanya sebuah poll_url. Lakukan polling pada GET /v1/tasks/{id} dengan ID tersebut sampai video yang selesai siap.
Kirim URL HTTP(S) publik atau URL data yang didukung di kolom gambar yang diterima oleh model pilihan Anda. Input ini mengikuti jalur media normal dan tidak secara otomatis membuat ID material yang dapat digunakan kembali.
Ketika material eksplisit masih dalam persiapan, POST /v1/videos/generations mengembalikan 409 seedance_material_preparing dengan inactive_asset_ids. Lakukan polling pada aset tersebut hingga statusnya ACTIVE, lalu coba lagi dengan ID material yang sama. Jika sebuah aset berstatus FAILED, periksa error_message dan perbaiki atau impor ulang sebelum mencoba lagi.
Pilih API
Gunakan /v1/videos/generations untuk integrasi video baru. Klien Seedance 2.0 yang sudah ada yang mengirimkan content[] Volcengine atau permintaan Action dapat mempertahankan format tersebut melalui /api/v3. Kedua API menggunakan kunci Bearer TokenLab, namun kolom dan nilai statusnya berbeda.
Pilih apa yang akan dibuat
Tetapkan operation secara eksplisit agar API dapat memvalidasi kolom yang tepat untuk pekerjaan tersebut.
| Operasi | Input yang diperlukan atau umum | Kasus penggunaan |
|---|---|---|
text-to-video | prompt | Menghasilkan dari teks saja |
image-to-video | image_url atau image yang kompatibel | Menganimasikan gambar awal |
reference-to-video | reference_images dan opsional video_urls / audio_urls pada model yang didukung | Mempertahankan identitas, gaya, atau referensi aset |
start-end-to-video | start_image, end_image | Mengontrol bingkai pertama dan terakhir |
video-to-video | video_url atau task_id khusus model | Mengubah atau meningkatkan resolusi klip yang ada |
motion-control | image_url ditambah video_url | Menerapkan referensi gerakan ke subjek |
audio-to-video | audio_url | Alur video yang dikondisikan oleh audio |
video-extension | task_id, extend_at, atau kolom ekstensi khusus model | Melanjutkan video yang telah dibuat |
Pilih model
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
-H "Authorization: Bearer sk-your-api-key"Gunakan ID model yang dikembalikan oleh TokenLab, lalu pilih jenis pembuatan dengan operation dan input media yang sesuai. Jangan gunakan nama operasi sebagai ID model.
Baca detail model yang dipilih sebelum mengandalkan kolom khusus seperti reference_images, kling_elements, output_audio, duration, resolution, atau aspect_ratio.
Membuat video
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"operation": "text-to-video",
"prompt": "A calm cinematic shot of a cat walking through a sunlit garden",
"resolution": "720p",
"duration": 4,
"aspect_ratio": "16:9"
}'Gunakan URL https untuk media yang dapat diambil dari internet. URL sementara harus tetap valid sampai TokenLab membuat tugas tersebut.
Kolom khusus model
Perilaku audio bergantung pada model yang dipilih dan operasi. Video mungkin berisi suara meskipun tidak ada pemilih audio yang ditampilkan. Menghilangkan pemilih berbeda dengan mengirimkan false.
veo3.1,veo3.1-fast, danveo3.1-liteselalu menghasilkan audio. Hilangkanoutput_audioatau kirimtrue;falseakan ditolak.wan-2.6danwan-2.7selalu menyertakan audio. Hilangkanoutput_audioatau kirimtrue.wan-3.0danwan-3.0-primejuga selalu menyertakan audio dan tidak menggunakan pemilih audio.hailuo-h3menghasilkan audio asli dan tidak memiliki tombol senyap (mute). Jangan mengirim pemilih audio yang tidak tercantum dalam detail model.viduq3-prodanviduq3-turbomenghasilkan audio secara default; kirimoutput_audio: false(atauaudio: false) untuk output senyap. Model Seedance dan PixVerse menggunakanoutput_audio; kirim secara eksplisit alih-alih mengandalkan default. Gunakan hanya untuk operasi yang mencantumkannya.audio_url/audio_urlsmenyediakan input atau referensi audio. Ini bukan tombol untuk output audio. Penyuntingan video, transfer gerakan, dan transfer gaya mungkin mempertahankan jalur suara input; mempertahankan audio sumber tidak berarti membisukannya.
Periksa detail model untuk nilai yang diizinkan dan harga yang bergantung pada audio. Jika model mencantumkannya, alias outputAudio, generate_audio, dan boolean audio harus sesuai dengan output_audio saat digabungkan. Jangan berasumsi bahwa setiap versi atau operasi dalam satu keluarga model memiliki kontrol audio yang sama.
- Untuk keluarga Seedance 2.0, baca panduan model video Seedance 2.0 sebelum menggunakan output 4K, batas resolusi Fast/Mini, atau input referensi multimodal.
- Untuk
grok-imagine-videovideo-to-video, kirimpromptdanvideo_urlHTTPS publik berformat.mp4. URL hasil.mp4TokenLab dari tugas sebelumnya dapat digunakan. Operasi ini tidak menggunakan pemilihduration,resolution, atauaspect_ratio.
PixVerse dan HappyHorse
| Model | Operasi | Input | Resolusi | Durasi | Pemilih audio |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | Bilangan bulat dari 1 hingga 15 detik | output_audio, default false |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | Field yang sama dengan C1 dan V6 | 360p, 540p, 720p, 1080p | 5, 8, atau 10 detik; 1080p mendukung 5 atau 8 detik | output_audio, default false |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 3 hingga 15 detik untuk operasi generasi; output video-to-video dibatasi maksimal 15 detik | Jangan kirim output_audio |
Di TokenLab, model-model PixVerse di atas tidak mendukung operation=video-extension.
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"operation": "image-to-video",
"prompt": "A slow camera move through a neon-lit street",
"image_url": "https://example.com/start.jpg",
"resolution": "1080p",
"duration": 5,
"output_audio": true
}'Dapatkan video yang sudah selesai
Panggil GET /v1/tasks/{id} dengan id atau task_id dari respons pembuatan sampai tugas berstatus completed atau failed.
Tugas video yang selesai mungkin mengembalikan video_url, video, atau videos tergantung pada model dan jumlah output. Perlakukan billing_transaction_id sebagai pengenal penagihan, bukan sebagai pengenal tugas.
URL hasil video adalah URL hasil media TokenLab yang diakhiri dengan jenis file, seperti .mp4, dan tetap valid selama 30 hari. media_retention.items melaporkan status penyimpanan setiap item dan expires_at; respons dapat menghilangkan media_retention jika status penyimpanan tidak diketahui tepat waktu, dan URL tersebut tetap berfungsi. Tugas yang gagal dan sedang berlangsung mengembalikan kolom URL video kosong. Snapshot tugas asinkron memiliki siklus hidup terpisah. Lihat Retensi data.
Kendala Umum
- Jangan gunakan jalur status per-modalitas seperti
/v1/videos/generations/{id}dalam kode baru; lakukan polling padaGET /v1/tasks/{id}. - Jangan menggabungkan kolom bingkai pertama dengan alur gambar referensi khusus kecuali detail model mengizinkannya.
- Jangan berasumsi bahwa
durationmenjelaskan panjang video referensi input; biasanya ini mengontrol panjang output yang dihasilkan. - Kirim
Idempotency-KeydenganPOST /v1/videos/generations. Setelah waktu tunggu habis, kirim permintaan yang sama dengan kunci yang sama untuk mendapatkan tugas asli. Tanpa kunci, periksa apakah tugas sudah dibuat sebelum Anda mencoba lagi.
Referensi API
| Topik | Referensi |
|---|---|
| Buat Video | Buat Video |
| Dapatkan Status Video | Dapatkan Status Video |
| Dapatkan Status Tugas | Dapatkan Status Tugas |
| Batalkan Tugas | Batalkan Tugas |
| Penagihan & Harga | Penagihan & Harga |
Hailuo H3-Max menghasilkan video berdurasi 5–15 detik pada 480p atau 768p dari teks, bingkai pertama, atau bingkai pertama dan terakhir. Alur kerja yang berfokus pada kecepatan ini berguna untuk mengubah ide pengambilan gambar menjadi klip pendek dengan cepat.
{
"model": "hailuo-h3-max",
"operation": "text-to-video",
"prompt": "A slow camera move through a quiet garden",
"resolution": "768p",
"duration": 5,
"aspect_ratio": "16:9"
}