> ## 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 API guide - 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)

まだログインまたは登録していない場合は、自動的にログインページへ移動し、登録とログインを促されます。完了すると自動的に現在のページへ戻ります。

**1 つの 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 タイムスタンプ |

3 種類のアクションの用途は次のとおりです。

| `action` | 用途 | 必要なパラメータ | レスポンス構造 |
| - | - | - | - |
| `retrieve` | 1 つのタスクの状態と結果を照会する | `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 | 成功後の動画 URL |
| `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 秒ごとに 1 回クエリします：

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