Langsung ke konten utama

​
Ringkasan

Generasi video berjalan secara asinkron. Anda mengirim permintaan, menerima task_id dan poll_url, lalu memeriksa status secara berkala sampai hasil akhirnya siap.

​
Perilaku polling

Untuk perilaku pengecekan status yang paling andal, gunakan poll_url yang dikembalikan oleh respons pembuatan secara persis. Jika respons create mengembalikan poll_url, panggil URL tersebut secara persis. Saat URL itu mengarah ke /v1/tasks/{id}, perlakukan itu sebagai endpoint status tetap yang kanonik.

​
Perilaku model dan media

Output audio bergantung pada model. Di TokenLab, permintaan Veo 3 dan Seedance secara default mengaktifkan audio saat output_audio tidak dikirim. Jika model mendukung kontrol audio, gunakan output_audio untuk mengaktifkan atau menonaktifkannya secara eksplisit. Alias outputAudio dan generate_audio diterima untuk kompatibilitas dan harus sama dengan output_audio jika lebih dari satu field dikirim. Untuk integrasi produksi, sebaiknya gunakan URL https publik untuk gambar, video, dan audio. Model yang kompatibel masih menerima URL data:, tetapi muatan base64 yang besar lebih sulit untuk dicoba ulang, diinspeksi, dan di-debug.

​
Request body

​
model
string
default:"veo3.1"
ID model video. Gunakan ID model yang ditampilkan TokenLab seperti veo3.1, wan-2.7, happyhorse-1.0, viduq3, pixverse-v6, atau kling-3.0-video; pilih text-to-video, image-to-video, reference-to-video, atau varian lain dengan operation. Lihat panduan video dan Models API.
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, default false
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
​
prompt
string
wajib
Deskripsi teks video yang ingin Anda hasilkan. Field ini wajib untuk sebagian besar model video publik.
​
operation
string
Operasi video yang akan dijalankan. Kontrak publik mendukung text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video, dan motion-control. TokenLab bisa menebak operasi berdasarkan input yang Anda kirim, tetapi untuk traffic produksi sebaiknya operation dikirim secara eksplisit.
​
image_url
string
URL publik dari gambar awal untuk alur image-to-video. Untuk kompatibilitas lintas-model yang paling luas, sebaiknya gunakan image_url.
​
image
string
Gambar inline dalam bentuk URL data: (misalnya data:image/jpeg;base64,...). Model yang kompatibel mendukung format ini, tetapi dalam praktik produksi image_url biasanya lebih stabil.
​
reference_images
array
Gambar referensi untuk alur dengan conditioning khusus. Jumlah yang didukung bergantung pada model. Untuk seedance-2.0 dan seedance-2.0-fast, TokenLab saat ini mendukung hingga 9 gambar referensi, ditambah hingga 3 video referensi dan 3 audio referensi. Untuk pilihan model, batas 4K, dan catatan Mini, lihat panduan model video Seedance 2.0. URL publik https lebih disarankan; model yang kompatibel juga menerima URL data:. Untuk grok-imagine-video, reference-to-video menerima hingga 7 referensi gambar dan duration dibatasi maksimal 10 detik. grok-imagine-video-1.5-preview hanya mendukung image-to-video dan tidak menerima referensi gambar.
​
material_asset_id
string
ID material Seedance TokenLab yang dikembalikan oleh Create Material Asset atau persiapan gambar otomatis. Gunakan setelah material menjadi ACTIVE dengan model Seedance yang dapat menggunakan pustaka material TokenLab.
​
material_asset_ids
array
Beberapa ID material Seedance TokenLab. ID ini berbagi batas referensi gambar Seedance yang sama dengan reference_images; model yang dipilih harus dapat menggunakan pustaka material TokenLab.
Jika model Seedance yang dipilih dapat menggunakan pustaka material TokenLab, TokenLab menyiapkan field gambar (image, image_url, image_urls, reference_images, start_image, end_image) sebagai material yang dapat digunakan ulang sebelum generasi. Jika belum selesai dalam 60 detik, API mengembalikan 409 seedance_material_preparing dengan auto_material_asset_ids; coba lagi setelah material tersebut menjadi ACTIVE. Jika model yang dipilih tidak dapat menggunakan pustaka material, input gambar biasa tetap berjalan melalui jalur gambar normal dan ID material eksplisit gagal secara aman dengan error ketersediaan material yang dapat dicoba ulang.
​
reference_image_type
string
Field opsional untuk model yang membedakan referensi asset dan style.
​
kling_elements
array
Definisi referensi elemen Kling 3.0. Hanya didukung oleh kling-3.0-video untuk request yang dikondisikan gambar. Definisikan 1-3 elemen; setiap elemen memiliki name, description opsional, dan element_input_urls berisi 2-4 URL gambar. Referensikan elemen di prompt dengan @name. Jangan gabungkan kling_elements dengan output_audio=true; hilangkan output_audio atau set ke false saat memakai referensi elemen.
​
video_url
string
URL publik video sumber. Diperlukan untuk alur video-to-video berbasis URL video dan untuk motion-control; beberapa alur turunan menggunakan task_id sebagai gantinya.
​
video_urls
array
Input video referensi tambahan untuk model yang mendukung conditioning referensi multimodal. Jumlah yang didukung bergantung pada model. Untuk seedance-2.0 dan seedance-2.0-fast, TokenLab saat ini mendukung hingga 3 video referensi.
​
audio_url
string
URL audio publik untuk model yang mendukung audio-to-video.
​
audio_urls
array
Input audio referensi tambahan untuk model yang mendukung conditioning referensi multimodal. Jumlah yang didukung bergantung pada model. Untuk seedance-2.0 dan seedance-2.0-fast, TokenLab saat ini mendukung hingga 3 audio referensi.
​
task_id
string
ID tugas yang digunakan oleh beberapa alur lanjutan, ekstensi, atau turunan.
​
extend_at
integer
Offset awal khusus model yang dipakai oleh beberapa alur video-extension.
​
extend_times
string
Pengali atau jumlah pengulangan khusus model yang dipakai oleh beberapa alur video-extension.
​
duration
integer
Durasi video output yang dihasilkan dalam detik. Untuk model Seedance 1.5/2.0, jika field ini dihilangkan nilainya adalah 5; mengirim -1 membuat model memilih dalam rentang yang didukung, dan penagihan diperkirakan secara konservatif sampai tugas selesai.
​
seconds
integer
Alias kompatibilitas untuk duration. Jika seconds dan duration dikirim bersama, nilainya harus sama. Untuk Seedance, seconds=-1 memiliki arti durasi otomatis yang sama dengan duration=-1.
​
aspect_ratio
string
Rasio aspek kanonis, misalnya adaptive, 16:9, 9:16, 1:1, 4:3, 3:4, atau 21:9. Seedance menggunakan adaptive secara default jika dihilangkan.
​
resolution
string
Resolusi output bergantung pada model. Seedance default ke 720p; seedance-2.0 mendukung 480p, 720p, 1080p, dan 4k, sedangkan seedance-2.0-fast dan seedance-2.0-mini dibatasi ke 480p dan 720p.
​
output_audio
boolean
Toggle output audio kanonis yang bergantung pada model. Veo 3 dan Seedance default ke true jika dihilangkan. kling-3.0-video menerima selector ini untuk request tanpa referensi elemen dan default ke output tanpa suara jika dihilangkan. Jangan gabungkan output_audio=true dengan kling_elements.
​
draft
boolean
Flag alur Draft Seedance 1.5 Pro. Gunakan draft=true dengan model Seedance yang mendukung tugas draft. Jangan kirim bersama draft_task_id.
​
draft_task_id
string
ID tugas draft Seedance 1.5 Pro untuk promosi. Kirim ID tugas draft sebelumnya untuk membuat video final; ini bukan field video generik.
​
ratio
string
Alias kompatibilitas untuk aspect_ratio. Jika ratio dan aspect_ratio dikirim bersama, nilainya harus identik.
​
generate_audio
boolean
Alias kompatibilitas untuk output_audio. Jika generate_audio, output_audio, dan outputAudio muncul bersama, semua nilai harus sama.
​
execution_expires_after
integer
Waktu kedaluwarsa eksekusi opsional dalam detik untuk model video yang kompatibel. Seedance default ke 172800 detik jika dihilangkan.
​
priority
integer
Prioritas tugas opsional dari 0 sampai 9 untuk model video yang kompatibel. Jangan gabungkan priority dengan service_tier=flex.
​
safety_identifier
string
Pengenal keamanan end-user opsional untuk model video yang kompatibel. Jika dihilangkan untuk Seedance, TokenLab menggunakan user jika tersedia.
​
service_tier
string
default diterima sebagai no-op kompatibilitas untuk model Seedance 2.0. flex hanya boleh digunakan jika model yang dipilih mendukungnya.
​
frames
integer
Jumlah frame opsional untuk model video yang kompatibel. Model Seedance 2.0 dan Seedance 1.5 Pro tidak mendukung field ini.
​
camera_fixed
boolean
Selector kamera tetap opsional untuk model video yang kompatibel. Model Seedance 2.0 tidak mendukung field ini.
​
fps
integer
Frame per detik (1-120). Hanya berlaku pada model yang mengekspos kontrol FPS.
​
negative_prompt
string
Elemen yang ingin dihindari dalam video yang dihasilkan.
​
seed
integer
Seed acak untuk generasi yang dapat direproduksi. Seedance menggunakan -1 sebagai seed acak jika dihilangkan.
​
cfg_scale
number
Kekuatan kepatuhan terhadap prompt (0-20) pada model yang mengekspos kontrol ini.
​
motion_strength
number
Intensitas gerakan (0-1) pada model yang mengekspos kontrol ini.
​
start_image
string
URL gambar frame pertama, atau input gambar yang kompatibel, untuk start-end-to-video.
​
end_image
string
URL gambar frame terakhir, atau input gambar yang kompatibel, untuk start-end-to-video.
​
size
string
Tingkat ukuran khusus model untuk model video yang kompatibel.
​
watermark
boolean
Toggle watermark opsional untuk model yang menyediakannya. Seedance default ke false jika dihilangkan.
​
effect_type
string
Pemilih efek khusus model untuk alur efek atau editing tertentu.
​
user
string
Pengenal unik untuk end-user. Untuk Seedance, TokenLab juga menggunakan nilai ini sebagai safety_identifier ketika field tersebut dihilangkan.

​
Catatan kompatibilitas

  • Field publik kanonis menggunakan snake_case: reference_images, reference_image_type, dan output_audio.
  • Field publik kanonis tetap menggunakan snake_case: aspect_ratio, output_audio, reference_images, dan reference_image_type.
  • Untuk kompatibilitas, TokenLab juga menerima ratio, generate_audio, outputAudio, seconds, referenceImages, dan referenceImageType.
  • Jika field kanonis dan alias dikirim bersama, nilainya harus sama; alias yang bertentangan ditolak sebelum tugas dibuat.

​
Praktik terbaik untuk input media

  • Untuk image_url, reference_images, video_url, dan audio_url, sebaiknya gunakan URL https publik.
  • Jika memungkinkan, hindari mencampur base64 inline dan URL jarak jauh dalam permintaan yang sama.
  • Pastikan URL media jarak jauh tetap berlaku cukup lama untuk menutupi coba ulang dan pembuatan tugas asinkron.

​
Parameter Seedance

Untuk model Seedance 1.5/2.0, endpoint terpadu mengikuti nama field TokenLab sambil menerima alias kompatibel seconds, ratio, dan generate_audio. Selector Seedance yang dihilangkan memakai default berikut: duration=5, resolution=720p, aspect_ratio=adaptive, output_audio=true, watermark=false, return_last_frame=false, execution_expires_after=172800, priority=0, dan seed=-1. duration=-1 atau seconds=-1 membuat Seedance memilih durasi output dalam rentang yang didukung model. TokenLab memperkirakan biaya secara konservatif sebelum tugas selesai, lalu melakukan penyelesaian berdasarkan usage tugas selesai jika tersedia. service_tier=default diterima sebagai no-op kompatibilitas untuk Seedance 2.0; service_tier=flex, frames, dan camera_fixed ditolak jika model yang dipilih tidak mendukungnya.

​
Contoh Seedance

cURL
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.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

​
Respons

​
id
string
Identifier tugas asinkron kanonik. Saat id dan task_id sama-sama ada, perlakukan keduanya sebagai identitas tugas yang sama.
​
task_id
string
Pengidentifikasi tugas unik untuk pengecekan status.
​
poll_url
string
URL pengecekan status yang direkomendasikan untuk tugas ini. Gunakan path ini secara persis saat memeriksa status.
​
billing_transaction_id
string
ID transaksi billing TokenLab saat settlement sudah selesai. Ini adalah identitas transaksi untuk dashboard/rekonsiliasi dan terpisah dari id / task_id async.
​
status
string
Status awal: pending.
​
created
integer
Unix timestamp saat tugas dibuat.
​
model
string
Model yang digunakan.
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,
    "aspect_ratio": "16:9"
  }'

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

​
Image to video

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "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,
        "aspect_ratio": "16:9"
    }
)

​
Kling 3.0 Elements

Gunakan kling_elements dengan kling-3.0-video saat memerlukan referensi elemen. Sertakan request yang dikondisikan gambar (image_url, image_urls, start_image, atau end_image) dan referensikan setiap elemen di prompt dengan @name. Jangan gabungkan kling_elements dengan output_audio=true; hilangkan output_audio atau set ke false saat memakai referensi elemen. 
response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

​
Reference to video

Gunakan operation=reference-to-video ketika model mendukung conditioning referensi khusus. Dalam detail model TokenLab, referensi gambar menggunakan reference_images, sedangkan video dan audio referensi multimodal menggunakan video_urls dan audio_urls. Untuk seedance-2.0 dan seedance-2.0-fast, TokenLab saat ini mendukung hingga 9 gambar referensi, ditambah hingga 3 video referensi dan 3 audio referensi. Untuk pilihan model, batas 4K, dan catatan Mini, lihat panduan model video Seedance 2.0. duration hanya mengatur panjang output yang dihasilkan; field ini tidak menetapkan batas terpisah untuk durasi input video referensi. Untuk grok-imagine-video, reference-to-video menerima hingga 7 referensi gambar (reference_images atau image_urls) dan duration dibatasi maksimal 10 detik. Jangan gabungkan referensi gambar dengan input frame awal image_url / image. grok-imagine-video-1.5-preview hanya mendukung image-to-video. 
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"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

​
Kontrol frame awal dan akhir

Gunakan start_image dan end_image untuk mengontrol frame pertama dan frame terakhir. 
response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "prompt": "Smooth transition from day to night",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)

​
Video to video

Untuk video-to-video dengan grok-imagine-video, kirim URL HTTPS publik .mp4 di video_url. TokenLab menerjemahkannya menjadi body REST xAI video.url. Anda dapat mengatur resolution ke 480p atau 720p; duration dan aspect_ratio tidak diterima untuk alur edit ini. Jika model menerima video yang sudah ada sebagai input utama, gunakan operation=video-to-video. 
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.",
        "resolution": "720p"
    }
)

​
Motion control

Jika model membutuhkan gambar subjek sekaligus video referensi gerakan, gunakan operation=motion-control. TokenLab akan menormalkan bentuk publik image_url + video_url menjadi input kontrol gerakan yang kompatibel. 
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 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 dari waktu ke waktu. Gunakan Models API sebagai sumber kebenaran sebelum mengintegrasikan alur khusus model: 
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"
Baca respons detail model sebelum bergantung pada operasi atau field khusus model. Operasi seperti audio-to-video dan video-extension bersifat khusus model; konfirmasi ketersediaan terbarunya di sana, bukan dari contoh statis di halaman ini.