POST /maestro/videos), запрашивать статус выполнения и окончательный результат этой задачи.
В этом документе будет подробно описана интеграция API запроса задач Maestro. Поскольку генерация видео является асинхронной задачей, после отправки необходимо использовать этот интерфейс для опроса и получения прогресса и готового видео, опрос бесплатный и не расходует баллы.
POST https://api.acedata.cloud/maestro/tasks
Процесс получения
Чтобы использовать API запроса задач Maestro, сначала перейдите в консоль Ace Data Cloud, чтобы получить ваш API Token и сохранить его для последующего использования.
Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти в систему, после чего вы автоматически вернётесь на текущую страницу.
Один API Token позволяет вызывать все сервисы платформы, нет необходимости подавать отдельную заявку для каждого сервиса. При первом получении предоставляется бесплатный лимит, позволяющий бесплатно ознакомиться с сервисом; при недостатке лимита вы можете пополнить универсальный баланс в консоли.
📘 Полная документация: API запроса задач Maestro →
Запрос одной задачи
О том, как создать задачу видео, смотрите документацию API генерации видео Maestro. В качестве примера возьмём один из возвращённых им ID задач:f57e99c4f60f4373a15517742ce2357d, и покажем, как запросить его статус и результат.
Настройка заголовков и тела запроса
Request Headers включают:accept: указывает получение результата ответа в формате JSON, здесь указываетсяapplication/json.authorization: ключ для вызова API, после получения можно напрямую выбрать из выпадающего списка.content-type: формат тела запроса, здесь указываетсяapplication/json.
Пример кода
Соответствующий CURL-код выглядит следующим образом:Пример ответа
После успешного выполнения запроса API вернёт статус и результат этой видеозадачи. Пример ответа после завершения задачи приведён ниже (массивvariants содержит один готовый видеоролик):
id: идентификатор этой видеозадачи, используемый для её уникальной идентификации.status: статус задачи; возможные значения:pending → planning → producing → succeeded(илиfailed). Признаком завершения задачи является верхнеуровневое полеstatus.elapsed: время выполнения задачи (в секундах).progress: объект верхнеуровневого прогресса. Значениеpercent(0–100) после успешного выполнения задачи равно 100;stageиmessageотражают последнее событие прогресса AI-режиссёра (поэтому после успехаstageможет по-прежнему указывать на последний этап выполнения, напримерproducing). Может использоваться непосредственно для отображения индикатора выполнения.request: тело запроса при запуске задачи.response: информация, возвращаемая задачей.success: признак успешного выполнения задачи.data.variants: содержит объект готового видеоролика на выбранном языке, включаяlang,aspect,title,output_url(адрес загрузки готового ролика) и другие поля.data.project: артефакты всего проекта, включаяtarball_url(пакет проекта) иoutputs(ссылка на готовый видеоролик).data.progress: массив событий прогресса, добавляемых по этапам (журнал только с добавлением), который можно использовать для отображения подробного прогресса в реальном времени.
created_at: время создания задачи, метка времени Unix (в секундах).started_at: время начала выполнения задачи, метка времени Unix (в секундах). До начала выполнения задачи значение равно null.finished_at:время завершения задачи, метка времени Unix (в секундах). Если задача не завершена, значение — null.
Запрос списка истории
Передайтеaction: retrieve_batch, чтобы получить последние задачи текущего вошедшего исполнителя (в обратном порядке по времени создания); это можно использовать для страницы списка «Мои видео». Список истории изолирован по учётной записи входа.
Request Body включает:
Пример кода
Соответствующий CURL-код выглядит следующим образом:Пример ответа
После успешного выполнения запроса API вернёт список исторических задач текущего пользователя:count:общее количество задач, видимых текущему вошедшему исполнителю, не зависит от временных условий илиlimit。items:массив задач, отфильтрованных по временным условиям иlimit, отсортированный по времени создания в обратном порядке;формат каждого элемента соответствует результату возврата «Запроса одной задачи».
Рекомендации по опросу
Поскольку производство видео занимает длительное время,status будет проходить через pending → planning → producing → succeeded(или failed)。Рекомендуется выполнять опрос каждые 5–10 секунд, пока status не станет succeeded или failed。Для отображения индикатора прогресса в реальном времени можно использовать progress.percent верхнего уровня。Опрос этого интерфейса бесплатен и не расходует баллы。
Обработка ошибок
При вызове API, если возникает ошибка, API вернёт соответствующий код ошибки и информацию. Например:401 invalid_token:Не авторизован, недействительный или отсутствующий токен авторизации.404 not_found:Задача не найдена, указанный task_id не существует.429 too_many_requests:Слишком много запросов, вы превысили лимит запросов.500 api_error:Внутренняя ошибка сервера, на сервере произошла ошибка.
Пример ответа с ошибкой
Заключение
Из этой документации вы уже узнали, как использовать API запросов задач Maestro для запроса статуса и результата одной задачи, а также для получения списка исторических задач текущего пользователя. Надеемся, эта документация поможет вам лучше интегрировать и использовать этот API. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки в любое время.Связанные интерфейсы
- Инструкция по интеграции API генерации видео Maestro:автоматическое создание готового видео с субтитрами с помощью одной подсказки на естественном языке; после отправки возвращается
task_id, затем для опроса результата используется этот интерфейс.

