Інструкція з інтеграції 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: масив подій прогресу, що додаються за етапами (журнал лише з додаванням), може використовуватися для відображення детального прогресу в реальному часі.
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, а потім використовуйте цей інтерфейс для опитування результату.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Coding

Інші посібники

Інструкція з інтеграції API запиту завдань Maestro

Процес отримання

Запит одного завдання

Налаштування заголовків і тіла запиту

Приклад коду

Приклад відповіді

Запит історичного списку

Приклад коду

Приклад відповіді

Рекомендації щодо опитування

Обробка помилок

Приклад відповіді з помилкою

Висновок

Пов’язані інтерфейси

​Процес отримання

​Запит одного завдання

​Налаштування заголовків і тіла запиту

​Приклад коду

​Приклад відповіді

​Запит історичного списку

​Приклад коду

​Приклад відповіді

​Рекомендації щодо опитування

​Обробка помилок

​Приклад відповіді з помилкою

​Висновок

​Пов’язані інтерфейси

Процес отримання

Запит одного завдання

Налаштування заголовків і тіла запиту

Приклад коду

Приклад відповіді

Запит історичного списку

Приклад коду

Приклад відповіді

Рекомендації щодо опитування

Обробка помилок

Приклад відповіді з помилкою

Висновок

Пов’язані інтерфейси