Video & materi
Create Video
Memulai tugas pembuatan video
Ringkasan
Pembuatan video bersifat asinkron. Permintaan pembuatan yang berhasil akan mengembalikan id tugas (nilai yang sama dengan task_id) dan poll_url. Panggil GET /v1/tasks/{id} dengan ID tersebut sampai status menjadi completed atau failed, kemudian baca video_url. Lihat Dapatkan Status Video.
- File hasil disimpan selama 30 hari. Unduh file tersebut jika Anda membutuhkannya lebih lama; lihat Retensi data.
- Tugas Seedance yang berada dalam antrean dapat dibatalkan dengan Batalkan Tugas.
- Biaya dapat dicadangkan saat tugas diterima dan diselesaikan saat tugas selesai atau gagal. Lihat Penagihan & Harga.
- Kirim header
Idempotency-Keyuntuk mencoba kembali permintaan pembuatan dengan aman setelah timeout.
Setiap model menerima operasi dan bidangnya masing-masing. GET /v1/models/{model} (Dapatkan Model) mencantumkan, untuk setiap operasi, bidang yang diterima, resolusi, durasi, dan rasio aspek. Bidang atau nilai di luar daftar tersebut akan mengembalikan 400 dengan nilai yang diterima. Atur duration, resolution, aspect_ratio, dan output_audio sendiri: jika Anda melewatkan salah satunya, TokenLab akan menggunakan default model untuk operasi tersebut, dan jika tidak ada default yang cocok, permintaan akan mengembalikan 400 dan menyebutkan bidang yang perlu diatur.
Input Audio dan Media
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.
Gunakan URL https yang dapat diakses publik untuk gambar, video, dan audio, serta pastikan URL tersebut valid hingga tugas dimulai. URL media dapat memiliki panjang hingga 8.192 karakter. Beberapa model juga menerima URL gambar data: inline (hingga 2.000.000 karakter per bidang); URL lebih andal untuk file besar. Jangan mencampur base64 inline dan URL jarak jauh dalam permintaan yang sama.
Body Permintaan
veo3.1ID model video. Cantumkan model video saat ini dengan Daftar model (recommended_for=video), lalu kirim model secara eksplisit.
PixVerse
- Model:
pixverse-c1,pixverse-v6,pixverse-v5.6 - Operasi:
text-to-video,image-to-video,start-end-to-video,reference-to-video - Pemilih audio:
output_audio, defaultfalse
Di TokenLab, model-model PixVerse di atas tidak mendukung operation=video-extension.
HappyHorse
- Model:
happyhorse-1.0 - Operasi:
text-to-video,image-to-video,reference-to-video,video-to-video - Pemilih audio: Jangan kirim
output_audio
Deskripsi teks video, hingga 10.000 karakter. Sebagian besar operasi memerlukan deskripsi ini; detail model akan menjelaskan mana yang tidak memerlukannya.
Mode pembuatan: text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, atau motion-control. Setiap model hanya mendukung beberapa di antaranya; yang lainnya akan mengembalikan 400 unsupported_operation. Jika Anda mengabaikannya, TokenLab akan menyimpulkannya dari input: task_id dengan extend_at atau extend_times menghasilkan video-extension, gambar atau materi referensi menghasilkan reference-to-video, end_image menghasilkan start-end-to-video, input video menghasilkan video-to-video, input gambar (image, image_url, image_urls atau start_image) menghasilkan image-to-video, dan selain itu text-to-video. Kirimkan secara eksplisit agar kolom yang tidak cocok dapat gagal lebih awal.
URL yang dapat diakses publik untuk gambar bingkai pertama. Model Seedance 2.0 juga menerima asset://asset-YYYYMMDDHHMMSS-xxxxx untuk menggunakan materi TokenLab yang ACTIVE sebagai bingkai pertama. Gunakan URL https untuk dukungan model yang lebih luas.
Gambar inline sebagai data URL (contoh: data:image/jpeg;base64,...). Hanya beberapa model yang menerimanya; image_url berfungsi pada lebih banyak model.
URL gambar untuk model yang mencantumkan bidang ini. Lihat reference_images untuk batas jumlah.
Gambar referensi untuk reference-to-video, sebagai URL https atau data URL. Batas jumlah bergantung pada model:
seedance-2.0,seedance-2.0-fast, danseedance-2.0-mini: hingga 9 referensi gambar secara total, termasuk aset materi. Lebih dari itu akan mengembalikan400 too_many_seedance_reference_images.seedance-2.5: hingga 30 input gambar secara total di seluruhimage_urlsdanreference_images.grok-imagine-video: hingga 7, dandurationdibatasi maksimal 10 detik.grok-imagine-video-1.5dangrok-imagine-video-1.5-previewtidak menerima gambar referensi.- Model lain: lihat detail model. Permintaan yang melebihi batas akan mengembalikan
400 too_many_items.
Model Seedance 2.0 juga menerima asset://asset-YYYYMMDDHHMMSS-xxxxx untuk materi TokenLab yang ACTIVE. Untuk pemilihan model, batas 4K, dan catatan Mini, lihat Panduan model video Seedance 2.0. Untuk grok-imagine-video, jangan gabungkan gambar referensi dengan image_url atau image.
Gambar bingkai pertama. Dengan end_image, permintaannya adalah start-end-to-video. Tanpa end_image, permintaannya adalah image-to-video, dan start_image berfungsi seperti image pada model yang kontraknya mencantumkannya. Menerima URL publik atau data URL; model Seedance 2.0 juga menerima asset://asset-YYYYMMDDHHMMSS-xxxxx.
Gambar bingkai terakhir untuk start-end-to-video. Menerima input yang sama dengan start_image.
ID aset materi TokenLab Seedance yang dikembalikan oleh Buat Aset Materi. Hanya diterima oleh model Seedance 2.0; model lain akan mengembalikan 400 unsupported_seedance_material_asset_model. Aset harus berstatus ACTIVE dan milik akun Anda. Bidang ini adalah input referensi generik; untuk menetapkan makna bingkai pertama, bingkai terakhir, atau gambar referensi secara eksplisit, masukkan asset://<material_asset_id> di start_image, end_image, atau reference_images.
Hingga 9 ID aset materi TokenLab Seedance. ID ini dihitung dalam batas 9 referensi gambar pada model Seedance 2.0.
URL gambar biasa diteruskan sebagai input gambar; URL tersebut tidak membuat aset materi yang dapat digunakan kembali. Buat aset yang dapat digunakan kembali melalui API materi, lalu gunakan ID TokenLab atau URI asset://asset-YYYYMMDDHHMMSS-xxxxx milik aset tersebut. Jika materi eksplisit mengembalikan 409 seedance_material_preparing, periksa inactive_asset_ids yang dikembalikan dan coba lagi setelah materi tersebut menjadi ACTIVE.
URL yang dapat diakses publik untuk video sumber, bagi operasi yang memerlukannya: video-to-video, video-extension, dan motion-control, pada model yang mencantumkan bidang ini.
Video sumber atau referensi untuk model yang mencantumkan bidang ini. seedance-2.5 menerima hingga 10 input video secara total di seluruh video_url dan video_urls. Lihat detail model untuk model lainnya.
URL audio publik untuk referensi audio atau operasi berbasis audio, pada model yang mencantumkan bidang ini. Ini adalah input, bukan sakelar output audio.
Audio referensi untuk model yang mencantumkan bidang ini. seedance-2.5 menerima hingga 10 input audio secara total di seluruh audio_url dan audio_urls serta mengizinkan permintaan dengan referensi audio tanpa prompt. Untuk seedance-2.5, audio referensi ditambah video referensi maksimal berdurasi 30 detik secara gabungan.
ID tugas sebelumnya di ruang kerja Anda, untuk video-extension pada model yang mencantumkan bidang ini. Tugas yang bukan milik ruang kerja Anda akan mengembalikan 403 task_not_owned.
Detik dari video sumber di mana video-extension dimulai. Diperlukan oleh grok-imagine-video.
Detik untuk ditambahkan dalam video-extension, pada model yang mencantumkan bidang ini. grok-imagine-video menerima 6 atau 10.
Durasi output dalam detik. Nilai yang diizinkan bergantung pada model dan operasi; nilai lain akan mengembalikan 400 invalid_duration. Model Seedance juga menerima -1 agar model memilih durasi dalam rentangnya; penagihan kemudian diestimasi secara konservatif hingga tugas selesai. Beberapa operasi tidak memerlukan durasi, seperti motion-control dan grok-imagine-video video-to-video.
Alias kompatibilitas untuk duration. Jika keduanya dikirim, nilainya harus identik.
Rasio aspek, contoh 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, atau adaptive (Seedance). Nilai yang diizinkan bergantung pada model dan operasi; nilai lain akan mengembalikan 400 invalid_aspect_ratio.
Resolusi output, contoh 480p, 720p, 1080p, atau 4k. Nilai yang diizinkan bergantung pada model dan operasi, dan beberapa model juga menggunakan 360p, 540p, atau 768p. Nilai lain akan mengembalikan 400 invalid_resolution.
Pemilih output audio untuk operasi yang mencantumkannya. Jika dilewati, akan mengikuti default model; false meminta output senyap hanya jika model mengizinkannya. Lihat catatan audio di atas dan detail model yang dipilih.
Format kontainer, mp4 atau mov, untuk model yang mencantumkan bidang ini, seperti seedance-2.5. Lewati untuk model yang tidak mencantumkannya.
Juga mengembalikan bingkai terakhir yang dihasilkan sebagai last_frame_url. Hanya model Seedance.
Toggle watermark untuk model yang mencantumkan bidang ini (model Seedance).
Hal yang harus dihindari dalam video yang dihasilkan, hingga 5.000 karakter, untuk model yang mencantumkan bidang ini.
Seed untuk pembuatan yang dapat direproduksi, untuk model yang mencantumkan bidang ini. Model Seedance 2.0 menerima -1 untuk seed acak; seedance-2.5 tidak menerima bidang ini.
Bingkai per detik (1-120), untuk model yang mencantumkan bidang ini.
Jumlah bingkai, untuk model yang mencantumkan bidang ini. Model Seedance tidak menerimanya.
Detik tugas dapat menunggu dalam antrean sebelum kedaluwarsa (3600 hingga 259200), untuk model Seedance.
Prioritas tugas dari 0 hingga 9, untuk model Seedance. Jangan gabungkan dengan service_tier=flex.
default diterima sebagai no-op kompatibilitas pada model Seedance 2.0 dan 2.5. flex ditolak pada model tersebut.
Pengidentifikasi keamanan pengguna akhir (hingga 128 karakter), untuk model Seedance. Jika dilewati, TokenLab menggunakan user jika disediakan.
Alat yang mungkin digunakan model saat membuat, untuk model Seedance 2.0 dan 2.5. Alat yang didukung adalah {"type": "web_search"}.
Pengidentifikasi unik untuk pengguna akhir. Untuk model Seedance, TokenLab juga menggunakannya sebagai safety_identifier jika bidang tersebut dilewati.
Nama Bidang yang Kompatibel
- Bidang utama menggunakan snake_case:
aspect_ratio,output_audio, danreference_images. - Untuk kompatibilitas, TokenLab juga menerima
ratio,generate_audio,outputAudio,seconds, danreferenceImages. - Jika bidang utama dan aliasnya dikirim bersamaan, nilainya harus cocok. Ketidakcocokan akan mengembalikan
400denganconflicting_audio_selector,conflicting_duration, atauconflicting_aspect_ratio.
Parameter Seedance
Model Seedance (seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, dan seedance-2.5) menerima nama bidang TokenLab di atas dan alias seconds, ratio, dan generate_audio. Versinya berbeda:
| Model Seedance 2.0 | seedance-2.5 | |
|---|---|---|
| Resolusi | seedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast dan seedance-2.0-mini: 480p, 720p | 480p, 720p |
| Durasi | -1, 4 hingga 15 detik | -1, 4 hingga 30 detik |
| Rasio aspek | 1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptive | Sama untuk text-to-video dan reference-to-video. Image-to-video, start-end, pengeditan video, dan ekstensi memerlukan adaptive; pengeditan video juga memerlukan duration=-1 |
| Format output | mp4 | mp4 atau mov |
seed | Diterima | Tidak diterima |
| Input referensi | 9 referensi gambar termasuk materi (materi hanya diterima pada model ini) | 30 gambar, 10 video, dan 10 file audio secara total |
Detail model adalah sumber saat ini untuk nilai-nilai ini. Kirim duration, resolution, aspect_ratio, dan output_audio secara eksplisit alih-alih mengandalkan default; recommended_request model menunjukkan permintaan yang umum.
duration=-1 atau seconds=-1 membiarkan Seedance memilih durasi output dalam rentang model. TokenLab mengestimasi biaya secara konservatif sebelum tugas selesai, kemudian diselesaikan dari penggunaan tugas yang telah selesai saat tersedia. service_tier=flex dan frames ditolak pada model ini.
Contoh Seedance
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "A sleek product reveal with cinematic camera movement",
"operation": "text-to-video",
"duration": -1,
"aspect_ratio": "adaptive",
"resolution": "720p",
"output_audio": true
}'Respons
Bidang yang menjelaskan hasil, kesalahan, stempel waktu, dan model dikembalikan jika tersedia untuk tugas tersebut.
ID Tugas. Identik dengan task_id.
ID tugas untuk melakukan polling dengan GET /v1/tasks/{id}.
URL status untuk tugas ini, /v1/tasks/{id}. Panggil dengan API key Anda.
Status tugas: pending, processing, completed, failed. Tugas baru biasanya berstatus pending.
Stempel waktu Unix saat tugas dibuat.
Model yang digunakan.
ID transaksi penagihan saat penyelesaian sudah selesai. Ini terpisah dari ID tugas.
URL video, hanya ada saat respons pembuatan sudah membawa hasil. Biasanya Anda membacanya dari respons status.
Pesan kesalahan atau objek kesalahan terstruktur saat tugas gagal.
Kesalahan
| Status dan kode | Arti |
|---|---|
400 invalid_request | Bidang salah format, di luar rentang, atau hilang. error.param menyebutkan bidang tersebut. Pesan seperti "Set aspect_ratio explicitly" berarti bidang yang dilewati tidak memiliki default untuk permintaan ini. |
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_long | Permintaan tidak cocok dengan apa yang diterima model untuk operasi tersebut. Kesalahan biasanya mencantumkan nilai yang diterima. |
400 invalid_parameter | Input tidak sesuai dengan operasi, contoh gambar dikirim dengan text-to-video. |
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratio | Alias dan bidang utamanya tidak cocok. |
400 unpriceable_selection | Kombinasi yang dipilih tidak memiliki harga. Ubah resolution, duration, aspect_ratio, atau pengaturan audio. |
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_model | Terlalu banyak referensi gambar untuk model Seedance 2.0, atau materi dikirim ke model lain. |
402 | Saldo tidak mencukupi. |
403 task_not_owned | task_id milik ruang kerja lain. |
409 seedance_material_preparing, seedance_material_route_unavailable | Materi belum ACTIVE, atau model yang dipilih tidak dapat menggunakan materi yang disediakan. |
429 | Batas kecepatan terlampaui. Lihat Batas kecepatan. |
Permintaan
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"prompt": "A cat walking through a garden, cinematic lighting",
"operation": "text-to-video",
"duration": 4,
"resolution": "720p",
"aspect_ratio": "16:9"
}'Respons
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000
}Gambar ke Video
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "hailuo-2.3",
"prompt": "The scene begins from the provided image and adds gentle natural motion.",
"operation": "image-to-video",
"image_url": "https://example.com/image.jpg",
"duration": 6,
"resolution": "768p"
}
)Referensi ke Video
Gunakan operation=reference-to-video saat model mendukung pengkondisian referensi khusus. Referensi gambar dimasukkan ke reference_images; model yang menerima video dan audio referensi menggunakan video_urls dan audio_urls. duration hanya mengatur panjang output yang dihasilkan. Ini tidak membatasi panjang input video referensi. Lihat reference_images di atas untuk batas jumlah per model.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "veo3.1",
"prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
"operation": "reference-to-video",
"reference_images": [
"https://example.com/ref-a.jpg",
"https://example.com/ref-b.jpg"
],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}
)Kontrol Keyframe
Gunakan start_image dan end_image untuk mengontrol bingkai pertama dan terakhir:
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "viduq2-pro",
"operation": "start-end-to-video",
"start_image": "https://example.com/day.jpg",
"end_image": "https://example.com/night.jpg",
"duration": 5,
"resolution": "720p"
}
)Video ke Video
Gunakan operation=video-to-video saat model menerima video yang ada sebagai input utama. Untuk grok-imagine-video, kirim URL .mp4 HTTPS publik di video_url dan prompt pengeditan, serta lewati resolution, duration, dan aspect_ratio.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "grok-imagine-video",
"operation": "video-to-video",
"video_url": "https://example.com/source.mp4",
"prompt": "Enhance the clip while preserving the original motion."
}
)Ekstensi Video
Gunakan operation=video-extension untuk melanjutkan hasil sebelumnya. Kirim task_id dari tugas di ruang kerja Anda dan prompt; bidang lainnya bergantung pada model. grok-imagine-video juga memerlukan extend_at dan menerima extend_times sebesar 6 atau 10. veo3.1 dan veo3.1-fast menerima task_id dan prompt. Model Seedance mencantumkan video_url, video_urls, dan task_id untuk operasi ini.
Kontrol Gerakan
Gunakan operation=motion-control saat model mengharapkan gambar subjek dan video referensi gerakan. Kirim image_url dan video_url; resolution diperlukan.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "kling-3.0-motion-control",
"operation": "motion-control",
"prompt": "Keep the subject identity stable while following the motion reference.",
"image_url": "https://example.com/subject.png",
"video_url": "https://example.com/motion.mp4",
"resolution": "720p"
}
)Penemuan Model
Inventaris video publik dan operasi yang didukung berubah seiring waktu. Gunakan Models API untuk memeriksa dukungan saat ini sebelum Anda menyusun alur khusus model:
curl "https://api.tokenlab.sh/v1/models?recommended_for=video"
curl "https://api.tokenlab.sh/v1/models/veo3.1"Baca respons detail model sebelum mengandalkan operasi atau bidang khusus model. Operasi seperti video-extension dan motion-control bersifat spesifik untuk model; konfirmasikan ketersediaan saat ini di sana alih-alih mengandalkan contoh statis di halaman ini.
Otorisasi
BearerAuth Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.
Lokasi: header
Header
Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.
Nilai yang tersedia
- "auto"
- "verified"
- "official"
Kunci opsional yang membuat permintaan pembuatan aman untuk dicoba ulang. Kirim nilai unik baru, seperti UUID, untuk setiap tugas. Percobaan ulang dengan kunci dan body yang sama akan mengembalikan hasil dari permintaan pembuatan asli, biasanya berupa tugas asli, dan tidak akan membuat, mengirim, atau mengenakan biaya untuk tugas kedua. Body yang berbeda dengan kunci yang sudah diterima akan ditolak dengan 409. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak akan memiliki perlindungan idempotensi. Lihat Retry safely with an idempotency key.
1 <= length <= 255Body permintaan
application/json
Respons
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json