MiniMax H3 Python API: 설정 가이드 및 비동기 워크플로

MiniMax H3는 자연어 프롬프트와 지원되는 참조 자료를 받아들이는 멀티모달 AI 비디오 생성 모델입니다. Python API는 비디오 작업을 제출하고, 렌더링 진행 상황을 모니터링하며, 생성이 완료될 때까지 요청을 계속 열어 두지 않고도 완성된 파일을 조회해야 하는 애플리케이션을 위해 설계되었습니다.

표준 워크플로는 비동기 방식입니다. 애플리케이션이 비디오 생성 요청을 보내고 task_id를 받은 다음, 일정 간격으로 작업 상태를 확인하고, 작업이 Success에 도달하면 출력을 조회합니다. 이 구조는 웹 애플리케이션, 내부 도구, 콘텐츠 파이프라인, 배치 생성 시스템에 특히 잘 맞습니다.

공식 MiniMax H3 워크플로는 길이와 해상도를 설정할 수 있는 단편 비디오 생성을 지원합니다. 선택한 엔드포인트와 계정 구성에 따라 사용 가능한 제어 항목에는 텍스트 프롬프트, 이미지 참조, 비디오 참조, 오디오 지시, 종횡비, 출력 해상도 등이 포함될 수 있습니다.

통합을 작성하기 전에 Python 환경을 준비하고, HTTP 클라이언트를 설치한 뒤, MiniMax API 키를 애플리케이션 코드 밖에 저장하세요. 이렇게 하면 저장소, 로그, 스크린샷, 클라이언트 측 번들에서 키가 실수로 노출될 가능성이 줄어듭니다.

아래 예시는 Python과 requests 패키지를 사용합니다. 애플리케이션이 사용하는 환경에 다음 명령으로 설치하세요:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests

스크립트를 실행하기 전에 API 키를 환경 변수로 설정하세요:

export MINIMAX_API_KEY="YOUR_API_KEY"

Windows PowerShell에서는 다음을 사용하세요:

$env:MINIMAX_API_KEY="YOUR_API_KEY"

기본적인 MiniMax H3 Python API 통합에는 다음 4단계 프로세스를 따르세요. 핵심 설계 원칙은 작업 제출과 작업 모니터링을 분리하는 것입니다. 운영 서비스는 같은 생성을 다시 제출하지 않고도 폴링을 재시작할 수 있어야 합니다.

간단한 Python 구현 예시는 다음과 같습니다:

import os
import time
import requests

API_KEY = os.environ["MINIMAX_API_KEY"]
BASE_URL = "https://api.minimax.io/v1"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "MiniMax-H3",
    "prompt": (
        "A premium perfume bottle rotating on black glass, "
        "dramatic studio lighting, synchronized ambient sound."
    ),
    "duration": 6,
    "resolution": "768P",
}

create_response = requests.post(
    f"{BASE_URL}/video_generation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
create_response.raise_for_status()

task_id = create_response.json()["task_id"]
print("Created task:", task_id)

while True:
    query_response = requests.get(
        f"{BASE_URL}/query/video_generation",
        headers=HEADERS,
        params={"task_id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()

    task = query_response.json()
    status = task.get("status")
    print("Current status:", status)

    if status == "Success":
        file_id = task["file_id"]
        print("Completed file:", file_id)
        break

    if status == "Fail":
        message = task.get("error_message", "Video generation failed")
        raise RuntimeError(message)

    time.sleep(10)

완료된 작업의 경우 반환된 ID를 사용해 파일 정보를 조회하세요:

file_id = "FILE_ID_FROM_SUCCESS_RESPONSE"

file_response = requests.get(
    f"{BASE_URL}/files/retrieve",
    headers=HEADERS,
    params={"file_id": file_id},
    timeout=30,
)
file_response.raise_for_status()

file_data = file_response.json()
download_url = file_data.get("file", {}).get("download_url")
if not download_url:
    download_url = file_data.get("download_url")

print("Download URL:", download_url)

정확한 응답 형식은 엔드포인트 버전에 따라 다를 수 있습니다. 통합 과정에서는 JSON 응답을 확인하고 현재 MiniMax 비디오 생성 API 문서를 따르세요.

간단한 스크립트는 HTTP 요청이 실패하면 예외를 발생시킬 수 있지만, 운영 통합에는 더 많은 구조가 필요합니다. 클라이언트 오류와 일시적인 서비스 오류를 분리하고, 제한된 재시도를 사용하며, 원본 작업 식별자를 보존하세요.

일시적인 실패에는 즉시 재시도하는 대신 지수 백오프를 사용하세요:

import time

def wait_with_backoff(attempt, base_delay=5, max_delay=60):
    delay = min(base_delay * (2 ** attempt), max_delay)
    time.sleep(delay)

폴링에는 작업자가 무기한 활성 상태로 남지 않도록 최대 대기 시간을 적용하세요:

started_at = time.time()
max_wait_seconds = 30 * 60

while time.time() - started_at < max_wait_seconds:
    # 여기에서 작업을 조회합니다.
    # Success 또는 Fail에서 중단합니다.
    time.sleep(10)

raise TimeoutError("The MiniMax H3 task exceeded the polling limit.")

로컬 테스트를 넘어 운영 환경으로 갈 때는 다음 관행을 사용하세요:

• 프롬프트와 페이로드를 재현 가능하게 유지하세요. 프롬프트, 모델, 길이, 해상도, 참조 파일 식별자를 저장하세요.
• 백그라운드 워커를 사용하세요. 웹 요청은 작업을 생성해야 하며, 전체 비디오 렌더링을 기다리면 안 됩니다.
• 중복 제출을 방지하세요. 생성 엔드포인트를 호출하기 전에 내부 요청 ID를 부여하세요.
• 입력을 일찍 검증하세요. API 제출 전에 누락된 파일, 지원되지 않는 형식, 충돌하는 설정을 거부하세요.
• 출력 URL을 보호하세요. 반환된 다운로드 링크를 애플리케이션 데이터로 취급하고 중요한 파일은 제어된 저장소에 복사하세요.
• 사용량을 모니터링하세요. 성공한 작업, 실패한 작업, 재시도 횟수, 총 생성 초를 추적하세요.

가장 안전한 시작점은 짧은 H3 작업 하나를 생성하고, 타임아웃을 두고 폴링하며, 결과를 조회하고, 디버깅에 필요한 모든 응답을 기록하는 작은 백엔드 스크립트입니다. 그 경로가 작동하면 큐, 지속 저장소, 재시도 정책, 애플리케이션 수준 요청 추적을 추가하세요.