Idempotencja Seedance i odzyskiwanie zgłoszeń

Dodaj Idempotency-Key dla seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5. POST /v1/videos, POST /v1/videos/generations, POST /v1/video/generations mają wspólną przestrzeń kluczy. Obrazy, wyceny, remix i inne modele wideo nie są objęte. Bez klucza nie ma ogólnej gwarancji deduplikacji.

Zakres i klucze

Klucz dotyczy konta APIMaster i operacji tworzenia wideo Seedance, nie pojedynczego API Key ani modelu. Dla każdej nowej generacji użyj nowego losowego klucza z 8–128 widocznych znaków ASCII. Ważne poświadczenia tego samego konta mogą odczytać potwierdzenie. Tokeny z wyczerpanym limitem mogą odczytywać lub powtarzać istniejące potwierdzenia; wygasłe, odwołane, usunięte klucze i zablokowane konta nie. Nowa generacja wymaga ważnych poświadczeń i wystarczającego limitu.

Atomowe powtórzenia i konflikty

Przed wyborem trasy, rozliczeniem i kontaktem z dostawcą zapisujemy atomowy rekord w bazie. Ten sam klucz i treść zwracają HTTP 202, pierwotny rekord i wstępnie przydzielony ID zadania bez nowego wysłania lub rezerwacji, także przy równoległych powtórzeniach i restartach. Zmieniona treść daje HTTP 409 (idempotency_conflict). Ignorujemy kolejność pól obiektu JSON i odstępy; porównujemy kolejność tablic, liczby, pominięte i jawne wartości domyślne, model, powiadomienia oraz grupę/kanał. multipart porównuje bajty i kolejność plików, nie granice ani nazwy. Zachowaj treść i trasę; JSON i multipart są różne. Rekordy przechowujemy co najmniej 30 dni; ta wersja nie usuwa ich automatycznie ani nie używa kluczy ponownie.

Odpowiedzi

Pierwsze żądanie zachowuje zwykłą odpowiedź tworzenia. Zapisz X-Video-Submission-Id, ID żądania i zadania. Powtórzenie zwraca potwierdzenie, niekoniecznie pierwotny format. Wstępny ID nie dowodzi przyjęcia przez dostawcę. accepted nie oznacza ukończenia generacji. Odpytuj zadanie tylko przy task_ready=true; inaczej skontaktuj się ze wsparciem bez ponownego wysyłania.

Stany zgłoszenia

pending: zapisane w bramie, jeszcze niewysłane. submitting: wysyłanie rozpoczęte, wynik oczekiwany. accepted: otrzymano ID dostawcy. not_accepted: nie wysłano do dostawcy; popraw błąd i utwórz z nowym kluczem. acceptance_unknown: możliwe przyjęcie bez potwierdzenia; nie generuj ponownie. Po awarii niedokończone rekordy są klasyfikowane przy odczycie po 30 minutach: przed wysłaniem not_accepted, po wysłaniu acceptance_unknown. Bez automatycznego ponownego wysyłania. Są to stany zgłoszenia, nie rozliczenia; rezerwacje, rozliczenia i uzgadnianie zwrotów nadal obowiązują.

Odzyskiwanie

Po timeout lub 5xx odczytaj ten sam klucz nawet bez ID zadania. Identyczne powtórzenie jest bezpieczne, ale nie uruchamia ponownie nieudanego wysłania. 404, pusta lista i brak opłat nie dowodzą nieprzyjęcia: pierwotne żądanie może być w drodze, bez klucza lub sprzed tej funkcji. same_key_replay_safe dotyczy odczytu potwierdzenia; new_submission_safe=true tylko dla not_accepted. Przy niepewnym wyniku albo accepted i task_ready=false podaj wsparciu ID potwierdzenia/żądania, model i czas UTC, nigdy API Key. Nie gwarantujemy idempotencji oficjalnego dostawcy. Stare potwierdzenia portretów zachowują dawną ścieżkę i mogą zwracać poprzedni schemat.

Przykłady

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"