Idempotensi Seedance dan pemulihan pengiriman

Tambahkan Idempotency-Key untuk seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, dan seedance-2.5. POST /v1/videos, POST /v1/videos/generations, dan POST /v1/video/generations berbagi ruang kunci. Gambar, estimasi biaya, remix, dan model video lain tidak tercakup. Tanpa kunci, tidak ada jaminan deduplikasi pengiriman umum.

Cakupan dan kunci

Kunci berlaku untuk akun APIMaster dan operasi video Seedance, bukan satu API Key atau model. Gunakan kunci acak baru berisi 8–128 karakter ASCII terlihat untuk setiap generasi baru. Kredensial valid dari akun yang sama dapat mencari tanda terima. Token yang kuotanya habis dapat mencari atau mengulang tanda terima lama; kunci kedaluwarsa, dicabut, dihapus, atau akun diblokir tidak dapat. Generasi baru tetap membutuhkan kredensial valid dan kuota cukup.

Pengulangan atomik dan konflik

Catatan atomik disimpan sebelum perutean, penagihan, dan menghubungi penyedia. Kunci dan isi yang sama mengembalikan HTTP 202, tanda terima asli, dan ID tugas yang dialokasikan sebelumnya tanpa pengiriman atau reservasi tambahan, termasuk percobaan bersamaan dan restart. Isi berubah menghasilkan HTTP 409 (idempotency_conflict). Urutan objek JSON dan spasi diabaikan; urutan array, angka, nilai dihilangkan versus default eksplisit, model, notifikasi, grup/kanal diperiksa. multipart membandingkan byte dan urutan berkas, bukan batas atau nama. Pertahankan isi dan perutean; JSON dan multipart berbeda. Catatan disimpan minimal 30 hari; versi ini tidak menghapus otomatis atau menggunakan ulang kunci.

Respons

Permintaan pertama mempertahankan respons normal. Simpan X-Video-Submission-Id, ID permintaan dan tugas. Pengulangan mengembalikan tanda terima dengan format yang mungkin berbeda. ID awal tidak membuktikan penerimaan penyedia. accepted bukan berarti generasi selesai. Cari tugas hanya bila task_ready=true; jika tidak, hubungi dukungan tanpa mengirim ulang.

Status pengiriman

pending: tercatat di gateway, belum dikirim. submitting: pengiriman dimulai, hasil menunggu. accepted: ID penyedia diterima. not_accepted: tidak dikirim ke penyedia; perbaiki lalu buat dengan kunci baru. acceptance_unknown: mungkin diterima tanpa konfirmasi; jangan membuat generasi lagi. Setelah gangguan, pencarian mengklasifikasikan catatan setelah 30 menit: sebelum pengiriman not_accepted, sesudah acceptance_unknown. Tidak ada pengiriman ulang otomatis. Ini status pengiriman, bukan tagihan; reservasi, penyelesaian dan rekonsiliasi pengembalian tetap berlaku.

Pemulihan

Setelah timeout atau 5xx cari dengan kunci yang sama meski tidak mendapat ID. Pengulangan identik aman tetapi tidak memulai ulang pengiriman gagal. 404, daftar kosong atau tidak ada tagihan bukan bukti belum diterima: permintaan masih berjalan, tanpa kunci atau sebelum fitur ini. same_key_replay_safe untuk mengambil tanda terima; new_submission_safe=true hanya untuk not_accepted. Untuk hasil tidak diketahui atau accepted dengan task_ready=false, berikan ID tanda terima/permintaan, model dan waktu UTC ke dukungan, bukan API Key. Idempotensi penyedia resmi tidak dijamin. Tanda terima potret lama mempertahankan alur dan dapat memakai skema lama.

Contoh

curl --fail-with-body 'https://apimaster.ai/v1/videos' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: seedance-order-20261014-001' \
  -d '{"model":"seedance-2.0","prompt":"A paper boat on a pond","duration":4,"resolution":"480p","generate_audio":false}'

curl --fail-with-body 'https://apimaster.ai/v1/video-submissions/by-key' \
  -H "Authorization: Bearer $APIMASTER_KEY" \
  -H 'Idempotency-Key: seedance-order-20261014-001'

{
  "code": 200,
  "data": {
    "submission_id": "HASH",
    "task_id": "task_PUBLIC_ID",
    "request_id": "ORIGINAL_REQUEST_ID",
    "model": "seedance-2.0",
    "status": "accepted",
    "task_ready": true,
    "created_at": 1791936000,
    "updated_at": 1791936001,
    "next_action": "query_task",
    "same_key_replay_safe": true,
    "new_submission_safe": false,
    "retention": "at_least_30_days_no_automatic_key_reuse"
  }
}

curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' \
  -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' \
  -H "Authorization: Bearer $APIMASTER_KEY"