Запрос видеозадачи

После создания задачи используйте id из ответа создания для запроса прогресса и результата; способ создания см. в разделе Создание видеозадачи.

Запрос статуса: GET /v1/video/generations/{task_id}

Загрузка готового видео: GET /v1/videos/{task_id}/content

После завершения задачи интерфейс запроса возвращает адрес видео в metadata.url. Платформа в первую очередь возвращает исходный адрес видео вышестоящей стороны; только если у вышестоящей стороны нет доступного адреса, используется адрес артефакта платформы с возможностью access. Исходный адрес вышестоящей стороны может содержать подпись и срок действия и открывается напрямую в браузере или плеере; адрес артефакта платформы также работает. Можно также с API Key вызвать /v1/videos/{task_id}/content для загрузки видеофайла.

Способ аутентификации

Authorization: Bearer <API_KEY>.

Параметры запроса · path

Пример запроса

curl "$LOCOPAL_API_ORIGIN/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Загрузка видео

После перехода задачи в статус completed используйте metadata.url из ответа запроса напрямую:

curl -L "$LOCOPAL_API_ORIGIN/v1/videos/$LOCOPAL_TASK_ID/content" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -o "$LOCOPAL_TASK_ID.mp4"

Параметры ответа

Тело ответа

В процессе выполнения:

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1787299277
}

Успешная генерация:

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "completed",
  "progress": 100,
  "created_at": 1787299277,
  "completed_at": 1787299581,
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800,
  "metadata": {
    "url": "https://upstream.example.com/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO.mp4?signature=...",
    "upstream_created": true
  },
  "usage": {
    "prompt_tokens": 141034,
    "completion_tokens": 0,
    "total_tokens": 141034,
    "quota": 2789652,
    "amount": 5.579304,
    "currency": "CNY"
  }
}

usage возвращается только после завершения и расчёта задачи, а значения полностью совпадают со списанием за эту задачу в счёте: usage.quota — потреблённые в этот раз баллы, usage.amount — сумма в юанях, в которую те же баллы пересчитаны по текущему курсу сайта, usage.total_tokens — число видеотокенов, тарифицируемых в этот раз. Пока задача стоит в очереди или генерируется, usage не возвращается, и по ответу запроса нельзя судить о стоимости; чтобы сверить списание, найдите задачу по тому же id в счёте консоли и сравните usage.quota и usage.amount.

metadata.url может быть подписанным адресом вышестоящей стороны или подстраховываться интерфейсом артефактов платформы. Обращайтесь с ним как с учётными данными и не публикуйте. После генерации готового видео рекомендуется скачать его или перенести в собственное объектное хранилище до наступления expires_at.

Артефакты видео и предпросмотр

Помимо прямого чтения metadata.url, можно запросить список артефактов платформы:

curl "$LOCOPAL_API_ORIGIN/v1/tasks/$LOCOPAL_TASK_ID/artifacts" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

После завершения задачи возвращается:

{
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://locopalai.com/v1/tasks/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO/artifacts/video/content?access=..."
    }
  ]
}

Адрес содержимого артефакта поддерживает Range-запросы; его можно напрямую использовать в плеерах, для предпросмотра в браузере и докачки файлов. Если клиент читает только metadata.url, он может продолжать использовать прежнюю логику и не обязан переходить на интерфейс артефактов.

Сбой генерации:

{
  "id": "task_NlersigX6rIqiOjCwTFlgNmGMTwqt39K",
  "object": "video",
  "model": "doubao-seedance-2.0-D",
  "status": "failed",
  "progress": 100,
  "created_at": 1789971935,
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  },
  "metadata": {
    "submission_stage": "submitting",
    "upstream_created": false
  }
}

error.message — итоговый текст сбоя, подготовленный платформой. Даже если историческая задача изначально хранила вложенный JSON, при запросе возвращается нормализованный текст; вызывающей стороне достаточно показать это поле пользователю и не нужно на клиенте склеивать или разбирать исходный JSON вышестоящей стороны.

Ответ с ошибкой

Запрос несуществующего ID задачи (или задачи, не принадлежащей текущей учётной записи) возвращает HTTP 400:

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Обработка статусов

Клиент не должен определять завершение по фиксированному числу секунд ожидания или повторно создавать задачу из-за одного сетевого тайм-аута; рекомендуется запрашивать раз в 5–15 секунд.

Сбой чтения референсных материалов

Если ошибка указывает на content[n].image_url, video_url или содержит resource download failed, сначала определите конкретный элемент по индексу массива, затем проверьте:

1. Можно ли напрямую выполнить GET по URL из публичной сети и получить 200;
2. Не происходит ли перенаправление на страницу входа и нет ли зависимости от Cookie, Referer, белого списка IP;
3. Соответствует ли Content-Type реальному формату файла;
4. Действителен ли временный подписанный URL во время загрузки и обработки;
5. Принадлежит ли материал asset:// текущей учётной записи и находится ли он в статусе Active;
6. Поддерживает ли текущая модель этот тип и количество материалов.

После исправления материалов создайте задачу заново. Сообщение об ошибке нужно показать пользователю один раз в читаемом виде; не выводите повторно склеенный многослойно экранированный JSON.

Параллельность, повторные попытки и тарификация

• Разные видеозадачи можно создавать параллельно;
• Для одного ответа создания всегда используйте один и тот же ID задачи при запросах;
• Новый запрос создания отправляйте только если задача явно завершилась сбоем и пользователь сам инициировал повтор;
• Тарификация детализируется по модели, разрешению, длительности и входному референсному видео; ориентируйтесь на каталог моделей и итоговый счёт; неудачная валидация параметров (400) означает, что запрос не принят, и обычно не приводит к расходам на задачу генерации.

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