MiniMax H3 Normal

텍스트, 프레임 한두 장, 또는 참조로 쓰는 최대 4장의 이미지와 1개의 영상으로 480p, 768p 또는 1080p의 소리 있는 5–15초 영상을 minimax-h3 요금보다 약 3분의 1 저렴하게 생성합니다.

• 비동기 방식: 생성 호출은 작업 ID를 반환하고, 작업이 성공하면 영상이 제공됩니다. Normal은 Fast보다 렌더링이 느립니다.
• 768p에서 minimax-h3 요금보다 약 3분의 1 저렴하며, 768p 외에 480p와 1080p도 제공합니다.
• 모든 영상에는 생성 오디오가 포함됩니다. 이를 끄는 필드도, 오디오 입력도 없습니다.
• 네 가지 입력 방식: 텍스트만, 첫 프레임, 첫 프레임과 마지막 프레임, 또는 최대 4장의 참조 이미지와 1개의 참조 영상. seed는 선택입니다.
• 영상 초 단위로 과금됩니다. 실패한 작업은 비용이 들지 않습니다.

API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델 ID

MiniMax H3 모델 다섯 개가 이 엔드포인트를 함께 쓰지만 입력은 서로 다릅니다. 아래 값은 게이트웨이 계약에서 그대로 가져왔습니다.

엔드포인트와 인증

POST https://api.beatapi.io/v1/videos/tasks

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청 처리 방식

입력 모드

요청 파라미터

게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.

• images는 참조 입력과 함께 쓸 수 없습니다
• Normal은 렌더링이 더 느리며 768p에서 minimax-h3 요금보다 약 3분의 1 저렴합니다. 480p, 768p, 1080p만 사용할 수 있습니다
• 참조 모드는 이미지 최대 4장과 영상 1개를 받습니다. 참조 오디오는 지원하지 않으며, 생성된 영상에는 네이티브 오디오가 포함됩니다

입력 미디어 제한

게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.

• 이 제한은 images와 reference_images(이미지), reference_videos(영상)에 적용됩니다. 이 모델은 참조 오디오를 받지 않으므로 오디오 행은 적용되지 않습니다.
• 입력은 images, reference_images, reference_videos 순서로 하나씩 검사합니다. 입력 하나에 대해서는 길이, 변 길이, 화면비, 프레임 속도 순이며, 모든 참조 영상의 총 길이는 마지막에 검사합니다. 메시지는 필드 오류와 마찬가지로 0부터 세어 목록과 위치로 입력을 명시합니다: images[0] is 200x200 pixels; this model takes images 256 to 5760 pixels on each side.
• 길이는 0.1초의 허용 오차로 측정합니다. 크기는 호스트가 알려 줄 때만 검사합니다.
• 링크는 호스트가 HTTP 4xx 오류로 응답하거나 빈 파일을 반환할 때만 작업 생성 시 거부됩니다(예: reference_videos[0] could not be downloaded: the URL returned HTTP 404.). 입력의 다른 문제는 제출 후에 드러나 작업이 실패하며 환불됩니다.
• 로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

소리와 이 모델이 받지 않는 필드

모든 영상에는 생성 오디오가 포함됩니다. generate_audio 필드와 오디오 입력은 없습니다.

모델이 받지 않는 필드를 보내면 무시되지 않고 비용이 청구되기 전에 거부됩니다:

• reference_audios, generate_audio, watermark, quality, sound 및 다른 영상 모델의 기타 필드 → field "reference_audios" is not supported by model minimax-h3-normal(보낸 필드 명시).
• 그 밖의 알 수 없는 필드 → unknown field: <name>.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-normal",
  "prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys, distant bells",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768p"
}'

텍스트로 영상 생성

768p 가로 5초 소리 있는 클립입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-normal",
  "prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys, distant bells",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768p"
}'

첫 프레임

이미지에서 영상이 시작되며, aspect_ratio는 이미지의 세로 모양에 맞춥니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-normal",
  "prompt": "The performer turns toward the camera as neon light sweeps across the stage",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "768p"
}'

첫 프레임과 마지막 프레임

1080p로 첫 번째 이미지에서 두 번째 이미지로 이어집니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-normal",
  "prompt": "The camera moves smoothly from the bottle on the table to the singer on a neon stage in one continuous shot",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 6,
  "aspect_ratio": "9:16",
  "resolution": "1080p"
}'

시드를 지정한 이미지 참조

참조 이미지 두 장, 고정 시드, 가장 저렴한 해상도.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-normal",
  "prompt": "The singer from the first reference image walks past the bottle from the second reference image, neon reflections, slow tracking shot",
  "reference_images": [
    "https://cdn.beatapi.io/samples/neon-singer.png",
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "480p",
  "seed": 42
}'

이미지와 영상 참조

영상 링크를 직접 준비한 최대 15초, 초당 23.976~60프레임의 MP4 또는 MOV로 바꾸세요.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-normal",
  "prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the reference video",
  "reference_images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "duration": 8,
  "resolution": "768p"
}'

응답

작업 생성(201)

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3-normal",
    "capability_version": 1,
    "media_type": "video",
    "model": "minimax-h3-normal",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.1,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.1,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

완료된 작업

GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3-normal",
    "capability_version": 1,
    "media_type": "video",
    "model": "minimax-h3-normal",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.1,
      "credits_settled": 0.1,
      "credits_refunded": 0,
      "credits_charged": 0.1,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

출력 필드

실패한 작업

실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "minimax-h3-normal",
    "capability_version": 1,
    "media_type": "video",
    "model": "minimax-h3-normal",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.1,
      "credits_settled": 0,
      "credits_refunded": 0.1,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

전체 예시

작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "minimax-h3-normal",
  "prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys, distant bells",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "768p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

과금

• 영상 초 단위로 과금되며, 요청한 duration에 선택한 해상도의 요금을 곱합니다. 아래 목록 가격은 8초 기준이며, 초당 480p 약 $0.0175, 768p$0.02, 1080p $0.025입니다.
• 768p에서 minimax-h3 요금보다 3분의 1 저렴합니다(768P 초당 $0.03, `minimax-h3-fast`는$0.06).
• 화면비, 참조 수, seed, 참조 영상 길이는 가격에 영향을 주지 않습니다.
• 가격은 작업 생성 시 보류되며, 작업의 usage.billable_duration_seconds에 과금된 초 수가 표시됩니다.
• 실패한 작업은 제출 후 콘텐츠 검수에서 거부된 경우를 포함해 전액 환불됩니다.

현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.

자주 발생하는 오류

HTTP 오류 요약

작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}