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.
prompt: опишіть природною мовою відео, яке потрібно створити (тема, що показати, стиль, аудиторія).langs: масив мов готового відео; щоразу передавайте лише одну мову, наприклад["zh-cn"]. За замовчуванням —["zh-cn"].aspect: співвідношення сторін,9:16(за замовчуванням) /16:9/1:1.duration: цільова тривалість (секунди), за замовчуванням — 30.
Нижче наведено конкретний приклад. Припустімо, потрібно згенерувати 20-секундне науково-популярне коротке відео китайською мовою у вертикальному форматі. Відповідний код CURL:
success: чи було це завдання успішно надіслано.task_id: ID цього завдання з генерації відео; надалі використовуйте його для опитування результату через API запитів завдань Maestro.trace_id: ID відстеження цього запиту; у разі проблем його можна надати технічній підтримці для діагностики.
task_id і не чекає завершення рендерингу відео. Далі потрібно використовувати task_id для опитування результату; докладніше дивіться в розділі «Отримання результату».
Вказання типу та стилю відео (scenario / style)
Якщо не передаватиscenario, його автоматично визначить AI (дорівнює auto); якщо потрібно прив’язати відео до певного типу, передайте його явно. Наприклад, для створення вертикальної короткої драми можна вказати такий вміст:
scenario:тип відео, тут встановленоdrama(коротка драма з персонажами + діалогами).style:візуальний стиль, тут встановленоcinematic(кінематографічна якість).
- Відео з озвученням:
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 є безкоштовним.
Обробка помилок
Під час виклику API, якщо виникає помилка, API повертає відповідний код помилки та повідомлення. Наприклад:400 invalid_request:Неправильний запит, можливо через відсутнійpromptабо некоректні параметри.401 invalid_token:Неавторизовано, недійсний або відсутній токен авторизації.403 forbidden:Заборонено, недостатній баланс або доступ.429 too_many_requests:Забагато запитів, ви перевищили ліміт частоти запитів.500 api_error:Внутрішня помилка сервера, на сервері щось пішло не так.
Приклад відповіді з помилкою
Висновок
Завдяки цьому документу ви вже дізналися, як використовувати API генерації відео Maestro: достатньо одногоprompt природною мовою, щоб автоматично виконати сценарій, матеріали, озвучення, музичний супровід, монтаж, субтитри та рендеринг готового відео; також підтримуються вказання типу відео, стилю, тембру голосу, мови готового відео та ітерації на основі наявного відео. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки в будь-який час.
Пов’язані інтерфейси
- Інструкція з інтеграції API запиту завдань Maestro:використовуйте
task_id, поверненийPOST /maestro/videos, щоб запитувати статус і результат завдання або отримувати список історичних завдань (опитування безкоштовне).

