MiniMax H3 Task Query API Integration Guide

This document introduces the integration and usage of the MiniMax H3 Task Query API. This interface is used to query, batch list, or delete asynchronous tasks created by the MiniMax H3 Video Generation API.

¶ Application Process

To use the MiniMax H3 Task Query API, first obtain your API Token from the YuJun Console for future reference.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, after which you will be automatically returned to the current page.

One API Token can call all services on the platform, no need to apply separately for each service. The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete documentation: MiniMax H3 Task Query API →

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

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

¶ Interface 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 Task: action=delete, pass in id
Billing Description: Task queries are free and will not incur duplicate billing

After creating a video, you must save the task_id. 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`; default is `retrieve`
`id`	string	Conditionally Required	`retrieve`, `delete`	Single task ID
`ids`	string[]	No	`retrieve_batch`	Only return specified task IDs; omitted will list tasks by other conditions
`limit`	integer	No	`retrieve_batch`	Maximum number of tasks to return this time
`offset`	integer	No	`retrieve_batch`	Number of tasks to skip from the result list, used for pagination
`created_at_min`	number	No	`retrieve_batch`	Creation time lower limit, Unix timestamp, in seconds
`created_at_max`	number	No	`retrieve_batch`	Creation time upper limit, 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 a 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 task record based on the current status	`id`	`{ "id": "...", "deleted": true }`

¶ Query a Single Task

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 a response from a real successful task:

{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786184658,
    "updated_at": 1786184758,
    "content": {
      "url": "https://platform2.cdn.acedata.cloud/minimax/f5977217-ed2c-40da-adbe-93d08235618f.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

¶ Task Status

`status`	Meaning	Client Handling
`queued`	Entered the queue, waiting for execution	Continue polling
`running`	Currently generating	Continue polling
`succeeded`	Generation succeeded	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	Model used for the task, currently `MiniMax-H3`
`status`	string	Current task status
`error.code`	string	Failure error code, returned only on failure
`error.message`	string	Reason for failure, returned only on failure
`created_at`	integer	Creation time, Unix timestamp, in seconds
`updated_at`	integer	Last status update time, Unix timestamp, in seconds
`content.url`	string	Video address after success
`resolution`	string	Output resolution, `768P` or `2K`
`duration`	integer	Output video duration, in seconds
`usage.total_seconds`	integer	Total cost amount, equal to the sum of input video seconds and output seconds
`usage.input_seconds`	integer	Cost amount generated by the input reference video
`usage.output_seconds`	integer	Cost amount generated by the output video
`usage.input_image_count`	integer	Number of input images in billing statistics
`ratio`	string	Actual output aspect ratio; when using `adaptive`, this result is authoritative
`task_type`	string	Video generation task is `generation`
`modality`	string	Video task is `video`

¶ Python Polling Complete Example

The following code reads the Token from environment variables and queries every 10 seconds after creating a task:

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": "In the early morning by the sea, a white sailboat glides across the calm surface of the water, the camera slowly pans.",
            }
        ],
        "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"])

The production environment should set a total timeout for polling and use exponential backoff for 429 and temporary 5xx. Network timeouts do not equal generation failures, and the same task_id can be used to continue querying.

¶ Batch Query

Specify multiple task IDs:

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:

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

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

{
  "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 is the last 7 days. task_id beyond this window may return invalid tasks; the business system should save the ID when creating the task and promptly persist the result URL upon success.

¶ Cancel or Delete Task

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 current status of the task:

Current Status	Action
`queued`	Cancel tasks that have not started yet
`succeeded`	Delete task record
`failed`	Delete task record
`running`	Deletion or cancellation not allowed, return error
`cancelled`	Repeated operation not allowed, return error

Example of successful deletion:

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

Deleting a task record does not reverse any completed billing, nor can it guarantee that saved video copies are deleted simultaneously.

¶ Failure Response and Troubleshooting

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

If the interface itself returns 400, check the action and condition parameters; 401 indicates an invalid Token, 429 indicates queries are too frequent, and 500 indicates the service is temporarily unavailable. Tasks that fail to generate are not billed; successful tasks are recorded based on the final usage.