> ## 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.

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

> Maestro AI Video Studio API guide - Ace Data Cloud

Основная функция API запроса задач Maestro — по ID задачи, возвращённому [API генерации видео Maestro](/ru/guides/maestro/maestro_videos) (`POST /maestro/videos`), запрашивать статус выполнения и итоговый результат этой задачи.

В этом документе будет подробно представлено описание интеграции API запроса задач Maestro. Поскольку генерация видео является асинхронной задачей, после отправки необходимо использовать этот интерфейс для опроса и получения прогресса и готового видео, **опрос бесплатный и не расходует кредиты.**

`POST https://api.acedata.cloud/maestro/tasks`

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

Чтобы использовать API запроса задач Maestro, сначала перейдите в [консоль 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).

> 📘 Полная документация: [API запроса задач Maestro →](https://platform.acedata.cloud/documents/maestro-tasks)

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

О том, как создавать задачи видео, см. документацию [API генерации видео Maestro](/ru/guides/maestro/maestro_videos). В качестве примера возьмём один возвращённый им 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 выглядит следующим образом:

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

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

```python theme={null}
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`):

```json theme={null}
{
  "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-код приведён ниже:

```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 '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

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

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

```json theme={null}
{
  "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`, отсортированный по времени создания в обратном порядке; формат каждого элемента совпадает с результатом возврата «Запроса одной задачи».

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

Поскольку создание видео занимает длительное время, `status` будет проходить через `pending → planning → producing → succeeded` (или `failed`). Рекомендуется выполнять опрос каждые 5–10 секунд, пока `status` не станет `succeeded` или `failed`. Для отображения индикатора выполнения в реальном времени можно использовать верхнеуровневый `progress.percent`. **Опрос этого интерфейса бесплатен и не расходует баллы.**

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

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

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

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

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

## Заключение

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

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

* [Инструкция по интеграции API генерации видео Maestro](/ru/guides/maestro/maestro_videos): автоматически создаёт готовое видео с субтитрами по подсказке на естественном языке, после отправки возвращает `task_id`, затем используйте этот интерфейс для опроса результата.


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