Video & materi

Create Video

Memulai tugas pembuatan video

POST
/v1/videos/generations

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-Key untuk 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, dan veo3.1-lite selalu menghasilkan audio. Hilangkan output_audio atau kirim true; false akan ditolak.
  • wan-2.6 dan wan-2.7 selalu menyertakan audio. Hilangkan output_audio atau kirim true. wan-3.0 dan wan-3.0-prime juga selalu menyertakan audio dan tidak menggunakan pemilih audio.
  • hailuo-h3 menghasilkan audio asli dan tidak memiliki tombol senyap (mute). Jangan mengirim pemilih audio yang tidak tercantum dalam detail model.
  • viduq3-pro dan viduq3-turbo menghasilkan audio secara default; kirim output_audio: false (atau audio: false) untuk output senyap. Model Seedance dan PixVerse menggunakan output_audio; kirim secara eksplisit alih-alih mengandalkan default. Gunakan hanya untuk operasi yang mencantumkannya.
  • audio_url / audio_urls menyediakan 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

modelstringbawaan: veo3.1

ID 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, 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
promptstring

Deskripsi teks video, hingga 10.000 karakter. Sebagian besar operasi memerlukan deskripsi ini; detail model akan menjelaskan mana yang tidak memerlukannya.

operationstring

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.

image_urlstring

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.

imagestring

Gambar inline sebagai data URL (contoh: data:image/jpeg;base64,...). Hanya beberapa model yang menerimanya; image_url berfungsi pada lebih banyak model.

image_urlsarray

URL gambar untuk model yang mencantumkan bidang ini. Lihat reference_images untuk batas jumlah.

reference_imagesarray

Gambar referensi untuk reference-to-video, sebagai URL https atau data URL. Batas jumlah bergantung pada model:

  • seedance-2.0, seedance-2.0-fast, dan seedance-2.0-mini: hingga 9 referensi gambar secara total, termasuk aset materi. Lebih dari itu akan mengembalikan 400 too_many_seedance_reference_images.
  • seedance-2.5: hingga 30 input gambar secara total di seluruh image_urls dan reference_images.
  • grok-imagine-video: hingga 7, dan duration dibatasi maksimal 10 detik. grok-imagine-video-1.5 dan grok-imagine-video-1.5-preview tidak 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.

start_imagestring

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.

end_imagestring

Gambar bingkai terakhir untuk start-end-to-video. Menerima input yang sama dengan start_image.

material_asset_idstring

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.

material_asset_idsarray

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.

video_urlstring

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_urlsarray

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.

audio_urlstring

URL audio publik untuk referensi audio atau operasi berbasis audio, pada model yang mencantumkan bidang ini. Ini adalah input, bukan sakelar output audio.

audio_urlsarray

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.

task_idstring

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.

extend_atinteger

Detik dari video sumber di mana video-extension dimulai. Diperlukan oleh grok-imagine-video.

extend_timesstring

Detik untuk ditambahkan dalam video-extension, pada model yang mencantumkan bidang ini. grok-imagine-video menerima 6 atau 10.

durationinteger

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.

secondsinteger

Alias kompatibilitas untuk duration. Jika keduanya dikirim, nilainya harus identik.

aspect_ratiostring

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.

resolutionstring

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.

output_audioboolean

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.

output_formatstring

Format kontainer, mp4 atau mov, untuk model yang mencantumkan bidang ini, seperti seedance-2.5. Lewati untuk model yang tidak mencantumkannya.

return_last_frameboolean

Juga mengembalikan bingkai terakhir yang dihasilkan sebagai last_frame_url. Hanya model Seedance.

watermarkboolean

Toggle watermark untuk model yang mencantumkan bidang ini (model Seedance).

negative_promptstring

Hal yang harus dihindari dalam video yang dihasilkan, hingga 5.000 karakter, untuk model yang mencantumkan bidang ini.

seedinteger

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.

fpsinteger

Bingkai per detik (1-120), untuk model yang mencantumkan bidang ini.

framesinteger

Jumlah bingkai, untuk model yang mencantumkan bidang ini. Model Seedance tidak menerimanya.

execution_expires_afterinteger

Detik tugas dapat menunggu dalam antrean sebelum kedaluwarsa (3600 hingga 259200), untuk model Seedance.

priorityinteger

Prioritas tugas dari 0 hingga 9, untuk model Seedance. Jangan gabungkan dengan service_tier=flex.

service_tierstring

default diterima sebagai no-op kompatibilitas pada model Seedance 2.0 dan 2.5. flex ditolak pada model tersebut.

safety_identifierstring

Pengidentifikasi keamanan pengguna akhir (hingga 128 karakter), untuk model Seedance. Jika dilewati, TokenLab menggunakan user jika disediakan.

toolsarray

Alat yang mungkin digunakan model saat membuat, untuk model Seedance 2.0 dan 2.5. Alat yang didukung adalah {"type": "web_search"}.

userstring

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, dan reference_images.
  • Untuk kompatibilitas, TokenLab juga menerima ratio, generate_audio, outputAudio, seconds, dan referenceImages.
  • Jika bidang utama dan aliasnya dikirim bersamaan, nilainya harus cocok. Ketidakcocokan akan mengembalikan 400 dengan conflicting_audio_selector, conflicting_duration, atau conflicting_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.0seedance-2.5
Resolusiseedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast dan seedance-2.0-mini: 480p, 720p480p, 720p
Durasi-1, 4 hingga 15 detik-1, 4 hingga 30 detik
Rasio aspek1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptiveSama 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 outputmp4mp4 atau mov
seedDiterimaTidak diterima
Input referensi9 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
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.

idstring

ID Tugas. Identik dengan task_id.

task_idstring

ID tugas untuk melakukan polling dengan GET /v1/tasks/{id}.

poll_urlstring

URL status untuk tugas ini, /v1/tasks/{id}. Panggil dengan API key Anda.

statusstring

Status tugas: pending, processing, completed, failed. Tugas baru biasanya berstatus pending.

createdinteger

Stempel waktu Unix saat tugas dibuat.

modelstring

Model yang digunakan.

billing_transaction_idstring

ID transaksi penagihan saat penyelesaian sudah selesai. Ini terpisah dari ID tugas.

video_urlstring

URL video, hanya ada saat respons pembuatan sudah membawa hasil. Biasanya Anda membacanya dari respons status.

errorstring | object

Pesan kesalahan atau objek kesalahan terstruktur saat tugas gagal.

Kesalahan

Status dan kodeArti
400 invalid_requestBidang 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_longPermintaan tidak cocok dengan apa yang diterima model untuk operasi tersebut. Kesalahan biasanya mencantumkan nilai yang diterima.
400 invalid_parameterInput tidak sesuai dengan operasi, contoh gambar dikirim dengan text-to-video.
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratioAlias dan bidang utamanya tidak cocok.
400 unpriceable_selectionKombinasi yang dipilih tidak memiliki harga. Ubah resolution, duration, aspect_ratio, atau pengaturan audio.
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_modelTerlalu banyak referensi gambar untuk model Seedance 2.0, atau materi dikirim ke model lain.
402Saldo tidak mencukupi.
403 task_not_ownedtask_id milik ruang kerja lain.
409 seedance_material_preparing, seedance_material_route_unavailableMateri belum ACTIVE, atau model yang dipilih tidak dapat menggunakan materi yang disediakan.
429Batas 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

Response
{
  "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
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Panjang1 <= length <= 255

Body permintaan

application/json

Respons

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json