prompt описываете желаемое видео (опционально прикладывая через file_urls референсные изображения / видео / аудио), а безголовый «AI-режиссёр» автоматически выполнит выбор темы, написание сценария, генерацию визуала, озвучку, создание музыки, компоновку и рендеринг, в итоге создав готовый ролик с субтитрами и загрузив его в CDN.
В этой статье будет подробно представлено руководство по интеграции API генерации видео Maestro, чтобы помочь вам быстро интегрировать и в полной мере использовать возможности данного API.
Это интерфейс асинхронных задач: после отправки сразу возвращается task_id, а затем результат получается через опрос API запросов задач Maestro (POST /maestro/tasks) (опрос бесплатен и не тарифицируется). Чтобы продолжить итерации над существующим видео, можно использовать action: remix / edit / extend вместе с ref_task_id.
Процесс подачи заявки
Чтобы использовать API генерации видео Maestro, сначала получите ваш API Token в консоли Ace Data Cloud и сохраните его для дальнейшего использования.
Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа с приглашением зарегистрироваться и войти, после завершения вы автоматически вернётесь на текущую страницу.
Один API Token позволяет вызывать все сервисы платформы, нет необходимости подавать отдельную заявку для каждого сервиса. При первой заявке будут предоставлены бесплатные квоты, позволяющие бесплатно опробовать сервис; при недостатке квоты можно пополнить универсальный баланс в консоли.
📘 Полная документация: API генерации видео Maestro →
Базовое использование
POST https://api.acedata.cloud/maestro/videos
Для самого базового использования достаточно передать описание на естественном языке prompt, а ИИ-режиссёр автоматически определит сценарий, визуальный ряд, озвучку и монтаж. Сначала рассмотрим необходимые заголовки и тело запроса.
Заголовки запроса включают:
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 предыдущей задачи, чтобы внести инкрементальные изменения на основе исходного проекта(например, «изменить заголовок второй сцены», «сменить озвучку», «сделать всё темнее»)。Небольшие изменения выполняются быстро, а крупные потребуют переработки:
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, для запроса статуса и результата задачи или получения списка исторических задач(опрос бесплатен)。

