> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro відео генерації API інтеграційна інструкція

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro — це **Agent рідний** відео виробничий інтерфейс: ви описуєте бажане відео однією природною мовою `prompt` (за бажанням можна додати `file_urls` з посиланнями на зображення / відео / аудіо), безголовий «AI режисер» автоматично виконає вибір теми, напише сценарій, згенерує зображення, озвучить, підбере музику, зкомпонує та відрендерить, в результаті чого буде створено готове відео з субтитрами та завантажено на CDN.

У цій статті буде детально описано інтеграцію Maestro відео генерації API, щоб допомогти вам швидко інтегрувати та повністю використовувати можливості цього API.

Це **асинхронний завдання** інтерфейс: після подачі буде негайно повернуто `task_id`, а потім через [Maestro завдання запит API](/uk/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) можна опитувати результати (опитування безкоштовне, не підлягає оплаті). Щоб продовжити ітерацію на вже існуючому відео, можна використовувати `action: remix` / `edit` / `extend` разом з `ref_task_id`.

## Процес подачі заявки

Щоб використовувати Maestro відео генерації API, спочатку перейдіть до [Ace Data Cloud консолі](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token, залиште його на випадок потреби.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після чого ви будете автоматично повернені на цю сторінку.

**Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно спробувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в [консолі](https://platform.acedata.cloud/console/coin).

> 📘 Повна документація: [Maestro відео генерації API →](https://platform.acedata.cloud/documents/maestro-videos)

## Основне використання

`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", "en"]`, за замовчуванням `["zh-cn"]`.
* `aspect`: співвідношення сторін, `9:16` (за замовчуванням) / `16:9` / `1:1`.
* `duration`: цільова тривалість (секунди), за замовчуванням 30.

Усі поля тіла запиту наведені в таблиці нижче:

| Поле | Тип | Обов'язково | Опис |
| - | - | - | - |
| `prompt` | string | Так | Описуєте відео природною мовою (тема, що показати, стиль, аудиторія). Сценарій, зображення, озвучення, монтаж визначає AI |
| `action` | string | Ні | `generate` (за замовчуванням, створити нове відео) / `remix` / `edit` / `extend` (ітерація на вже існуючому відео, потрібно разом з `ref_task_id`) |
| `ref_task_id` | string | Ні | Обов'язково, коли `action` є remix / edit / extend: історичний `task_id`, з якого почати |
| `file_urls` | string\[] | Ні | Посилання на медіа (зображення / відео / аудіо URL), наприклад, зображення продукту, логотип або фрагменти матеріалів, до яких потрібно додати субтитри |
| `langs` | string\[] | Ні | Мови виводу, наприклад, `["zh-cn", "en"]`, за замовчуванням `["zh-cn"]`. Перша мова є основною; за кожну додаткову мову повторюється зображення, лише додається озвучення + рендеринг, **за кожну додаткову +6 балів** |
| `aspect` | string | Ні | `9:16` (за замовчуванням) / `16:9` / `1:1`, єдиний вихід 1080p/30fps |
| `duration` | int | Ні | Цільова тривалість (секунди), за замовчуванням 30, підтримує **5–300 секунд**. Оплата за фактичну тривалість готового відео, але не перевищує запитувану тривалість |
| `scenario` | string | Ні | Тип відео: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` вимагає наявності вихідного відео, `avatar` вимагає наявності зображення людини |
| `style` | string | Ні | Візуальний стиль: `auto` (за замовчуванням) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, також приймає вільний текст як м'який підказка. Не змінює маршрут |
| `voice` | string | Ні | Голос озвучення (незалежно від мови, універсальний для всіх мов): `auto` (за замовчуванням) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male` |

Нижче наведено конкретний приклад. Припустимо, ми хочемо створити двомовне (китайською та англійською), вертикальне, 20-секундне науково-популярне відео, відповідний CURL код виглядає так:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

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

```python theme={null}
import requests

url = "https://api.acedata.cloud/maestro/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Коли ви натискаєте "Запустити", ви отримаєте результат, як показано нижче:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

Опис полів у повернутому результаті виглядає наступним чином:

* `success`：Чи успішно подано це завдання.
* `task_id`：ID цього завдання на генерацію відео, надалі його використовують для опитування результатів через [API запитів Maestro](/uk/guides/maestro/maestro_tasks).
* `trace_id`：ID відстеження цього запиту, який можна надати технічній підтримці для локалізації проблеми.

Оскільки виробництво відео займає багато часу, API **відразу повертає `task_id`**, і не чекає завершення рендерингу відео. Далі потрібно використовувати `task_id` для опитування результатів, деталі дивіться в розділі «Отримати результати».

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

Якщо не передати `scenario`, AI автоматично визначить (еквівалентно `auto`); якщо хочете закріпити відео за певним типом, передайте його явно. Наприклад, для створення **вертикального короткометражного фільму** можна вказати такі дані:

* `scenario`：тип відео, тут встановлено `drama` (короткометражка з персонажами + діалогами).
* `style`：візуальний стиль, тут встановлено `cinematic` (кінематографічна якість).

Приклад CURL коду:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Два сусіди по кімнаті через кота посварилися, але потім помирилися, три акти з поворотами, закінчення тепле",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

Звичні комбінації:

* Оповідний короткометражний фільм: `scenario: "narrated"`, підтримується Lite / Standard / Pro.
* Автоматичні субтитри: `scenario: "captions"`, потрібно передати вихідне відео через `file_urls`, підтримується Lite / Standard / Pro.
* Цифрова людина / озвучка: `scenario: "avatar"`, потрібно передати зображення людини через `file_urls`, підтримується Standard / Pro.
* Короткометражка: `scenario: "drama"` (персонажі + діалоги), підтримується лише Pro.
* `style` є попередньо визначеним візуальним стилем (наприклад, `modern` / `neon` / `luxury`), не змінює тип, лише впливає на сприйняття.
* `voice` використовується для визначення тону озвучки (наприклад, `warm-female` / `deep-male`), не залежить від мови, універсально для всіх мов.

Результат повертається так само, як і в «Основному використанні», також відразу повертає `task_id`.

## Багатомовний вихід

Передайте кілька мов у `langs`, щоб одночасно отримати багатомовні версії. Перша мова є основною, а кожна наступна мова буде **використовувати ту ж саму картинку**, лише додатково озвучуючи + рендеруючи, тому **кожна додаткова мова лише +6 балів**. Приклад:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Представте наш продукт інтелектуального обслуговування клієнтів, підкресліть 3 основні переваги",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

Після завершення завдання кожна мова відповідатиме одному `variant` у результаті (див. [API запитів Maestro](/uk/guides/maestro/maestro_tasks)).

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

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

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "Змінити заголовок на більш вражаючий, загальна кольорова гамма більш темна"
}'
```

* `remix`：переробка на основі структури оригінального відео (збереження теми, коригування виконання).
* `edit`：точне редагування певної частини (наприклад, зміна заголовка, зміна озвучки, корекція кольору).
* `extend`：розширення змісту на основі оригінального відео.

Результат також відразу повертає новий `task_id`, за яким можна опитувати, щоб отримати готовий продукт.

## Отримати результати

Оскільки виробництво відео займає багато часу, цей API відразу повертає `task_id` після подання, вам потрібно використовувати його для опитування результатів через [API запитів Maestro](/uk/guides/maestro/maestro_tasks):

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d"
}'
```

Після завершення завдання буде повернено інформацію про готовий продукт (кожна мова відповідатиме одному `variant`). `status` проходитиме через `pending → planning → producing → succeeded` (або `failed`), **опитування безкоштовне, не витрачає бали**. Повний формат відповіді та історію запитів дивіться в [інструкції з інтеграції API запитів Maestro](/uk/guides/maestro/maestro_tasks).

## Оплата

**Оплата здійснюється після завершення завдання за фактичною готовою продукцією, за невдалі завдання плата не стягується.** Оплата базується на фактичній тривалості готового продукту та кількості мов, і тривалість оплати не перевищить тривалість запиту. Якщо якась мова в результаті не була отримана, за цю мову також не стягується +6. Подання завдання само по собі не підлягає окремій оплаті, опитування `/maestro/tasks` безкоштовне.

Бали за один готовий продукт розраховуються за формулою:

```
бали = тривалість готового продукту в секундах × 0.60 × множник сцени + 6 × max(кількість мов − 1, 0)
```

Maestro стягує **0.60 балів/фактичні секунди готового продукту**, підтримує 5–300 секунд, максимум 4 мови та вихід 1080p / 30fps; всі дії та сцени доступні.

Множник сцени: `drama` 1.35× / `avatar` 1.15× / інші 1×.

| Приклад | Бали |
| - | -: |
| Lite 30 секунд | 6 |
| Standard 30 секунд | 18 |
| Standard 60 секунд | 36 |
| Standard 120 секунд | 72 |
| Pro 30 секунд | 36 |
| Pro 300 секунд | 360 |
| Кожна додаткова фактична мова | +6 |
| Опитування `/maestro/tasks` | Безкоштовно |

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

При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад:

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

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "не вдалося отримати"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Висновок

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

## Відповідні інтерфейси

* [Опис інтеграції API запитів Maestro](/uk/guides/maestro/maestro_tasks): використовуйте `POST /maestro/videos`, щоб отримати `task_id` для перевірки статусу та результатів завдання або для отримання списку історичних завдань (опитування безкоштовне).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.