> ## 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](/uk/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](/uk/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`: масив подій прогресу, що додаються за етапами (журнал лише з додаванням), може використовуватися для відображення детального прогресу в реальному часі.
* `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](/uk/guides/maestro/maestro_videos): автоматично створює готове відео із субтитрами за одним текстовим запитом природною мовою, після надсилання повертає `task_id`, а потім використовуйте цей інтерфейс для опитування результату.


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