Перейти до основного вмісту
Maestro — це Agent-нативний інтерфейс для створення відео: ви одним природномовним prompt описуєте бажане відео (за потреби додаєте через file_urls референсні зображення / відео / аудіо), а безголовий «AI-режисер» автоматично виконає вибір теми, написання сценарію, генерацію зображень, озвучення, створення музики, компонування та рендеринг, зрештою створивши готове відео із субтитрами та завантаживши його на CDN. У цій статті буде детально представлено інструкцію з інтеграції API генерації відео Maestro, щоб допомогти вам швидко інтегруватися та повною мірою використати можливості цього API. Це інтерфейс асинхронних завдань: після надсилання він негайно повертає task_id, а потім результат отримується шляхом опитування через API запиту завдань Maestro (POST /maestro/tasks) (опитування безкоштовне та не тарифікується). Щоб продовжити ітерації над наявним відео, можна використовувати action: remix / edit / extend разом із ref_task_id.

Процес подання заявки

Щоб використовувати API генерації відео Maestro, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати ваш API Token, і збережіть його для подальшого використання. Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку. Один API Token може викликати всі сервіси платформи, не потрібно подавати окрему заявку для кожного сервісу. Під час першого отримання надаються безкоштовні квоти для безкоштовного тестування; коли квоти недостатньо, можна поповнити універсальний баланс у консолі.
📘 Повна документація: API генерації відео Maestro →

Базове використання

POST https://api.acedata.cloud/maestro/videos Для найпростішого використання достатньо передати prompt природною мовою — AI-режисер автоматично визначить сценарій, візуальний ряд, озвучення та монтаж. Спочатку розгляньмо заголовки й тіло запиту, які потрібно налаштувати. Request Headers включають:
  • accept: формат відповіді, яку потрібно отримати. Тут вкажіть application/json, тобто формат JSON.
  • authorization: ключ для виклику API. Після отримання його можна безпосередньо вибрати зі спадного списку.
  • content-type: формат тіла запиту. Тут вкажіть application/json.
Request Body переважно містить:
  • prompt: опишіть природною мовою відео, яке потрібно створити (тема, що показати, стиль, аудиторія).
  • langs: масив мов готового відео; щоразу передавайте лише одну мову, наприклад ["zh-cn"]. За замовчуванням — ["zh-cn"].
  • aspect: співвідношення сторін, 9:16 (за замовчуванням) / 16:9 / 1:1.
  • duration: цільова тривалість (секунди), за замовчуванням — 30.
Усі поля тіла запиту наведено в таблиці нижче: Нижче наведено конкретний приклад. Припустімо, потрібно згенерувати 20-секундне науково-популярне коротке відео китайською мовою у вертикальному форматі. Відповідний код CURL:
Відповідний код Python:
Натисніть «Запустити» — і ви одразу отримаєте результат, як показано нижче:
Опис полів результату наведено нижче:
  • success: чи було це завдання успішно надіслано.
  • task_id: ID цього завдання з генерації відео; надалі використовуйте його для опитування результату через API запитів завдань Maestro.
  • trace_id: ID відстеження цього запиту; у разі проблем його можна надати технічній підтримці для діагностики.
Оскільки створення відео займає тривалий час, API негайно повертає task_id і не чекає завершення рендерингу відео. Далі потрібно використовувати task_id для опитування результату; докладніше дивіться в розділі «Отримання результату».

Вказання типу та стилю відео (scenario / style)

Якщо не передавати scenario, його автоматично визначить AI (дорівнює auto); якщо потрібно прив’язати відео до певного типу, передайте його явно. Наприклад, для створення вертикальної короткої драми можна вказати такий вміст:
  • scenario:тип відео, тут встановлено drama (коротка драма з персонажами + діалогами).
  • style:візуальний стиль, тут встановлено cinematic (кінематографічна якість).
CURL-код прикладу заповнення наведено нижче:
Поширені способи поєднання:
  • Відео з озвученням: scenario: "narrated".
  • Автоматичні субтитри: scenario: "captions", потрібно передати вихідне відео через file_urls.
  • Цифрова людина / усне мовлення: scenario: "avatar", потрібно передати одне зображення обличчя через file_urls.
  • Коротка драма: scenario: "drama" (персонажі + діалоги).
  • style — це передвстановлення візуального стилю (наприклад, modern / neon / luxury), воно не змінює тип, а лише впливає на візуальне сприйняття.
  • voice використовується для вказання тембру голосу диктора (наприклад, warm-female / deep-male), не залежить від мови та є універсальним для різних мов.
Результат відповіді такий самий, як у «Базовому використанні»: також негайно повертається task_id.

Мова готового відео

Одне завдання надає лише одне готове відео однією мовою. langs може містити лише один мовний код, наприклад ["zh-cn"] або ["en"]; передавання кількох мов поверне 400. Якщо потрібні відео різними мовами, створюйте окремі завдання. Вибір мови не змінює ціну за секунду.

Ітерація на основі наявного відео (remix / edit / extend)

Передайте action і ref_task_id попереднього завдання, щоб вносити часткові зміни на основі оригінального проєкту (наприклад, «змінити заголовок 2-ї сцени», «змінити озвучення», «загалом затемнити»). Невеликі зміни виконуються швидко, а значні зміни потребуватимуть повторного створення:
  • remix:повторна інтерпретація на основі структури оригінального відео (зберігає тему, змінює подачу).
  • edit:точне редагування вказаної частини (наприклад, зміна заголовка, озвучення, кольорокорекції).
  • extend:розширення вмісту на основі оригінального відео.
Результат відповіді також негайно повертає новий task_id, використовуйте його для опитування та отримання готового відео після ітерації.

Отримання результату

Оскільки створення відео займає тривалий час, цей інтерфейс негайно повертає task_id після подання, і вам потрібно використовувати його для опитування результату через API запиту завдань Maestro:
Після завершення завдання повертається інформація про одне готове відео (у масиві variants). status проходитиме через pending → planning → producing → succeeded (або failed), опитування безкоштовне та не витрачає бали. Повний формат відповіді та запит списку історії дивіться в інструкції з інтеграції API запиту завдань Maestro.

Тарифікація

Після успішного виконання завдання оплата стягується відповідно до фактичної тривалості наданого готового відео; у разі невдачі плата не стягується. Тривалість для тарифікації обчислюється в цілих секундах і не перевищує запитувану тривалість; якщо тривалість готового відео не вдається прочитати, використовується запитувана тривалість. Саме подання завдання окремо не тарифікується, опитування /maestro/tasks є безкоштовним.
Усі сценарії, дії та мови мають однакову ціну, без множників сценарію або доплат за мову. Кожне завдання надає лише одне готове відео однією мовою. Запитувана цільова тривалість підтримується від 5 до 300 секунд, уніфікований вихід — 1080p / 30fps.

Обробка помилок

Під час виклику API, якщо виникає помилка, API повертає відповідний код помилки та повідомлення. Наприклад:
  • 400 invalid_request:Неправильний запит, можливо через відсутній prompt або некоректні параметри.
  • 401 invalid_token:Неавторизовано, недійсний або відсутній токен авторизації.
  • 403 forbidden:Заборонено, недостатній баланс або доступ.
  • 429 too_many_requests:Забагато запитів, ви перевищили ліміт частоти запитів.
  • 500 api_error:Внутрішня помилка сервера, на сервері щось пішло не так.

Приклад відповіді з помилкою

Висновок

Завдяки цьому документу ви вже дізналися, як використовувати API генерації відео Maestro: достатньо одного prompt природною мовою, щоб автоматично виконати сценарій, матеріали, озвучення, музичний супровід, монтаж, субтитри та рендеринг готового відео; також підтримуються вказання типу відео, стилю, тембру голосу, мови готового відео та ітерації на основі наявного відео. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки в будь-який час.

Пов’язані інтерфейси