MiniMax H3 Task Query API Integration Guide

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.

¶ Application Process

To use the MiniMax H3 Task Query API, first go to the qiyaov Console to obtain your API Token and keep it for later use.

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.

📘 Full documentation: MiniMax H3 Task Query API →

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:

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

¶ API Overview

Base URL: https://api.qiyaov.com
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

curl -X POST 'https://api.qiyaov.com/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:

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

¶ 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:

import os
import time

import requests

BASE_URL = "https://api.qiyaov.com"
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:

curl -X POST 'https://api.qiyaov.com/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
}

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:

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

curl -X POST 'https://api.qiyaov.com/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:

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

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