TL;DR

• Text-to-Video, Image-to-Video, Reference-to-Video는 POST로 prediction을 생성하고 결과 URL을 polling하는 과정까지 공통적입니다.
• 우선 Text-to-Video 또는 Image-to-Video를 5초·480p로 실행해 보고, 참조 소재가 필요한 경우에만 Reference-to-Video로 넘어갑니다.
• 480p 5초 기준 Text/Image는 $0.20, Reference는 출력만으로 $0.25입니다. 참조 소재에는 별도의 요금이 부과됩니다.

전제: 이 API 경로에서 확인할 사항

MiniMax H3에는 공식 minimax/h3 API와는 별개로, WaveSpeed가 호스트하는 Open Weights 버전의 endpoint가 있습니다.

WaveSpeed의 설명에 따르면, 동일한 모델 패밀리라도 호스팅, 해상도, 초당 과금 방식은 독립적입니다.

이 글에서 다루는 것은 그 우열이 아닙니다.

3가지 입력 방식을 동일한 인증, 동일한 prediction 모니터링, 동일한 실패 처리 방식으로 호출할 수 있도록 만드는 것입니다.

요금과 중앙값(median) 시간은 2026-08-06에 각 모델 페이지에서 확인한 게시 값입니다.

큐의 혼잡도나 설정에 따라 달라질 수 있으므로, 실행 전에는 가격 견적 API나 화면의 견적을 확인하십시오. 아래 코드는 공식 스키마를 바탕으로 한 구현 예시이며, 필자의 실측 결과가 아닙니다.

전제 환경

• Python 3.11 이상
• WAVESPEED_API_KEY를 환경 변수로 설정 완료 - 입력 이미지·동영상·음성은 API에서 취득할 수 있는 URL이어야 함

export WAVESPEED_API_KEY="your-api-key"

공통 API 골격

3가지 endpoint의 차이는 payload뿐입니다. 인증, POST, prediction ID 취득, 2초부터 시작하는 polling, 종료 상태 처리는 공통화할 수 있습니다.

아래 스크립트는 --mode text, --mode image, --mode reference를 전환하며 사용합니다. --price-only를 붙이면 생성하지 않고 견적을 문의합니다.

from __future__ import annotations
import argparse
import json
...

Text-to-Video를 5초·480p로 견적 내는 예시입니다. --price-only를 먼저 실행한 후, 동일한 인자로 본 실행을 수행합니다.

python generate_minimax_h3.py \
--mode text \
--resolution 480p \
...

1. Text-to-Video: 우선 지시사항만 검증하기

Text-to-Video의 최소 입력과 해상도·길이 조건은 prompt, aspect_ratio, resolution, duration, seed입니다. 출력은 480p와 768p이며, 길이는 5~15초입니다.

모델 페이지가 제안하는 prompt 구성 방식은 다음 5개 계층입니다.

• Style: 색상, 질감, 시대, 분위기
• Timeline: [0s-2s]와 같은 시간대별 사건
• Camera: 클로즈업, 팬(pan), 고정, 컷 유무
• Audio: 목소리, 환경음, 삽입 타이밍
• On-screen text: 필요한 표시 문구. 필요 없다면 none이라고 작성

5초·480p는 $0.20이며, 게시된 중앙값 end-to-end 시간은 약 270초입니다. 처음부터 15초·768p로 가는 것보다, 5초로 prompt 구조를 수정하는 것이 무엇을 변경했는지 추적하기 쉽습니다.

실패가 많은 경우는 duration과 prompt의 timeline이 모순되는 케이스입니다. 5초로 지정했다면 [0s-4s]까지만 작성하는 등 정합성을 먼저 맞추어야 합니다.

2. Image-to-Video: 첫 장면을 고정하고 움직임만 바꾸기

첫 프레임을 고정하고 움직임만 바꾸는 단계에서는 image와 last_image를 받는 Image-to-Video 입력으로 전환합니다. 필요한 경우에만 last_image를 사용할 수 있습니다. 코드에서는 --image를 필수 사항으로 설정했습니다.

generate_minimax_h3.py \
--mode image \
--image 'https://example.com/first-frame.png' \
...

요금은 Text-to-Video와 동일하게 480p는 $0.04/초, 768p는 $0.08/초입니다. 생성 중인 중앙값 시간(Median time)은 약 75초로, Text-to-Video보다 짧게 표시됩니다. 다만, 이는 실측 보증값이 아니며 큐(Queue) 상태에 따라 달라질 수 있습니다.

여기서의 실패 원인은 API로부터 image를 가져올 수 없는 경우입니다. 공식 에러 코드로는 1402 Media Access Failed에 해당합니다. 로컬 경로가 아닌, 만료되지 않은 공개 URL이나 서비스가 읽을 수 있는 서명된 URL(Signed URL)을 전달해야 합니다.

3. Reference-to-Video: 참조는 태그로 지정한다

참조 소재의 역할을 나누어 전달하는 단계에서는 이미지, 영상, 오디오의 참조 프레임을 갖는 Reference-to-Video 조건을 사용합니다. reference_images를 최대 9개, reference_videos를 최대 3개, reference_audios를 최대 3개까지 전달할 수 있습니다. 단, 참조 영상은 480p 출력에서만 사용할 수 있으며, 참조 영상의 합계는 15초의 예산 내에 들어와야 합니다.

prompt에서는 이미지를 <Picture 1>, 영상을 <Video 1>, 오디오를 <Audio 1>과 같이 대괄호를 붙여 지칭합니다. Picture 1만으로는 참조 태그로 취급되지 않습니다.

generate_minimax_h3.py \
--mode reference \
--resolution 480p \
...

Reference-to-Video는 출력 480p가 $0.05/초, 768p가 $0.10/초입니다. 이미지와 오디오는 각각 $0.02이며, 참조 영상은 480p 기준 $0.05/초가 가산됩니다. 예를 들어 5초·480p에 이미지 2장을 첨부하면, 5 × $0.05 + 2 × $0.02 = $0.29가 됩니다.

이미지, 영상, 오디오를 모두 넣는 것이 정답은 아닙니다. 누구의 외형을 유지할 것인지, 어떤 장면을 배경으로 할 것인지, 어떤 소리를 사용할 것인지를 태그로 구분할 수 없다면, 참조를 줄이는 것이 실패 원인을 파악하기에 더 좋습니다.

입력 방식별 비교

가격과 중앙값 시간은 변경될 수 있는 값입니다. 특히 Reference-to-Video는 출력 시간뿐만 아니라 참조 이미지, 오디오, 영상에도 과금이 추가되므로, 고정된 '영상 1개당 얼마'로 취급하지 않는 것이 안전합니다.

비용은 「5초·480p」를 기준으로 설계한다

WaveSpeed의 비용 절감 가이드는 영상의 경우 먼저 480p로 prompt를 확인하고, 납득한 후에 고해상도로 진행하는 흐름을 안내하고 있습니다. MiniMax H3에서는 5초가 기본값이므로, 초기 비교 단위로 다루기에도 용이합니다.

• Text/Image: 5초·480p는 $0.20
• Text/Image: 15초·768p는 $1.20
• Reference: 5초·480p는 출력만으로 $0.25. 여기에 참조 소재 과금이 추가됨

최종 결과물만 768p로 만드는 운영 방식은 합리적입니다. 다만, 변경 사항은 해상도에만 한정해야 합니다. prompt, duration, seed까지 한꺼번에 바꾸면 비용이 증가한 이유와 출력이 바뀐 이유를 구분할 수 없기 때문입니다.

seed를 고정하고, 한 가지 변수만 변경한다

seed=-1은 랜덤입니다. 구도나 카메라 지시 사항만 비교하고 싶을 때는 동일한 seed, 동일한 해상도, 동일한 duration으로 설정하고, 변경할 항목을 하나로 좁혀야 합니다.

이는 「동일한 seed라면 항상 동일한 영상이 된다」는 보장이 아닙니다. 여기서의 목적은 최소한 요청(request) 측의 조건을 통일하여, 비교를 위한 메모를 남길 수 있도록 하는 것입니다.

seed: 42
변경한 항목: Camera 뿐
고정한 항목: prompt의 Style / Timeline / Audio, 480p, 5초
...

failed / cancelled / timeout 이 발생했을 때

코드는 completed 이외의 종료 상태에서 멈춥니다. 따라서 동일한 payload를 무조건적으로 다시 던지기 전에, 상태와 에러 코드(error code)를 나누어 살펴봐야 합니다.

cancelled와 timeout은 출력 품질의 평가가 아니라 태스크(task)의 상태입니다. 출력이 없는 상태로 다음 공정으로 넘어가지 않도록, 스크립트에서 예외(exception) 처리를 해두는 것이 안전합니다.

아직 결론을 내리지 말 것

상업적 이용 가능 여부는 WaveSpeed만으로 일률적으로 결정되지 않습니다. 공식 Commercial Use Policy에서도 모델별 README와 제공처의 라이선스를 확인하도록 안내하고 있습니다.

의뢰 소재를 투입할 수 있는지, 출력을 납품물로 사용할 수 있는지, 생성물을 어디에 저장할지는 API가 반환하는지 여부와는 별개의 판단입니다. 이 부분은 이용 약관과 의뢰 조건을 확인한 후에 결정해야 합니다.

참고

Discussion