Video & materi
Buat Tugas (Kompatibel dengan Volc)
Buat tugas Seedance dengan API yang kompatibel dengan Volc.
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"tanparole, atau denganrole: "first_frame", diperlakukan sebagai bingkai pertama.role: "last_frame"harus dipasangkan dengan bingkai pertama.type: "video_url"memerlukanrole: "reference_video", dantype: "audio_url"memerlukanrole: "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, 1draft_task). Seedance 2.5 menerima hingga 51 (1 teks, 30 gambar, 10 video, 10 audio, 1draft_task). image_url.urlmenerima URL gambar publik atau URI material sepertiasset://asset-YYYYMMDDHHMMSS-xxxxx.rolemenentukan 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_iddanmaterial_asset_ids, akan mengembalikan400 UnsupportedParameter. Masukkan URI material TokenLab diimage_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:
| Parameter | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (default: 5) | 4–30 / -1 (default: -1) |
resolution | 480p, 720p, 1080p (default: 720p) | 480p, 720p (default: 720p) |
generate_audio | boolean (default: false) | boolean (default: true) |
priority | Tidak didukung | integer: 0–9 |
seed | integer: -1–4294967295 (default: -1) | Tidak didukung |
execution_expires_after | 3600–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.
ratiomenerima16:9,4:3,1:1,3:4,9:16,21:9, atauadaptive(default:adaptive).watermarkdanreturn_last_frameadalah boolean (default:false).safety_identifieradalah string hingga 64 karakter.service_tierhanya menerimadefault;flexakan mengembalikan400 UnsupportedParameter.toolsmenerima paling banyak satu item,{"type": "web_search"}.draft: true,frames, dancamera_fixedtidak didukung.camera_fixed: falsehanya diterima untuk Seedance 2.0.callback_urldapat 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 menambahkanIdempotency-Replayed: true. - Menggunakan kembali kunci dengan body yang berbeda akan mengembalikan
409dengan kodeidempotency_conflictdan 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 Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.
Lokasi: header
Header
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"
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.
1 <= length <= 255Body permintaan
application/json
Respons
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json