> ## 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 — это **родной агент** интерфейс для производства видео: вы описываете желаемое видео с помощью естественного языка `prompt` (по желанию можно прикрепить `file_urls` с примерами изображений / видео / аудио), и безголовый «AI режиссер» автоматически завершает выбор темы, написание сценария, генерацию изображений, озвучивание, музыкальное сопровождение, компоновку и рендеринг, в конечном итоге создавая готовое видео с субтитрами и загружая его на CDN.

В этой статье подробно описывается интеграция Maestro Видео Генерации API, чтобы помочь вам быстро интегрировать и в полной мере использовать возможности этого API.

Это **асинхронный** интерфейс задач: после отправки сразу возвращается `task_id`, затем с помощью [Maestro API для запроса задач](/ru/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\[] | Нет | Ссылки на медиа (изображения / видео / аудио), например, изображения продукта, логотип или фрагменты материалов, к которым нужно добавить субтитры. |
| `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](/ru/guides/maestro/maestro_tasks).
* `trace_id`：ID отслеживания данного запроса, который можно предоставить технической поддержке для диагностики проблем.

Поскольку производство видео занимает много времени, интерфейс **немедленно возвращает `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](/ru/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`, с помощью которого можно опрашивать для получения итогового видео.

## Получение результатов

Поскольку производство видео занимает много времени, этот интерфейс немедленно возвращает `task_id` после отправки, вам нужно использовать его для опроса результатов через [API запроса задач Maestro](/ru/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](/ru/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](/ru/guides/maestro/maestro_tasks): используйте `POST /maestro/videos`, чтобы получить `task_id` для проверки статуса и результатов задачи или для получения списка историй задач (бесплатное опрашивание).


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