> ## 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 запитів завдань MiniMax H3

> Minimax API guide - Ace Data Cloud

У цій статті описано інтеграцію та використання API запитів завдань MiniMax H3. Цей інтерфейс використовується для запиту, пакетного виведення списку або видалення асинхронних завдань, створених за допомогою [API генерації відео MiniMax H3](https://platform.acedata.cloud/documents/minimax-videos-integration).

## Процес подання заявки

Щоб використовувати API запитів завдань MiniMax H3, спочатку перейдіть до [консолі 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 запитів завдань MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

Під час запиту завдання слід використовувати той самий Token, яким було створено це завдання. Рекомендується зберігати Token як змінну середовища, не записувати його у вихідний код і не надсилати до репозиторію версій:

```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```

## Огляд інтерфейсу

* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/tasks`
* **Спосіб автентифікації**：передавайте `authorization: Bearer {token}` у HTTP Header
* **Заголовки запиту**：
  * `accept: application/json`
  * `content-type: application/json`
* **Запит одного завдання**：`action=retrieve`, передайте `id`
* **Пакетний запит завдань**：`action=retrieve_batch`, можна фільтрувати за ID завдань, часовим діапазоном і умовами пагінації
* **Видалення завдання**：`action=delete`, передайте `id`
* **Пояснення щодо тарифікації**：запит завдань безкоштовний, повторна тарифікація не виникає

Після створення відео необхідно зберегти `task_id`. Рекомендується виконувати запит приблизно раз на 10 секунд, доки завдання не перейде в термінальний стан.

## Параметри запиту

| Параметр | Тип | Обов’язковий | Застосовна дія | Опис |
| - | - | - | - | - |
| `action` | string | Ні | Усі | `retrieve`, `retrieve_batch` або `delete`; за замовчуванням `retrieve` |
| `id` | string | Умовно обов’язковий | `retrieve`, `delete` | ID одного завдання |
| `ids` | string\[] | Ні | `retrieve_batch` | Повертає лише вказані ID завдань; якщо пропущено, завдання виводяться за іншими умовами |
| `limit` | integer | Ні | `retrieve_batch` | Максимальна кількість завдань, що повертаються за цей раз |
| `offset` | integer | Ні | `retrieve_batch` | Кількість завдань, які потрібно пропустити у списку результатів, використовується для пагінації |
| `created_at_min` | number | Ні | `retrieve_batch` | Нижня межа часу створення, Unix timestamp, у секундах |
| `created_at_max` | number | Ні | `retrieve_batch` | Верхня межа часу створення, Unix timestamp, у секундах |

Призначення трьох дій наведено нижче:

| `action` | Призначення | Необхідні параметри | Структура відповіді |
| - | - | - | - |
| `retrieve` | Запит статусу та результату одного завдання | `id` | `{ "task": {...} }` |
| `retrieve_batch` | Пакетний запит за ID завдань, часом та умовами пагінації | Необов’язкові `ids`, часовий діапазон, `offset`, `limit` | `{ "items": [...], "total": number }` |
| `delete` | Скасування або видалення запису завдання відповідно до поточного статусу завдання | `id` | `{ "id": "...", "deleted": true }` |

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

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "f5977217-ed2c-40da-adbe-93d08235618f"
  }'
```

Нижче наведено відповідь одного реального успішного завдання:

```json theme={null}
{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786184658,
    "updated_at": 1786184758,
    "content": {
      "url": "https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4"
    },
    "resolution": "768P",
    "duration": 4,
    "usage": {
      "total_seconds": 4,
      "input_seconds": 0,
      "output_seconds": 4,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

[Відкрити реальний результат відео цього завдання](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## Статуси завдання

| `status` | Значення | Обробка клієнтом |
| - | - | - |
| `queued` | Додано до черги, очікує виконання | Продовжувати опитування |
| `running` | Виконується генерація | Продовжувати опитування |
| `succeeded` | Генерацію успішно завершено | Зчитати `task.content.url`, припинити опитування |
| `failed` | Помилка генерації | Зчитати `task.error`, припинити опитування |
| `cancelled` | Завдання скасовано | Припинити опитування |

`succeeded`, `failed` і `cancelled` — це всі термінальні стани. Не продовжуйте опитування після переходу до термінального стану.

## Поля відповіді task

| Поле | Тип | Опис |
| - | - | - |
| `id` | string | ID завдання |
| `model` | string | Модель, використана завданням, наразі `MiniMax-H3` |
| `status` | string | Поточний статус завдання |
| `error.code` | string | Код помилки збою, повертається лише у разі збою |
| `error.message` | string | Причина збою, повертається лише у разі збою |
| `created_at` | integer | Час створення, Unix timestamp, у секундах |
| `updated_at` | integer | Час останнього оновлення статусу, Unix timestamp, у секундах |
| `content.url` | string | Адреса відео після успішного завершення |
| `resolution` | string | Вихідна роздільна здатність, `768P` або `2K` |
| `duration` | integer | Тривалість вихідного відео, у секундах |
| `usage.total_seconds` | integer | Загальний обсяг тарифікації, дорівнює сумі секунд вхідного відео та вихідних секунд |
| `usage.input_seconds` | integer | Обсяг тарифікації, що виникає через вхідне референсне відео |
| `usage.output_seconds` | integer | Обсяг тарифікації, що виникає через вихідне відео |
| `usage.input_image_count` | integer | Кількість вхідних зображень у статистиці тарифікації |
| `ratio` | string | Фактичне співвідношення сторін виходу; у разі використання `adaptive` орієнтуйтеся на результат тут |
| `task_type` | string | Завдання генерації відео має значення `generation` |
| `modality` | string | Відеозавдання має значення `video` |

## Повний приклад опитування Python

Наведений нижче код зчитує Token зі змінної середовища, після створення завдання виконує запит кожні 10 секунд:

```python theme={null}
import os
import time

import requests

BASE_URL = "https://api.acedata.cloud"
HEADERS = {
    "Authorization": f"Bearer {os.environ['ACEDATACLOUD_API_KEY']}",
    "Content-Type": "application/json",
}

create_response = requests.post(
    f"{BASE_URL}/minimax/videos",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": "Морський берег на світанку, білий вітрильник пливе спокійною морською поверхнею, камера повільно рухається вбік",
            }
        ],
        "resolution": "768P",
        "duration": 4,
        "ratio": "16:9",
    },
    timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["task_id"]

while True:
    time.sleep(10)
    query_response = requests.post(
        f"{BASE_URL}/minimax/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()
    task = query_response.json()["task"]
    print(f"task={task_id} status={task['status']}")

    if task["status"] == "succeeded":
        print(f"video_url={task['content']['url']}")
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error") or task["status"])
```

У виробничому середовищі для опитування слід встановити загальний тайм-аут і використовувати експоненційне збільшення затримки для `429` та тимчасових `5xx`. Тайм-аут мережі не означає збій генерації, можна продовжувати запити, використовуючи той самий `task_id`.

## Пакетний запит

Вкажіть кілька ID завдань:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "ids": ["TASK_ID_1", "TASK_ID_2"],
    "offset": 0,
    "limit": 20
  }'
```

Виведіть завдання посторінково за часовим діапазоном:

```json theme={null}
{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}
```

`items` у пакетній відповіді використовує ті самі поля task, що й запит одного завдання, а `total` — це загальна кількість завдань, які відповідають умовам фільтрації:

```json theme={null}
{
  "items": [
    {
      "id": "TASK_ID_1",
      "model": "MiniMax-H3",
      "status": "running",
      "resolution": "2K",
      "duration": 5,
      "ratio": "adaptive",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}
```

Вікно запиту завдань охоплює останні 7 днів. `task_id`, що виходить за межі цього вікна, може повертати недійсне завдання; бізнес-система повинна зберігати ID під час створення завдання та своєчасно зберігати URL результату після успішного виконання.

## Скасування або видалення завдання

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "delete",
    "id": "YOUR_TASK_ID"
  }'
```

Дія залежить від поточного статусу завдання:

| Поточний статус | Поведінка |
| - | - |
| `queued` | Скасувати завдання, яке ще не розпочалося |
| `succeeded` | Видалити запис завдання |
| `failed` | Видалити запис завдання |
| `running` | Видалення або скасування не дозволено, повертається помилка |
| `cancelled` | Повторна операція не дозволена, повертається помилка |

Приклад успішного видалення:

```json theme={null}
{
  "id": "YOUR_TASK_ID",
  "deleted": true
}
```

Видалення запису завдання не скасовує вже завершене виставлення рахунків і не гарантує одночасного видалення збережених копій відео.

## Відповіді про помилки та діагностика

Завдання, що зазнало невдачі, все одно повертає об’єкт task через HTTP 200, а причина наводиться в `task.error`:

```json theme={null}
{
  "task": {
    "id": "YOUR_TASK_ID",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "task_type": "generation",
    "modality": "video"
  }
}
```

Коли сам інтерфейс повертає `400`, слід перевірити `action` та параметри умов, `401` означає, що Token недійсний, `429` означає, що запити виконуються надто часто, а `500` означає, що сервіс тимчасово недоступний. Завдання, генерація яких завершилася невдачею, не тарифікуються; для успішних завдань використання обліковується за остаточним записом `usage`.


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