Buat Tugas (Kompatibel dengan Volc)

Gambaran UmumCopy Anchor Link

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

Lihat juga Model Video Seedance 2.0 dan Pembuatan Video.

Autentikasi Dan EndpointCopy Anchor Link

• 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 KontenCopy Anchor Link

• 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.
• role: "reference_image", reference_video, dan reference_audio digunakan sebagai referensi.
• 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.
• Field tingkat atas material_asset_id dan material_asset_ids ditolak. Masukkan URI material TokenLab ke image_url.url. priority hanya didukung untuk Seedance 2.5.

Catatan ParameterCopy Anchor Link

duration adalah bilangan bulat dalam detik; -1 memilih durasi otomatis. Default dan batas berbeda menurut model:

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

• ratio menerima 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, atau adaptive.
• watermark, return_last_frame, seed, execution_expires_after, dan safety_identifier diterima jika valid untuk model yang dipilih.
• callback_url dapat mengarah ke endpoint HTTP(S) publik.

Pengiriman CallbackCopy Anchor Link

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 GambarCopy Anchor Link

URL gambar HTTP(S) publik dan URL data yang didukung digunakan sesuai input, tanpa otomatis disimpan sebagai material yang dapat digunakan kembali. Referensi eksplisit asset://asset-... memakai material TokenLab yang sudah ada. Kepemilikan dan kesiapan diperiksa sebelum pembuatan. Jika material masih disiapkan, tunggu hingga siap lalu coba lagi. Jika pembuatan gagal, periksa error.code dan error.message.

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 PembuatanCopy Anchor Link

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

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

Mencegah Tugas DuplikatCopy Anchor Link

Kirim Idempotency-Key unik 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.
• Jika permintaan asli masih didaftarkan, TokenLab mengembalikan 409 IdempotencyRequestInProgress. Coba lagi nanti dengan kunci dan body yang sama.
• Menggunakan kembali kunci dengan body yang berbeda akan mengembalikan 409 IdempotencyConflict dan tidak akan pernah membuat tugas kedua.

Idempotensi berlaku untuk jalur pembuatan REST v3 resmi. Ini tidak mengubah bentuk respons JSON, dan tidak disimpulkan dari X-Request-ID atau dari body permintaan yang identik tanpa kunci.

ContohCopy Anchor Link

Pembuatan RESTCopy Anchor Link

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": "doubao-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"}
  }
]

Langkah BerikutnyaCopy Anchor Link

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": "doubao-seedance-2-0-260128",    "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"}