Panduan media
Migrasi Seedance dari Volcengine
Pertahankan format permintaan Volcengine Anda dan pindahkan Seedance ke TokenLab
Jika aplikasi Anda sudah menggunakan API Seedance Volcengine, Anda dapat mempertahankan path REST, body content[], field respons, callback, dan Action material PascalCase-nya. Ubah host API dan ganti penandatanganan AK/SK dengan API key TokenLab.
Apa yang Berubah
| Perubahan | Klien Volcengine yang Ada | TokenLab |
|---|---|---|
| Base URL | Endpoint Volcengine Anda | https://api.tokenlab.sh/ |
| Autentikasi | Penandatanganan permintaan AK/SK | Authorization: Bearer <TOKENLAB_API_KEY> |
| Transportasi Tugas | Path REST resmi /api/v3/contents/generations/tasks | Dipertahankan |
| Action Material/validasi | Parameter kueri Action dan Version | Dipertahankan |
| Body Tugas | content[] gaya Volcengine | Dipertahankan |
| Body Material | Field PascalCase seperti GroupId dan ProjectName | Dipertahankan |
| Hasil Asinkron | Siklus hidup tugas Volcengine | ID tugas cgt-... TokenLab dengan polling dan callback opsional |
Permintaan yang hanya ditandatangani dengan AK/SK akan mengembalikan 401 AuthenticationError. Setiap permintaan TokenLab harus menyertakan Authorization: Bearer <TOKENLAB_API_KEY>.
Memilih endpoint
| Klien yang Ada | Endpoint TokenLab |
|---|---|
| Klien tugas REST Volcengine | /api/v3/contents/generations/tasks dan path tugasnya |
| Klien Action Material atau validasi | POST /?Action=...&Version=2024-01-01 atau POST /api/v3?Action=...&Version=2024-01-01 |
Untuk tugas video, pertahankan metode REST, path, dan body JSON yang ada. Permintaan material dan verifikasi tetap menggunakan parameter kueri Action dan Version. Endpoint Action juga menerima Action tugas CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks, dan DeleteContentsGenerationsTasks; gunakan path REST untuk pekerjaan baru.
Path Tugas Resmi
| Metode dan path | Tujuan |
|---|---|
POST /api/v3/contents/generations/tasks | Membuat tugas video |
GET /api/v3/contents/generations/tasks/{id} | Membaca satu tugas |
GET /api/v3/contents/generations/tasks | Mencantumkan tugas |
DELETE /api/v3/contents/generations/tasks/{id} | Membatalkan tugas yang masih dalam antrean. Tugas yang sudah dimulai akan mengembalikan 409 task_not_cancellable |
Klien REST dapat menggunakan referensi yang setara berikut:
- Buat Tugas (Kompatibel dengan Volc)
- Dapatkan Tugas (Kompatibel dengan Volc)
- Daftar Tugas (Kompatibel dengan Volc)
- Batalkan Tugas (Kompatibel dengan Volc)
Aturan Body Permintaan
content[]menerima itemtext,image_url,video_url,audio_url, dandraft_task.- Untuk
image_url, hilangkanroleatau gunakanfirst_frameuntuk image-to-video. Gunakanlast_framebersama dengan frame pertama, ataureference_imageuntuk reference-to-video. - URI material publik seperti
asset://asset-YYYYMMDDHHMMSS-xxxxxdapat digunakan di mana alur kerja Seedance yang dipilih menerima peran media tersebut. - Body REST hanya menerima field resmi, termasuk
model,content,ratio,duration,resolution,generate_audio,watermark,return_last_frame,seed,execution_expires_after, dansafety_identifier. Default berbeda per model.generate_audioadalahfalseuntuk modelseedance-2.0dantrueuntukseedance-2.5, sertadurationadalah5untuk modelseedance-2.0dan-1untukseedance-2.5. Format REST ini menerima nilairesolution480p,720p, dan1080p(480pdan720puntukseedance-2.5) tetapi tidak4k, yang hanya diterima oleh API terpadu/v1/videos/generations.seedance-2.5menolakseed,frames, dancamera_fixed. callback_urlmenerima endpoint HTTP(S) publik. TokenLab mengirimkan body kueri-tugas yang sama untukqueued,running,succeeded,failed, danexpired; hanyasucceededdanfailedyang mengikuti perilaku resmi: batas waktu lima detik, dan percobaan ulang saat endpoint Anda tidak mengakui notifikasi tersebut.
Contoh REST Minimal
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.5",
"content": [
{"type":"text","text":"A cinematic product reveal"},
{"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p"
}'Simpan ID cgt-... yang dikembalikan. Lakukan polling hingga status menjadi succeeded, failed, cancelled, atau expired; jangan menganggap respons pembuatan sebagai video yang sudah selesai. Jika Anda memberikan callback_url, izinkan notifikasi succeeded atau failed berulang dan tetap lakukan polling sebagai jalur pemulihan.
Pisahkan Tipe v1 Dan v3
Jangan gunakan kembali struktur respons /v1/tasks/{id} untuk endpoint ini. API v1 terpadu melaporkan pending, processing, completed, dan failed; API v3 yang kompatibel dengan Volc melaporkan queued, running, succeeded, failed, cancelled, dan expired. Respons v3 resmi juga merepresentasikan duration sebagai string JSON dan menghilangkan error pada tugas yang tidak gagal.
Untuk pemulihan yang aman setelah timeout pembuatan atau pemutusan koneksi, tambahkan Idempotency-Key unik ke permintaan pembuatan REST. Mencoba ulang body yang sama dengan kunci yang sama akan mengembalikan ID cgt-... asli; kunci yang sama dengan body yang berbeda akan mengembalikan 409.
Material Dan Verifikasi Orang Asli
Endpoint Action yang sama juga mendukung 10 operasi material dan grup material. Lihat Action Material (Kompatibel dengan Volc) untuk body PascalCase, filter, paging, amplop respons, dan URL material 12 jam yang tepat.
Material orang asli menambahkan dua Action sebelum unggah:
Action kedua mengembalikan GroupId yang terverifikasi. Gunakan ID tersebut dengan CreateAsset; klien tidak dapat membuat grup LivenessFace secara langsung.
Daftar Periksa Migrasi
- Ganti host API dengan
https://api.tokenlab.sh. - Ganti penandatanganan AK/SK dengan API key Bearer TokenLab.
- Pertahankan metode tugas REST resmi, path, dan casing body permintaan; pertahankan Action dan versi hanya untuk operasi material atau validasi.
- Pertahankan
ProjectNameyang sama di seluruh permintaan material dan verifikasi terkait. - Simpan ID tugas, grup, dan aset TokenLab yang dikembalikan oleh endpoint ini.
- Verifikasi satu respons pembuatan, polling, daftar, dan error sebelum memindahkan trafik produksi.