Seedance: Idempotenz und Wiederherstellung

Verwenden Sie Idempotency-Key für seedance-2.0, seedance-2.0-fast, seedance-2.0-mini und seedance-2.5. Unterstützt sind POST /v1/videos, POST /v1/videos/generations und POST /v1/video/generations mit gemeinsamem Schlüsselraum. Bilder, Kostenvoranschläge, remix und andere Videomodelle sind ausgenommen. Ohne Schlüssel gilt keine allgemeine Deduplizierungsgarantie.

Geltungsbereich und Schlüssel

Der Schlüssel gilt pro APIMaster-Konto und Seedance-Videogenerierung, nicht pro API Key oder Modell. Nutzen Sie für jede neue Generierung einen zufälligen neuen Schlüssel mit 8–128 sichtbaren ASCII-Zeichen. Gültige Zugangsschlüssel desselben Kontos dürfen Belege abfragen. Erschöpfte Tokens dürfen bestehende Belege abrufen oder wiederholen; abgelaufene, widerrufene oder gelöschte Schlüssel sowie gesperrte Konten nicht. Neue Generierungen benötigen gültige Zugangsdaten und ausreichendes Kontingent.

Atomare Wiederholung und Konflikte

Vor Routing, Abrechnung und Anbieteraufruf wird ein atomarer Datenbankbeleg gespeichert. Gleicher Schlüssel und Inhalt liefern HTTP 202 mit Originalbeleg und vorab vergebener Aufgaben-ID, auch bei parallelen Wiederholungen und Neustarts, ohne erneute Einreichung oder Reservierung. Geänderter Inhalt ergibt HTTP 409 (idempotency_conflict). JSON-Objektreihenfolge und Leerraum werden ignoriert; Arrayreihenfolge, Zahlen, ausgelassene gegenüber expliziten Standardwerten, Modell, Benachrichtigungen und Routinggruppe/Kanal sind relevant. Bei multipart zählen Dateiinhalt und Reihenfolge, nicht Grenzen oder Dateinamen. Behalten Sie Inhalt und Routing bei; JSON und multipart unterscheiden sich. Belege bleiben mindestens 30 Tage erhalten; diese Version löscht sie nicht automatisch und verwendet Schlüssel nicht erneut.

Antworten

Die erste Anfrage behält die normale Erstellungsantwort. Speichern Sie X-Video-Submission-Id, Anfrage-ID und Aufgaben-ID. Wiederholungen liefern einen Beleg und eventuell ein anderes Antwortformat. Die vorab vergebene ID beweist keine Annahme durch den Anbieter. accepted bedeutet keine abgeschlossene Generierung. Fragen Sie die Aufgabe nur bei task_ready=true ab, andernfalls kontaktieren Sie den Support ohne Neueinreichung.

Einreichungsstatus

pending: im Gateway gespeichert, noch nicht gesendet. submitting: Sendung begonnen, Ergebnis ausstehend. accepted: Anbieter-ID erhalten. not_accepted: nicht an den Anbieter gesendet; nach Korrektur mit neuem Schlüssel neu erstellen. acceptance_unknown: möglicherweise angenommen, Bestätigung fehlt; keine neue Generierung. Nach einem Absturz werden offene Belege nach 30 Minuten beim Abruf klassifiziert: vor dem Senden als not_accepted, danach als acceptance_unknown. Keine automatische Neueinreichung. Einreichungsstatus ist kein Abrechnungsstatus; Reservierungen, Abrechnung und Erstattungsabgleich gelten weiterhin.

Wiederherstellung

Nach Timeout oder 5xx mit demselben Schlüssel nachsehen, auch ohne Aufgaben-ID. Identische Wiederholung ist sicher, startet aber fehlgeschlagene Einreichungen nicht neu. 404, leere Listen und fehlende Abrechnungslogs beweisen keine Nichtannahme: die ursprüngliche Anfrage kann unterwegs, ohne Schlüssel oder vor Einführung dieser Funktion erfolgt sein. same_key_replay_safe betrifft den Belegabruf; new_submission_safe=true gilt nur für not_accepted. Bei Ungewissheit oder accepted mit task_ready=false Beleg-/Anfrage-ID, Modell und UTC-Zeit an den Support geben, niemals API Keys. Keine Garantie für Idempotenz beim offiziellen Anbieter. Alte Portraitbelege behalten ihren bisherigen Wiederholungsweg und ihr Schema.

Beispiele

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"