> ## 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 任務查詢 API 串接指南

> Minimax 整合指南 - Ace Data Cloud

本文介紹 MiniMax H3 任務查詢 API 的串接與使用。該介面用於查詢、批量列出或刪除 [MiniMax H3 影片生成 API](https://platform.acedata.cloud/documents/minimax-videos-integration) 建立的非同步任務。

## 申請流程

要使用 MiniMax H3 任務查詢 API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。

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

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。

**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。

> 📘 完整文件：[MiniMax H3 任務查詢 API →](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 時間戳記，單位為秒 |
| `created_at_max` | number | 否 | `retrieve_batch` | 建立時間上限，Unix 時間戳記，單位為秒 |

三種動作的用途如下：

| `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 時間戳記，單位為秒 |
| `updated_at` | integer | 最近一次狀態更新時間，Unix 時間戳記，單位為秒 |
| `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
}
```

刪除任務記錄不會撤銷已經完成的計費，也不能保證已儲存的影片副本同時被刪除。

## 失敗回應與排查

失敗任務仍以 HTTP 200 回傳 task 物件，並在 `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.