Идемпотентность Seedance и восстановление отправок

Добавляйте Idempotency-Key для 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 используют общее пространство ключей. Изображения, оценка стоимости, remix и другие видеомодели не охвачены. Без ключа общей гарантии дедупликации нет.

Область действия и ключи

Ключ относится к аккаунту APIMaster и операции генерации видео Seedance, а не к отдельному API Key или модели. Для каждой новой генерации используйте новый случайный ключ из 8–128 видимых ASCII-символов. Действующий ключ того же аккаунта позволяет найти квитанцию. Токены с исчерпанной квотой могут читать или повторно получать существующие квитанции; истёкшие, отозванные, удалённые ключи и заблокированные аккаунты — нет. Новая генерация требует действующих полномочий и достаточной квоты.

Атомарные повторы и конфликты

До маршрутизации, списания и обращения к поставщику атомарно сохраняется запись в БД. Тот же ключ и содержимое возвращают HTTP 202, исходную квитанцию и заранее выделенный ID задачи без новой отправки или резервирования, включая конкурентные повторы и перезапуски. Изменение даёт HTTP 409 (idempotency_conflict). Порядок полей объектов JSON и пробелы игнорируются; порядок массивов, числа, пропущенные и явно заданные значения по умолчанию, модель, уведомления и группа/канал учитываются. multipart сравнивает байты и порядок файлов, не границы или имена. Сохраняйте тело и маршрутизацию; JSON и multipart различаются. Записи хранятся минимум 30 дней; автоматического удаления и повторного использования ключей в этой версии нет.

Ответы

Первый запрос сохраняет обычный ответ создания. Запишите X-Video-Submission-Id, ID запроса и задачи. Повтор возвращает квитанцию, формат может отличаться. Предварительный ID не доказывает принятие поставщиком. accepted не означает завершение генерации. Опрашивайте задачу только при task_ready=true; иначе обратитесь в поддержку без повторной отправки.

Состояния отправки

pending: записано шлюзом, отправка не начата. submitting: отправка начата, результат ожидается. accepted: получен ID поставщика. not_accepted: поставщику не отправлялось; исправьте ошибку и создайте с новым ключом. acceptance_unknown: возможно принято, подтверждения нет; новая генерация запрещена. После сбоя незавершённые записи классифицируются при чтении через 30 минут: до отправки not_accepted, после acceptance_unknown. Автоматических повторных отправок нет. Это состояния отправки, а не расчётов; резервирование, расчёт и сверка возвратов продолжают действовать.

Восстановление

После таймаута или 5xx ищите по тому же ключу даже без ID задачи. Идентичный повтор безопасен, но не перезапускает неудачную отправку. 404, пустой список и отсутствие списаний не доказывают непринятие: исходный запрос ещё в пути, без ключа или до появления функции. same_key_replay_safe означает повторное получение квитанции; new_submission_safe=true только для not_accepted. При неизвестном результате либо accepted с task_ready=false передайте поддержке ID квитанции/запроса, модель и время UTC, но не API Key. Идемпотентность официального поставщика не гарантируется. Старые квитанции портретов сохраняют прежний путь повторов и могут иметь старую схему.

Примеры

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"