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: 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 timestamp (секунди). Якщо завдання не завершено, значення — 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, а потім використовуйте цей інтерфейс для опитування результату.

