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

아직 로그인 또는 등록하지 않은 경우, 등록 및 로그인을 안내하는 로그인 페이지로 자동 이동하며, 완료 후 현재 페이지로 자동 복귀합니다.

**하나의 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.