Посібник з інтеграції API запитів завдань MiniMax H3

У цій статті описано інтеграцію та використання API запитів завдань MiniMax H3. Цей інтерфейс використовується для запиту, пакетного виведення списку або видалення асинхронних завдань, створених за допомогою API генерації відео MiniMax H3.

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

Щоб використовувати API запитів завдань MiniMax H3, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати свій API Token, і збережіть його для подальшого використання.

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

📘 Повна документація: API запитів завдань MiniMax H3 →

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

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 }`

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

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"
  }'

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

{
  "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"
  }
}

Відкрити реальний результат відео цього завдання

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

`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 секунд:

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 завдань:

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
  }'

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

{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}

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

{
  "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 результату після успішного виконання.

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

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`	Повторна операція не дозволена, повертається помилка

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

{
  "id": "YOUR_TASK_ID",
  "deleted": true
}

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

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

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

{
  "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.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Coding

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

Посібник з інтеграції API запитів завдань MiniMax H3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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