Описание интеграции API запроса задач Maestro

Основная функция API запроса задач Maestro — по ID задачи, возвращённому API генерации видео Maestro (POST /maestro/videos), запрашивать статус выполнения и итоговый результат этой задачи. В этом документе будет подробно представлено описание интеграции API запроса задач Maestro. Поскольку генерация видео является асинхронной задачей, после отправки необходимо использовать этот интерфейс для опроса и получения прогресса и готового видео, опрос бесплатный и не расходует кредиты. POST https://api.acedata.cloud/maestro/tasks

Процесс получения доступа

Чтобы использовать API запроса задач Maestro, сначала перейдите в консоль Ace Data Cloud, чтобы получить ваш API Token и сохранить его для дальнейшего использования.

Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти в систему; после завершения вы автоматически вернётесь на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, не требуется подавать отдельную заявку для каждого сервиса. При первом получении предоставляется бесплатный лимит для бесплатного ознакомления; при недостатке лимита вы можете пополнить общий баланс в консоли.

📘 Полная документация: API запроса задач Maestro →

Запрос одной задачи

О том, как создавать задачи видео, см. документацию API генерации видео Maestro. В качестве примера возьмём один возвращённый им ID задачи: f57e99c4f60f4373a15517742ce2357d, чтобы показать, как запросить его статус и результат.

Настройка заголовков и тела запроса

Request Headers включают:

accept: указывает получение результатов ответа в формате JSON, здесь указывается application/json.
authorization: ключ для вызова API, после получения его можно напрямую выбрать из выпадающего списка.
content-type: формат тела запроса, здесь указывается application/json.

Request Body включает:

Поле	Тип	Обязательное	Описание
`id`	string	Обязательно при запросе одной задачи	`task_id`, возвращаемый `POST /maestro/videos`
`action`	string	Нет	`retrieve` (по умолчанию, запрос одной задачи); при запросе списка истории всегда `retrieve_batch`

Пример кода

Соответствующий код CURL выглядит следующим образом:

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",
  "action": "retrieve"
}'

Соответствующий код Python выглядит следующим образом:

import requests

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

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

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

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

Пример ответа

После успешного запроса API вернёт статус и результат этой задачи видео. Пример ответа после завершения задачи выглядит следующим образом (каждому языку соответствует один variant):

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

Описание полей возвращаемого результата выглядит следующим образом:

id: ID этой задачи видео, используется для уникальной идентификации текущей задачи генерации видео.
status: статус задачи, значения: pending → planning → producing → succeeded (или failed). Завершена ли задача, определяется этим верхнеуровневым status.
elapsed: затраченное задачей время (секунды).
progress: верхнеуровневый объект прогресса, percent (0–100) после успешного выполнения задачи гарантированно будет равен 100; stage и message отражают последнее событие прогресса AI-режиссёра (поэтому после успеха stage всё ещё может быть последним этапом выполнения, например producing), может напрямую использоваться для отображения индикатора прогресса.
request: тело запроса при запуске задачи.
response: информация о возврате задачи.
- success: успешно ли выполнена задача.
- data.variants: каждому языку соответствует один объект готового видео, содержащий lang, aspect, title, output_url (адрес скачивания готового видео) и т. д.
- data.project: результаты всего проекта, содержащие tarball_url (пакет проекта) и outputs (ссылки на все готовые видео).
- data.progress: массив событий прогресса, добавляемых по этапам (журнал append-only), может использоваться для отображения подробного прогресса в реальном времени.
created_at: время создания задачи, Unix timestamp (секунды).
started_at: время начала выполнения задачи, Unix timestamp (секунды). До начала задачи равно null.
finished_at: время завершения задачи, Unix timestamp (секунды). До завершения задачи равно null.

Запрос списка истории

Передайте action: retrieve_batch, чтобы получить последние задачи текущего вошедшего исполнителя (в обратном порядке по времени создания); может использоваться для страницы списка «Мои видео». Список истории изолирован по учётной записи, вошедшей в систему. Request Body включает:

Поле	Тип	Обязательно	Описание
`action`	string	Да	Фиксированное значение: `retrieve_batch`
`limit`	int	Нет	Количество возвращаемых записей, по умолчанию 20; допустимый диапазон 1–100
`created_at_max`	int	Нет	Возвращать только задачи, строго созданные до этой Unix-метки времени (без граничного значения, для пагинации)
`created_at_min`	int	Нет	Возвращать только задачи, строго созданные после этой Unix-метки времени (без граничного значения)

Пример кода

Соответствующий CURL-код приведён ниже:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

Пример ответа

После успешного запроса API вернёт список исторических задач текущего пользователя:

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

Описание полей возвращаемого результата приведено ниже:

count: общее количество задач, видимых текущему вошедшему в систему исполнителю, не зависит от условий времени или limit.
items: массив задач, отфильтрованных по условиям времени и limit, отсортированный по времени создания в обратном порядке; формат каждого элемента совпадает с результатом возврата «Запроса одной задачи».

Обработка ошибок

При вызове API, если возникает ошибка, API вернёт соответствующий код ошибки и сообщение. Например:

401 invalid_token: Не авторизован, недействительный или отсутствующий токен авторизации.
404 not_found: Задача не найдена, указанный task_id не существует.
429 too_many_requests: Слишком много запросов, вы превысили ограничение скорости.
500 api_error: Внутренняя ошибка сервера, на сервере что-то пошло не так.

Пример ответа с ошибкой

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Заключение

С помощью этого документа вы уже узнали, как использовать API запросов задач Maestro для запроса статуса и результата отдельной задачи, а также для получения списка исторических задач текущего пользователя. Надеемся, этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки в любое время.

Связанные интерфейсы

Инструкция по интеграции API генерации видео Maestro: автоматически создаёт готовое видео с субтитрами по подсказке на естественном языке, после отправки возвращает task_id, затем используйте этот интерфейс для опроса результата.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Описание интеграции API запроса задач Maestro

Процесс получения доступа

Запрос одной задачи

Настройка заголовков и тела запроса

Пример кода

Пример ответа

Запрос списка истории

Пример кода

Пример ответа

Рекомендации по опросу

Обработка ошибок

Пример ответа с ошибкой

Заключение

Связанные интерфейсы

​Процесс получения доступа

​Запрос одной задачи

​Настройка заголовков и тела запроса

​Пример кода

​Пример ответа

​Запрос списка истории

​Пример кода

​Пример ответа

​Рекомендации по опросу

​Обработка ошибок

​Пример ответа с ошибкой

​Заключение

​Связанные интерфейсы

Процесс получения доступа

Запрос одной задачи

Настройка заголовков и тела запроса

Пример кода

Пример ответа

Запрос списка истории

Пример кода

Пример ответа

Рекомендации по опросу

Обработка ошибок

Пример ответа с ошибкой

Заключение

Связанные интерфейсы