MiniMax H3 작업 조회 API 연동 가이드

본 문서는 MiniMax H3 작업 조회 API의 연동 및 사용 방법을 소개합니다. 이 인터페이스는 MiniMax H3 비디오 생성 API로 생성된 비동기 작업을 조회, 일괄 나열 또는 삭제하는 데 사용됩니다.

신청 절차

MiniMax H3 작업 조회 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비용으로 보관하세요.

아직 로그인 또는 등록하지 않은 경우, 등록 및 로그인을 안내하는 로그인 페이지로 자동 이동하며, 완료 후 현재 페이지로 자동 복귀합니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족한 경우 콘솔에서 공용 잔액을 충전할 수 있습니다.

📘 전체 문서: MiniMax H3 작업 조회 API →

작업을 조회할 때는 해당 작업을 생성한 것과 동일한 Token을 사용해야 합니다. Token은 환경 변수로 저장하고 소스 코드에 작성하거나 버전 관리 저장소에 커밋하지 않는 것을 권장합니다:

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

단일 작업 조회

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"
  }'

다음은 실제 성공 작업의 응답입니다:

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

이번 작업의 실제 비디오 결과 열기

작업 상태

`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초마다 한 번씩 조회합니다:

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를 지정합니다:

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
  }'

시간 범위별로 페이지네이션하여 작업을 나열합니다:

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

일괄 응답의 items는 단일 작업 조회와 동일한 task 필드를 사용하며, total은 필터 조건과 일치하는 작업의 총수입니다:

{
  "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을 적시에 영구 저장해야 합니다.

작업 취소 또는 삭제

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`	반복 작업 불가, 오류 반환

삭제 성공 예시:

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

작업 기록을 삭제해도 이미 완료된 청구는 취소되지 않으며, 저장된 비디오 사본도 함께 삭제된다고 보장할 수 없습니다.

실패 응답 및 문제 해결

실패한 작업도 HTTP 200으로 task 객체를 반환하며, 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"
  }
}

인터페이스 자체가 400을 반환하면 action 및 조건 매개변수를 확인해야 하며, 401은 Token이 유효하지 않음을 나타내고, 429는 조회가 너무 빈번함을 나타내며, 500은 서비스를 일시적으로 사용할 수 없음을 나타냅니다. 생성에 실패한 작업에는 과금되지 않으며, 성공한 작업은 최종 usage에 따라 사용량이 기록됩니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

MiniMax H3 작업 조회 API 연동 가이드

신청 절차

인터페이스 개요

요청 파라미터

단일 작업 조회

작업 상태

task 응답 필드

Python 폴링 전체 예제

일괄 조회

작업 취소 또는 삭제

실패 응답 및 문제 해결

​신청 절차

​인터페이스 개요

​요청 파라미터

​단일 작업 조회

​작업 상태

​task 응답 필드

​Python 폴링 전체 예제

​일괄 조회

​작업 취소 또는 삭제

​실패 응답 및 문제 해결

신청 절차

인터페이스 개요

요청 파라미터

단일 작업 조회

작업 상태

task 응답 필드

Python 폴링 전체 예제

일괄 조회

작업 취소 또는 삭제

실패 응답 및 문제 해결