Video & materi

Buat Tugas (Kompatibel dengan Volc)

Buat tugas Seedance dengan API yang kompatibel dengan Volc.

POST
/api/v3/contents/generations/tasks

Gambaran Umum

Klien Seedance bergaya Volc yang sudah ada dapat menggunakan TokenLab dengan mengubah alamat API dan kunci.

Contoh-contoh ini menggunakan Seedance 2.0. Endpoint ini juga mendukung Seedance 2.5 dengan perbedaan spesifik model di bawah ini. Contoh URI material TokenLab yang dapat digunakan kembali pada halaman ini berlaku untuk Seedance 2.0.

Lihat juga Model Video Seedance 2.0 dan Pembuatan Video.

Autentikasi Dan Endpoint

  • Gunakan Authorization: Bearer <TOKENLAB_API_KEY>.
  • Penandatanganan AK/SK Volc tidak diterima. Permintaan harus menyertakan kunci Bearer TokenLab.
  • Gunakan jalur tugas resmi: POST /api/v3/contents/generations/tasks.

Aturan Konten

  • type: "text" adalah teks prompt.
  • type: "image_url" tanpa role, atau dengan role: "first_frame", diperlakukan sebagai bingkai pertama.
  • role: "last_frame" harus dipasangkan dengan bingkai pertama.
  • type: "video_url" memerlukan role: "reference_video", dan type: "audio_url" memerlukan role: "reference_audio". role: "reference_image" menandai gambar referensi.
  • Batas item: Seedance 2.0 menerima hingga 16 item content (1 teks, 9 gambar, 3 video, 3 audio, 1 draft_task). Seedance 2.5 menerima hingga 51 (1 teks, 30 gambar, 10 video, 10 audio, 1 draft_task).
  • image_url.url menerima URL gambar publik atau URI material seperti asset://asset-YYYYMMDDHHMMSS-xxxxx. role menentukan apakah material tersebut adalah bingkai pertama, bingkai terakhir, atau gambar referensi.
  • Jangan mencampur input bingkai pertama/terakhir dengan media referensi dalam satu permintaan.
  • Body REST hanya menerima field yang ada di halaman ini. Field tingkat atas lainnya, termasuk material_asset_id dan material_asset_ids, akan mengembalikan 400 UnsupportedParameter. Masukkan URI material TokenLab di image_url.url.

Catatan Parameter

model menerima ID model TokenLab seperti seedance-2.0 atau seedance-2.5. Klien yang sudah ada dapat terus mengirimkan ID model Volcengine yang sudah mereka gunakan untuk model-model ini. Respons get-task akan mengembalikan nilai model yang Anda kirimkan. Nilai yang tidak dikenali akan mengembalikan 400 InvalidParameter.

duration adalah angka integer dalam detik; -1 memilih durasi otomatis. Default dan batas berbeda tergantung model:

ParameterSeedance 2.0Seedance 2.5
duration4–15 / -1 (default: 5)4–30 / -1 (default: -1)
resolution480p, 720p, 1080p (default: 720p)480p, 720p (default: 720p)
generate_audioboolean (default: false)boolean (default: true)
priorityTidak didukunginteger: 0–9
seedinteger: -1–4294967295 (default: -1)Tidak didukung
execution_expires_after3600–259200 detik (default: 172800)3600–259200 detik (default: 172800)

Untuk Seedance 2.5, permintaan bingkai pertama, bingkai pertama/terakhir, ekstensi video, dan video-ke-video memerlukan ratio: "adaptive"; video-ke-video juga memerlukan duration: -1. output_format hanya menerima mp4 atau mov untuk Seedance 2.5.

  • ratio menerima 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, atau adaptive (default: adaptive).
  • watermark dan return_last_frame adalah boolean (default: false). safety_identifier adalah string hingga 64 karakter.
  • service_tier hanya menerima default; flex akan mengembalikan 400 UnsupportedParameter.
  • tools menerima paling banyak satu item, {"type": "web_search"}.
  • draft: true, frames, dan camera_fixed tidak didukung. camera_fixed: false hanya diterima untuk Seedance 2.0.
  • callback_url dapat mengarah ke endpoint HTTP(S) publik hingga 2.048 karakter.

Pengiriman Callback

Ketika callback_url ada, TokenLab mengirimkan POST HTTP saat status tugas berubah. Status callback adalah queued, running, succeeded, failed, dan expired. Body JSON cocok dengan respons get-task.

Respons 2xx mengakui pengiriman. Untuk succeeded dan failed, pengiriman yang tidak berhasil dalam lima detik akan dicoba kembali hingga tiga kali. Callback hanya memiliki header konten JSON standar dan tidak ada header pengiriman khusus TokenLab. Pengalihan (redirect) tidak diikuti, dan target jaringan pribadi atau yang dicadangkan akan ditolak.

Simpan ID tugas. Jika callback tidak terkirim, Anda masih dapat mengambil hasilnya dengan endpoint get-task.

Persiapan Gambar

URL gambar HTTP(S) publik dan URL data yang didukung digunakan sebagaimana mestinya; URL tersebut tidak disimpan secara otomatis sebagai material yang dapat digunakan kembali. Referensi asset://asset-... eksplisit menggunakan material TokenLab yang sudah ada. TokenLab memeriksa kepemilikan dan kesiapan sebelum pembuatan. Jika material yang direferensikan masih dalam persiapan, tunggu hingga siap dan coba lagi; periksa error.code dan error.message saat pembuatan gagal.

Untuk material yang sudah ada, gunakan ID asset-YYYYMMDDHHMMSS-xxxxx publik, bukan ID aset asli yang dikembalikan oleh sistem lain. TokenLab memverifikasi kepemilikan material sebelum pembuatan.

Respons Pembuatan

{
  "id": "cgt-20260102030405-a1b2c"
}

Respons pembuatan hanya berisi ID tugas. Simpan agar Anda dapat mengambil status dan hasil kapan saja.

Mencegah Tugas Duplikat

Kirim Idempotency-Key yang unik (1–255 karakter, tanpa baris baru) dengan permintaan pembuatan. Jika koneksi terputus sebelum respons tiba, coba lagi dengan kunci API, kunci idempotensi, dan body permintaan yang sama:

  • Jika tugas asli telah dibuat, TokenLab mengembalikan ID cgt-... yang sama dan menambahkan Idempotency-Replayed: true.
  • Menggunakan kembali kunci dengan body yang berbeda akan mengembalikan 409 dengan kode idempotency_conflict dan tidak akan pernah membuat tugas kedua.
  • Kunci yang lebih panjang dari 255 karakter atau berisi baris baru akan mengembalikan 400 InvalidParameter.

Kunci tidak mengubah bentuk respons JSON. TokenLab tidak menyimpulkan duplikat dari X-Request-ID atau dari body permintaan yang identik tanpa kunci.

Contoh

Pembuatan REST

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

Untuk material yang sudah ada, masukkan setiap URI ke dalam item content[] resmi dan nyatakan perannya:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

Error

Error REST menggunakan {"error": {"code", "message", "param", "type"}}. Masalah permintaan mengembalikan 400 dengan InvalidParameter atau UnsupportedParameter, dan kunci Bearer yang hilang mengembalikan 401 AuthenticationError. Error dari pembuatan video, seperti saldo tidak mencukupi (402) atau batas kecepatan (429), tetap mempertahankan status HTTP-nya.

Operasi yang sama juga tersedia sebagai Actions CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks, dan DeleteContentsGenerationsTasks pada POST /api/v3?Version=2024-01-01. Integrasi baru harus menggunakan jalur REST di atas.

Langkah Berikutnya

Gunakan ID cgt-... yang dikembalikan dengan Dapatkan Tugas (Kompatibel dengan Volc) sampai tugas mencapai status terminal.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'
{  "id": "string"}

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

Key yang dihasilkan klien untuk pembuatan tugas REST yang idempoten, 1-255 karakter tanpa jeda baris. Di bawah kredensial API TokenLab yang sama, menggunakan kembali key yang sama dengan body JSON yang sama akan mengembalikan ID tugas cgt asli; menggunakannya kembali dengan body yang berbeda akan mengembalikan 409 dengan kode idempotency_conflict. Key yang terlalu panjang atau berisi jeda baris akan mengembalikan 400. Simpan kredensial, key, dan body permintaan agar tidak berubah saat mencoba kembali setelah timeout atau terputus.

Panjang1 <= length <= 255

Body permintaan

application/json

Respons

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json