> ## 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.

# MiniMax H3 Task Query API Integration Guide

> Minimax integration guide - Ace Data Cloud

This document introduces the integration and usage of the MiniMax H3 Task Query API. This API is used to query, batch list, or delete asynchronous tasks created by the [MiniMax H3 Video Generation API](https://platform.acedata.cloud/documents/minimax-videos-integration).

## Application Process

To use the MiniMax H3 Task Query API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token and keep it for later use.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

If you have not logged in or registered yet, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page.

**One API Token can call all platform services, with no need to apply separately for each service.** Your first application will include free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin).

> 📘 Full documentation: [MiniMax H3 Task Query API →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

When querying a task, you should use the same Token that created the task. It is recommended to save the Token as an environment variable and not write it into source code or commit it to a version repository:

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

## API Overview

* **Base URL**: `https://api.acedata.cloud`
* **Endpoint**: `POST /minimax/tasks`
* **Authentication Method**: Include `authorization: Bearer {token}` in the HTTP Header
* **Request Headers**:
  * `accept: application/json`
  * `content-type: application/json`
* **Query a Single Task**: `action=retrieve`, pass in `id`
* **Batch Query Tasks**: `action=retrieve_batch`, can filter by task ID, time range, and pagination conditions
* **Delete a Task**: `action=delete`, pass in `id`
* **Billing Notes**: Task queries are free and will not result in repeated charges

You must save the `task_id` after creating a video. It is recommended to query approximately every 10 seconds until the task enters a terminal state.

## Request Parameters

| Parameter | Type | Required | Applicable Actions | Description |
| - | - | - | - | - |
| `action` | string | No | All | `retrieve`, `retrieve_batch`, or `delete`; defaults to `retrieve` |
| `id` | string | Conditionally required | `retrieve`, `delete` | Single task ID |
| `ids` | string\[] | No | `retrieve_batch` | Returns only specified task IDs; when omitted, lists tasks according to other conditions |
| `limit` | integer | No | `retrieve_batch` | Maximum number of tasks returned in this request |
| `offset` | integer | No | `retrieve_batch` | Number of tasks to skip from the result list, used for pagination |
| `created_at_min` | number | No | `retrieve_batch` | Lower bound of creation time, Unix timestamp in seconds |
| `created_at_max` | number | No | `retrieve_batch` | Upper bound of creation time, Unix timestamp in seconds |

The purposes of the three actions are as follows:

| `action` | Purpose | Required Parameters | Response Structure |
| - | - | - | - |
| `retrieve` | Query the status and result of one task | `id` | `{ "task": {...} }` |
| `retrieve_batch` | Batch query by task ID, time, and pagination conditions | Optional `ids`, time range, `offset`, `limit` | `{ "items": [...], "total": number }` |
| `delete` | Cancel or delete a task record according to the current task status | `id` | `{ "id": "...", "deleted": true }` |

## Query a Single Task

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

Below is the response from a real successful task:

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

[Open the real video result of this task](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## Task Status

| `status` | Meaning | Client Handling |
| - | - | - |
| `queued` | Has entered the queue, waiting for execution | Continue polling |
| `running` | Being generated | Continue polling |
| `succeeded` | Generated successfully | Read `task.content.url`, stop polling |
| `failed` | Generation failed | Read `task.error`, stop polling |
| `cancelled` | Task has been cancelled | Stop polling |

`succeeded`, `failed`, and `cancelled` are all terminal states. Do not continue polling after entering a terminal state.

## task Response Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Task ID |
| `model` | string | The model used by the task, currently `MiniMax-H3` |
| `status` | string | Current task status |
| `error.code` | string | Failure error code, returned only on failure |
| `error.message` | string | Failure reason, returned only on failure |
| `created_at` | integer | Creation time, Unix timestamp in seconds |
| `updated_at` | integer | Most recent status update time, Unix timestamp in seconds |
| `content.url` | string | Video URL after success |
| `resolution` | string | Output resolution, `768P` or `2K` |
| `duration` | integer | Output video duration, in seconds |
| `usage.total_seconds` | integer | Total billable usage, equal to the sum of input video seconds and output seconds |
| `usage.input_seconds` | integer | Billable usage generated by reference video input |
| `usage.output_seconds` | integer | Billable usage generated by output video |
| `usage.input_image_count` | integer | Number of input images in billing statistics |
| `ratio` | string | Actual output aspect ratio; when using `adaptive`, refer to the result here |
| `task_type` | string | Video generation task is `generation` |
| `modality` | string | Video task is `video` |

## Complete Python Polling Example

The following code reads the Token from an environment variable, creates a task, and queries it every 10 seconds:

```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": "At the seaside in the early morning, a white sailboat sails across the calm sea, and the camera slowly pans horizontally",
            }
        ],
        "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"])
```

Production environments should set an overall timeout for polling and use exponential backoff for `429` and temporary `5xx` responses. A network timeout does not mean generation has failed; you can continue querying using the same `task_id`.

## Batch Querying

Specify multiple task IDs:

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

List tasks by time range with pagination:

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

The `items` in the batch response use the same task fields as a single-task query, and `total` is the total number of tasks matching the filter criteria:

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

The task query window covers the most recent 7 days. A `task_id` beyond this window may return an invalid task; business systems should save the ID when creating a task and promptly persist the result URL after success.

## Cancel or Delete a Task

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

The action depends on the task's current status:

| Current Status | Behavior |
| - | - |
| `queued` | Cancel a task that has not started yet |
| `succeeded` | Delete the task record |
| `failed` | Delete the task record |
| `running` | Deletion or cancellation is not allowed; an error is returned |
| `cancelled` | Repeated operations are not allowed; an error is returned |

Example of a successful deletion:

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

Deleting a task record does not reverse charges that have already been incurred, nor does it guarantee that saved video copies will be deleted at the same time.

## Failure Responses and Troubleshooting

Failed tasks still return a task object with HTTP 200, and the reason is provided in `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"
  }
}
```

When the API itself returns `400`, check the `action` and condition parameters. `401` indicates an invalid Token, `429` indicates that queries are too frequent, and `500` indicates that the service is temporarily unavailable. Failed generation tasks are not billed; successful tasks are charged based on the final `usage` record.


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