> ## 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, сначала получите ваш API Token в [консоли Ace Data Cloud](https://platform.acedata.cloud/console/applications) и сохраните его для дальнейшего использования.

![](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`
* **Способ аутентификации**：в HTTP Header передаётся `authorization: Bearer {token}`
* **Заголовки запроса**：
  * `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.