Seedance idempotansı ve gönderim kurtarma

seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5 için Idempotency-Key ekleyin. POST /v1/videos, POST /v1/videos/generations, POST /v1/video/generations ortak anahtar alanını kullanır. Görseller, fiyat teklifleri, remix ve diğer video modelleri kapsam dışıdır. Anahtarsız istekler için genel gönderim tekilleştirme garantisi yoktur.

Kapsam ve anahtarlar

Anahtar, tek API Key veya modele değil APIMaster hesabındaki Seedance video oluşturma işlemine aittir. Her yeni üretimde 8–128 görünür ASCII karakterinden oluşan yeni rastgele anahtar kullanın. Aynı hesabın geçerli kimlik bilgileri kaydı sorgulayabilir. Kotası tükenmiş tokenlar mevcut kayıtları sorgulayabilir veya yeniden alabilir; süresi dolmuş, iptal edilmiş, silinmiş anahtarlar ve engelli hesaplar alamaz. Yeni üretim geçerli kimlik ve yeterli kota gerektirir.

Atomik tekrar ve çakışmalar

Yönlendirme, ücretlendirme ve sağlayıcıyla iletişimden önce atomik veritabanı kaydı oluşturulur. Aynı anahtar ve içerik HTTP 202 ile özgün kaydı ve önceden ayrılan görev ID’sini döndürür; eşzamanlı tekrarlar ve yeniden başlatmalar da yeni gönderim veya ön tahsilat yapmaz. Değişen içerik HTTP 409 (idempotency_conflict) verir. JSON nesne sırası ve boşluklar yok sayılır; dizi sırası, sayılar, atlanan veya açık varsayılan değerler, model, bildirimler ve grup/kanal karşılaştırılır. multipart dosya baytlarını ve sırasını karşılaştırır, sınırları ve adları değil. Gövdeyi ve yönlendirmeyi koruyun; JSON ve multipart farklıdır. Kayıtlar en az 30 gün saklanır; bu sürüm otomatik silmez veya anahtarları yeniden kullanmaz.

Yanıtlar

İlk istek normal oluşturma yanıtını korur. X-Video-Submission-Id, istek ID’si ve görev ID’sini saklayın. Tekrarlar kayıt döndürür, biçim farklı olabilir. Önceden ayrılan ID, sağlayıcının kabulünü kanıtlamaz. accepted üretimin tamamlandığı anlamına gelmez. Görevi yalnızca task_ready=true ise sorgulayın; aksi halde yeniden göndermeden desteğe başvurun.

Gönderim durumları

pending: ağ geçidinde kayıtlı, gönderilmedi. submitting: gönderim başladı, sonuç bekleniyor. accepted: sağlayıcı görev ID’si alındı. not_accepted: sağlayıcıya gönderilmedi; hatayı düzeltip yeni anahtarla oluşturun. acceptance_unknown: kabul edilmiş olabilir fakat doğrulama yok; tekrar üretmeyin. Çökme sonrası yarım kalan kayıtlar 30 dakika sonra sorgulandığında gönderim öncesi not_accepted, sonrası acceptance_unknown olur. Otomatik yeniden gönderim yoktur. Bunlar gönderim durumlarıdır, ödeme durumları değildir; rezervasyon, mutabakat ve iade uzlaştırması sürer.

Kurtarma

Zaman aşımı veya 5xx sonrası görev ID’si yoksa da aynı anahtarla sorgulayın. Aynı içeriğin tekrarı güvenlidir ancak başarısız gönderimi yeniden başlatmaz. 404, boş liste veya ücret kaydı olmaması kabul edilmediğini kanıtlamaz: ilk istek yolda, anahtarsız veya özellik öncesinde olabilir. same_key_replay_safe kaydı yeniden almayı ifade eder; new_submission_safe=true yalnızca not_accepted içindir. Belirsiz sonuçta veya accepted ve task_ready=false ise kayıt/istek ID’si, model ve UTC saatini desteğe iletin, API Key göndermeyin. Resmî sağlayıcının idempotansı garanti edilmez. Eski portre kayıtları önceki tekrar yolunu ve eski yanıt şemasını koruyabilir.

Örnekler

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"