Skip to main content

​
Краткий ответ

Согласно текущей общедоступной документации API Seedance 2.0, API предоставляет создание задач и запросы статуса задач, но не предоставляет эндпоинт для отмены или удаления задач. После успешного создания задачи API возвращает task_id. Тайм-аут на стороне клиента, сетевой сбой, закрытие веб-страницы или остановка опроса не должны считаться подтверждением отмены задачи. Запросите исходную задачу, прежде чем решать, следует ли повторить попытку, чтобы не создавать дублирующиеся задачи.

​
Публичные эндпоинты и статусы задач

В настоящее время Seedance 2.0 использует эндпоинты асинхронных задач: Обычно задача проходит следующий жизненный цикл:
  • queued: Задача создана и ожидает в очереди.
  • running: Задача обрабатывается.
  • succeeded: Генерация видео успешно завершена.
  • failed: Обработка задачи завершилась с ошибкой.
  • expired: Задача превысила допустимое время выполнения и истекла.
После успешной генерации URL видео возвращается в:
Это временный подписанный URL. В текущей документации указано, что он действителен примерно 24 часа. Сразу после успешного выполнения задачи скачайте видео и сохраните его.
Текущая публичная документация API не содержит эндпоинта для отмены задачи. Остановка локального скрипта или прекращение опроса лишь прекращает запросы клиента; это не подтверждает, что задача на стороне сервера была отозвана.

​
Что делать после отправки задачи?

​
Шаг 1. Сохраните идентификатор задачи и сведения о запросе

Сразу сохраните возвращённый task_id после успешного выполнения запроса на создание. Также следует сохранить:
  • Название модели;
  • Промпт или краткое описание промпта;
  • Важные параметры, такие как длительность, разрешение и соотношение сторон;
  • Время отправки;
  • Идентификатор запроса;
  • Идентификатор операции в вашей системе.
Эти сведения помогут позднее запрашивать состояние задачи, устранять неполадки и сверять записи о тарификации.

​
Шаг 2. Запросите исходную задачу

Для задач Seedance 2.0 обычно требуется несколько минут. В текущей документации API рекомендуется:
  • Подождать около 20–30 секунд после отправки перед первым запросом;
  • После этого отправлять запрос каждые 10–20 секунд;
  • Не отправлять запрос повторно сразу только потому, что видео ещё недоступно.
Пример запроса задачи:
Замените заполнители реальными значениями:
  • YOUR_TASK_ID: Идентификатор задачи, возвращённый эндпоинтом создания задачи;
  • YOUR_API_KEY: API-ключ, созданный в консоли APIYI.

​
Шаг 3. Обработайте каждый статус задачи

Обрабатывайте возвращённый статус следующим образом:
  • queued: Задача всё ещё ожидает выполнения; продолжайте ожидание и отправку запросов.
  • running: Задача всё ещё выполняется; продолжайте ожидание и отправку запросов.
  • succeeded: Немедленно скачайте видео по адресу content.video_url.
  • failed: Проверьте сведения error в ответе.
  • expired: Просмотрите сведения о задаче и журналы вызовов, чтобы определить причину её истечения.
Не считайте queued или running ошибками и не создавайте другую задачу только потому, что текущая задача ещё не завершена.

​
Шаг 4. Подтвердите статус задачи после тайм-аута клиента

Не повторяйте запрос немедленно, если клиент не получил полный ответ. Проверьте следующее по порядку:
  1. Проверьте, содержит ли ответ клиента task_id.
  2. Проверьте, есть ли запись о задаче в журналах вызовов консоли.
  3. Если существует task_id, сначала запросите исходную задачу.
  4. Если task_id пока не отображается, не делайте вывод об отсутствии созданной задачи только на основании сетевой ошибки.
  5. Если вы не можете подтвердить, была ли создана задача, попросите службу поддержки проверить это до повторной отправки запроса.
Тайм-аут клиента означает только то, что клиент не получил ответ в течение ожидаемого времени. Сам по себе он не доказывает, что сервер не создал задачу.

​
Как предотвратить дублирующие отправки?

Ниже приведены инженерные практики на стороне интеграции, а не обязательные правила платформы:
  • Создавайте уникальный бизнес-ID для каждого запроса.
  • Сохраняйте соответствие между бизнес-ID и task_id Seedance.
  • Временно отключайте кнопку отправки после отправки запроса пользователем.
  • После тайм-аута клиента или завершения процесса возобновляйте работу, запрашивая исходную задачу.
  • Сохраняйте промпт, модель, длительность, соотношение сторон и сведения о референсных материалах.
  • Выполняйте новую отправку только после подтверждения того, что исходная задача не существует или явно завершилась с ошибкой.
  • Различайте статусы выполнения и конечные статусы. Не считайте queued или running ошибками.
Для агентов, скриптов и фоновых служб разделяйте операции создания задачи и запроса задачи:
Это позволяет процессу после локального перезапуска возобновить запрос исходной задачи вместо создания другой задачи.

​
Как сверить тарификацию после повторных отправок?

В текущей документации по Seedance 2.0 процесс тарификации описан следующим образом:
Изменения баланса и записи в журнале поэтому могут отображаться не как одна операция. В обзорной документации также указано, что одной видеозадаче могут соответствовать несколько записей в журнале: предварительное списание и последующее окончательное списание. Используйте журналы вызовов как окончательный источник информации. В текущей документации также указано, что запрос, отклонённый из-за недопустимых параметров и не создавший задачу, например запрос InvalidParameter HTTP 400, не тарифицируется. Однако следующие обстоятельства сами по себе не позволяют определить, было ли выполнено списание:
  • Тайм-аут клиента;
  • Разрыв сетевого соединения;
  • failed;
  • expired;
  • Клиент не получил полный ответ;
  • Клиент отображает ошибку запроса, хотя сервер мог создать задачу.
Если уже было создано несколько задач, прекратите отправлять новые задачи и соберите:
  • Все связанные значения Seedance task_id;
  • Соответствующие идентификаторы запросов;
  • Время отправки;
  • Названия моделей;
  • Важные параметры запросов;
  • Журналы вызовов в консоли;
  • Снимки экрана с записями о тарификации или списаниях.
Затем обратитесь в службу поддержки для ручной проверки. Факт списания за задачу, наличие повторных списаний и доступность каких-либо действий в рамках тарификации должны определяться на основании записей о задачах, журналов вызовов, записей о тарификации и результатов проверки платформы.
Не делайте вывод о том, что за задачу было или не было выполнено списание, основываясь только на failed, expired или тайм-ауте клиента.

​
Часто задаваемые вопросы

​
Останавливает ли прекращение опроса автоматически задачу Seedance?

Это нельзя считать гарантированным. Прекращение опроса означает лишь, что клиент больше не запрашивает статус задачи. В текущей общедоступной документации API не предусмотрен эндпоинт отмены, поэтому прекращение опроса не означает, что задача на стороне сервера была отменена. Сохраните исходный task_id и запросите его снова позже.

​
Можно ли повторить запрос сразу после истечения времени ожидания?

Мы не рекомендуем немедленно повторять запрос. Сначала проверьте:
  • Содержит ли ответ task_id;
  • Есть ли запись о задаче в журналах вызовов консоли;
  • Текущий статус исходной задачи;
  • Существует ли уже соответствующая запись тарификации.
Если исходная задача была создана, запросите её статус, прежде чем создавать другую задачу для того же бизнес-запроса.

​
Означает ли статус «ошибка» или «истёк срок», что списание не произошло?

Нельзя определить результат тарификации только по статусу задачи. Seedance 2.0 использует предварительное списание при отправке с последующей тарификацией после завершения. Проверьте журналы вызовов и записи тарификации. Если записи выглядят некорректно, передайте в службу поддержки идентификатор задачи и идентификатор запроса для проверки.

​
Взимается ли плата за HTTP 400, вызванный недопустимыми параметрами?

В текущей документации указано, что запрос, отклонённый из-за недопустимых параметров без создания задачи, не тарифицируется. Примеры:
  • Недопустимые форматы параметров;
  • Неподдерживаемое разрешение;
  • Недопустимое соотношение сторон;
  • Неподдерживаемая длительность видео;
  • Несовместимое сочетание модели и параметров.
Не классифицируйте каждый ответ HTTP 400 как один и тот же случай. Используйте конкретное сообщение об ошибке, запись о задаче и журналы вызовов в качестве окончательного ориентира.

​
Как долго можно хранить URL сгенерированного видео?

В текущей документации указано, что content.video_url в успешном ответе представляет собой временный подписанный URL, действительный примерно 24 часа. Скачайте и сохраните видео сразу после перехода задачи в статус succeeded. Не рассматривайте этот URL как постоянный. В текущей документации также указано, что сам идентификатор задачи хранится 7 дней. Тем не менее вам следует сохранять собственную запись о задаче для отслеживания бизнес-операций.

​
Связанная документация

​
Свяжитесь с поддержкой

Обратитесь в службу поддержки за помощью, если:
  • Задача остаётся в состоянии queued или running необычно долго;
  • Вы не можете подтвердить, была ли создана задача после истечения времени ожидания клиента;
  • После повторной отправки было создано несколько задач;
  • Статус задачи и запись о тарификации не совпадают;
  • Для успешно выполненной задачи не возвращается видео или его нельзя скачать.
При обращении в службу поддержки предоставьте как можно больше следующей информации:
  • Идентификатор Seedance task_id;
  • Идентификатор запроса;
  • Время отправки;
  • Название модели;
  • Важные параметры запроса;
  • Журналы вызовов консоли;
  • Связанные записи о тарификации.
Точка входа в службу поддержки: поддержка APIYI в WeCom