> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Buat video

> Membuat tugas generasi video

## 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

<ParamField body="model" type="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](/id/guides/video-generation) dan [Models API](/id/api-reference/models/list-models).
</ParamField>

<Note>
  **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`
</Note>

<ParamField body="prompt" type="string" required>
  Deskripsi teks video yang ingin Anda hasilkan. Field ini wajib untuk sebagian besar model video publik.
</ParamField>

<ParamField body="operation" type="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.
</ParamField>

<ParamField body="image_url" type="string">
  URL publik dari gambar awal untuk alur image-to-video. Untuk kompatibilitas lintas-model yang paling luas, sebaiknya gunakan `image_url`.
</ParamField>

<ParamField body="image" type="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.
</ParamField>

<ParamField body="reference_images" type="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](/id/guides/seedance-2-video). 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.
</ParamField>

<ParamField body="material_asset_id" type="string">
  ID material Seedance TokenLab yang dikembalikan oleh [Create Material Asset](/id/api-reference/video/create-material-asset) atau persiapan gambar otomatis. Gunakan setelah material menjadi `ACTIVE` dengan model Seedance yang dapat menggunakan pustaka material TokenLab.
</ParamField>

<ParamField body="material_asset_ids" type="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.
</ParamField>

<Info>
  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.
</Info>

<ParamField body="reference_image_type" type="string">
  Field opsional untuk model yang membedakan referensi `asset` dan `style`.
</ParamField>

<ParamField body="kling_elements" type="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.
</ParamField>

<ParamField body="video_url" type="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.
</ParamField>

<ParamField body="video_urls" type="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.
</ParamField>

<ParamField body="audio_url" type="string">
  URL audio publik untuk model yang mendukung `audio-to-video`.
</ParamField>

<ParamField body="audio_urls" type="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.
</ParamField>

<ParamField body="task_id" type="string">
  ID tugas yang digunakan oleh beberapa alur lanjutan, ekstensi, atau turunan.
</ParamField>

<ParamField body="extend_at" type="integer">
  Offset awal khusus model yang dipakai oleh beberapa alur `video-extension`.
</ParamField>

<ParamField body="extend_times" type="string">
  Pengali atau jumlah pengulangan khusus model yang dipakai oleh beberapa alur `video-extension`.
</ParamField>

<ParamField body="duration" type="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.
</ParamField>

<ParamField body="seconds" type="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`.
</ParamField>

<ParamField body="aspect_ratio" type="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.
</ParamField>

<ParamField body="resolution" type="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`.
</ParamField>

<ParamField body="output_audio" type="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`.
</ParamField>

<ParamField body="draft" type="boolean">
  Flag alur Draft Seedance 1.5 Pro. Gunakan `draft=true` dengan model Seedance yang mendukung tugas draft. Jangan kirim bersama `draft_task_id`.
</ParamField>

<ParamField body="draft_task_id" type="string">
  ID tugas draft Seedance 1.5 Pro untuk promosi. Kirim ID tugas draft sebelumnya untuk membuat video final; ini bukan field video generik.
</ParamField>

<ParamField body="ratio" type="string">
  Alias kompatibilitas untuk `aspect_ratio`. Jika `ratio` dan `aspect_ratio` dikirim bersama, nilainya harus identik.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Alias kompatibilitas untuk `output_audio`. Jika `generate_audio`, `output_audio`, dan `outputAudio` muncul bersama, semua nilai harus sama.
</ParamField>

<ParamField body="execution_expires_after" type="integer">
  Waktu kedaluwarsa eksekusi opsional dalam detik untuk model video yang kompatibel. Seedance default ke `172800` detik jika dihilangkan.
</ParamField>

<ParamField body="priority" type="integer">
  Prioritas tugas opsional dari `0` sampai `9` untuk model video yang kompatibel. Jangan gabungkan `priority` dengan `service_tier=flex`.
</ParamField>

<ParamField body="safety_identifier" type="string">
  Pengenal keamanan end-user opsional untuk model video yang kompatibel. Jika dihilangkan untuk Seedance, TokenLab menggunakan `user` jika tersedia.
</ParamField>

<ParamField body="service_tier" type="string">
  `default` diterima sebagai no-op kompatibilitas untuk model Seedance 2.0. `flex` hanya boleh digunakan jika model yang dipilih mendukungnya.
</ParamField>

<ParamField body="frames" type="integer">
  Jumlah frame opsional untuk model video yang kompatibel. Model Seedance 2.0 dan Seedance 1.5 Pro tidak mendukung field ini.
</ParamField>

<ParamField body="camera_fixed" type="boolean">
  Selector kamera tetap opsional untuk model video yang kompatibel. Model Seedance 2.0 tidak mendukung field ini.
</ParamField>

<ParamField body="fps" type="integer">
  Frame per detik (1-120). Hanya berlaku pada model yang mengekspos kontrol FPS.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Elemen yang ingin dihindari dalam video yang dihasilkan.
</ParamField>

<ParamField body="seed" type="integer">
  Seed acak untuk generasi yang dapat direproduksi. Seedance menggunakan `-1` sebagai seed acak jika dihilangkan.
</ParamField>

<ParamField body="cfg_scale" type="number">
  Kekuatan kepatuhan terhadap prompt (0-20) pada model yang mengekspos kontrol ini.
</ParamField>

<ParamField body="motion_strength" type="number">
  Intensitas gerakan (0-1) pada model yang mengekspos kontrol ini.
</ParamField>

<ParamField body="start_image" type="string">
  URL gambar frame pertama, atau input gambar yang kompatibel, untuk `start-end-to-video`.
</ParamField>

<ParamField body="end_image" type="string">
  URL gambar frame terakhir, atau input gambar yang kompatibel, untuk `start-end-to-video`.
</ParamField>

<ParamField body="size" type="string">
  Tingkat ukuran khusus model untuk model video yang kompatibel.
</ParamField>

<ParamField body="watermark" type="boolean">
  Toggle watermark opsional untuk model yang menyediakannya. Seedance default ke `false` jika dihilangkan.
</ParamField>

<ParamField body="effect_type" type="string">
  Pemilih efek khusus model untuk alur efek atau editing tertentu.
</ParamField>

<ParamField body="user" type="string">
  Pengenal unik untuk end-user. Untuk Seedance, TokenLab juga menggunakan nilai ini sebagai `safety_identifier` ketika field tersebut dihilangkan.
</ParamField>

## 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

```bash cURL theme={null}
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

<ResponseField name="id" type="string">
  Identifier tugas asinkron kanonik. Saat `id` dan `task_id` sama-sama ada, perlakukan keduanya sebagai identitas tugas yang sama.
</ResponseField>

<ResponseField name="task_id" type="string">
  Pengidentifikasi tugas unik untuk pengecekan status.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL pengecekan status yang direkomendasikan untuk tugas ini. Gunakan path ini secara persis saat memeriksa status.
</ResponseField>

<ResponseField name="billing_transaction_id" type="string">
  ID transaksi billing TokenLab saat settlement sudah selesai. Ini adalah identitas transaksi untuk dashboard/rekonsiliasi dan terpisah dari `id` / `task_id` async.
</ResponseField>

<ResponseField name="status" type="string">
  Status awal: `pending`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp saat tugas dibuat.
</ResponseField>

<ResponseField name="model" type="string">
  Model yang digunakan.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "model": "veo3.1",
    "created": 1706000000
  }
  ```
</ResponseExample>

## Image to video

```python theme={null}
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.

```python theme={null}
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](/id/guides/seedance-2-video). `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.

```python theme={null}
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.

```python theme={null}
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`.

```python theme={null}
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.

```python theme={null}
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](/id/api-reference/models/list-models) sebagai sumber kebenaran sebelum mengintegrasikan alur khusus model:

```bash theme={null}
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.