Перейти до основного вмісту
Основна функція API запиту завдань Maestro — через ID завдання, повернений API генерації відео Maestro (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.
Request Body включає:

Приклад коду

Відповідний код CURL має такий вигляд:
Відповідний код Python має такий вигляд:

Приклад відповіді

Після успішного виконання запиту 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, а потім використовуйте цей інтерфейс для опитування результату.