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

PerubahanKlien Volcengine yang AdaTokenLab
Base URLEndpoint Volcengine Andahttps://api.tokenlab.sh/
AutentikasiPenandatanganan permintaan AK/SKAuthorization: Bearer <TOKENLAB_API_KEY>
Transportasi TugasPath REST resmi /api/v3/contents/generations/tasksDipertahankan
Action Material/validasiParameter kueri Action dan VersionDipertahankan
Body Tugascontent[] gaya VolcengineDipertahankan
Body MaterialField PascalCase seperti GroupId dan ProjectNameDipertahankan
Hasil AsinkronSiklus hidup tugas VolcengineID 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 AdaEndpoint TokenLab
Klien tugas REST Volcengine/api/v3/contents/generations/tasks dan path tugasnya
Klien Action Material atau validasiPOST /?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 pathTujuan
POST /api/v3/contents/generations/tasksMembuat tugas video
GET /api/v3/contents/generations/tasks/{id}Membaca satu tugas
GET /api/v3/contents/generations/tasksMencantumkan 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:

Aturan Body Permintaan

  • content[] menerima item text, image_url, video_url, audio_url, dan draft_task.
  • Untuk image_url, hilangkan role atau gunakan first_frame untuk image-to-video. Gunakan last_frame bersama dengan frame pertama, atau reference_image untuk reference-to-video.
  • URI material publik seperti asset://asset-YYYYMMDDHHMMSS-xxxxx dapat 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, dan safety_identifier. Default berbeda per model. generate_audio adalah false untuk model seedance-2.0 dan true untuk seedance-2.5, serta duration adalah 5 untuk model seedance-2.0 dan -1 untuk seedance-2.5. Format REST ini menerima nilai resolution 480p, 720p, dan 1080p (480p dan 720p untuk seedance-2.5) tetapi tidak 4k, yang hanya diterima oleh API terpadu /v1/videos/generations. seedance-2.5 menolak seed, frames, dan camera_fixed.
  • callback_url menerima endpoint HTTP(S) publik. TokenLab mengirimkan body kueri-tugas yang sama untuk queued, running, succeeded, failed, dan expired; hanya succeeded dan failed yang 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:

  1. Buat Sesi Validasi Visual
  2. Dapatkan Hasil Validasi Visual

Action kedua mengembalikan GroupId yang terverifikasi. Gunakan ID tersebut dengan CreateAsset; klien tidak dapat membuat grup LivenessFace secara langsung.

Daftar Periksa Migrasi

  1. Ganti host API dengan https://api.tokenlab.sh.
  2. Ganti penandatanganan AK/SK dengan API key Bearer TokenLab.
  3. Pertahankan metode tugas REST resmi, path, dan casing body permintaan; pertahankan Action dan versi hanya untuk operasi material atau validasi.
  4. Pertahankan ProjectName yang sama di seluruh permintaan material dan verifikasi terkait.
  5. Simpan ID tugas, grup, dan aset TokenLab yang dikembalikan oleh endpoint ini.
  6. Verifikasi satu respons pembuatan, polling, daftar, dan error sebelum memindahkan trafik produksi.

Di halaman ini