curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "MiniMax-H3-Max",
"prompt": "비 내리는 네온 거리에서 트렌치코트를 입은 탐정이 뒤돌아본다. 카메라가 천천히 다가가고 노면의 반사가 흔들린다.",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "MiniMax-H3-Max",
"prompt": "비 내리는 네온 거리에서 탐정이 뒤돌아보고 카메라가 천천히 다가간다.",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9",
},
)
print(response.json())
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
}
]
}
{
"error": {
"code": 400,
"message": "요청 매개변수가 올바르지 않습니다",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인하세요.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "계정 잔액이 부족합니다",
"type": "payment_required"
}
}
MiniMax-H3
MiniMax-H3-Max 동영상 생성
- MiniMax 동영상 생성 V2 고속 버전, 비동기 작업 제출
- 텍스트 기반 영상, 첫·마지막 프레임 제어 및 멀티모달 참조 생성 지원
- 480P / 768P / 1080P, 5~15초 길이의 오디오 포함 영상 지원
- 참조 이미지·영상·오디오 지원. 2K와 중간 프레임은 미지원
POST
/
v1
/
videos
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "MiniMax-H3-Max",
"prompt": "비 내리는 네온 거리에서 트렌치코트를 입은 탐정이 뒤돌아본다. 카메라가 천천히 다가가고 노면의 반사가 흔들린다.",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "MiniMax-H3-Max",
"prompt": "비 내리는 네온 거리에서 탐정이 뒤돌아보고 카메라가 천천히 다가간다.",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9",
},
)
print(response.json())
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
}
]
}
{
"error": {
"code": 400,
"message": "요청 매개변수가 올바르지 않습니다",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인하세요.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "계정 잔액이 부족합니다",
"type": "payment_required"
}
}
모델 선택:
MiniMax-H3-Max는 속도를 우선하는 텍스트 기반 영상, 첫·마지막 프레임 제어 및 멀티모달 참조 생성에 적합합니다. 480P, 768P, 1080P를 지원합니다. 2K나 중간 프레임이 필요하면 MiniMax-H3를 사용하세요.curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "MiniMax-H3-Max",
"prompt": "비 내리는 네온 거리에서 트렌치코트를 입은 탐정이 뒤돌아본다. 카메라가 천천히 다가가고 노면의 반사가 흔들린다.",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9"
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/videos/generations",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "MiniMax-H3-Max",
"prompt": "비 내리는 네온 거리에서 탐정이 뒤돌아보고 카메라가 천천히 다가간다.",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9",
},
)
print(response.json())
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
}
]
}
{
"error": {
"code": 400,
"message": "요청 매개변수가 올바르지 않습니다",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인하세요.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "계정 잔액이 부족합니다",
"type": "payment_required"
}
}
인증
모델 선택
| 기능 | MiniMax-H3 | MiniMax-H3-Max |
|---|---|---|
| 해상도 | 2K / 768P, 기본 2K | 480P / 768P / 1080P, 기본 768P |
| 길이 | 4~15초 | 5~15초 |
| 텍스트→동영상 | 지원 | 지원 |
| 첫 / 마지막 프레임 | 지원 | 지원 |
| 중간 프레임 | 지원 | 미지원 |
| 멀티모달 참조 | 이미지, 동영상, 오디오 | 이미지, 동영상, 오디오 |
| 입력 이미지 요금 | 처음 5장 무료 | 처음 2장은 무료, 초과 이미지는 장당 과금 |
| 참조 영상 요금 | 입력 길이에 따라 과금, 동일 해상도 출력 영상과 같은 단가 | 입력 길이에 따라 별도 단가로 과금 |
| AIGC 워터마크 | 지원 | 480P / 768P 지원, 1080P 미지원 |
MiniMax-H3-Max는 2K를 지원하지 않으며 결과를 Regeneration의 원본 작업으로 사용할 수 없습니다.생성 모드
요청 필드로 모드가 자동 결정됩니다.mode 필드를 보내지 마세요.
| 모드 | 조건 | 동작 |
|---|---|---|
| 텍스트→동영상(T2V) | prompt와 공통 필드만 전달 | 텍스트에서 생성 |
| 이미지→동영상(I2V) | first_frame_image / last_frame_image 또는 image_with_roles의 해당 역할 | 첫 프레임, 마지막 프레임 또는 둘 다 제어 |
| 멀티모달 참조(R2V) | image_urls / video_urls / audio_urls 또는 image_with_roles의 reference_image | 참조 이미지·영상·오디오로 생성, 1080P도 지원 |
첫·마지막 프레임 필드와 참조 자료를 함께 사용할 수 없습니다. 참조 오디오는 참조 이미지나 영상이 하나 이상 필요합니다. 잘못된 조합은 동기적으로 HTTP 400을 반환하며 작업 생성이나 과금은 이루어지지 않습니다.
요청 매개변수
string
필수
고정값:
MiniMax-H3-Max. 대소문자를 구분하지 않으며 minimax-h3-max도 허용됩니다.string
필수
비어 있지 않은 동영상 설명입니다. 모든 모드에서 필수이며 최대
7000자입니다.integer
기본값:"5"
동영상 길이(초).
5~15의 정수이며 기본값은 5입니다. 4초는 지원하지 않습니다.string
기본값:"768P"
출력 해상도:
480P, 768P(기본값), 1080P.1080P에서는 watermark와 별칭 aigc_watermark를 모두 생략하세요. 값이 false여도 전달하지 마세요.2K, 1440P, 2048P는 지원하지 않습니다. 잘못된 값은 HTTP 400을 반환하며 자동으로 낮은 해상도로 변경되지 않습니다.string
출력 화면비.
size와 ratio 별칭도 사용할 수 있습니다.T2V 값: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16.- T2V에서 생략하거나
adaptive사용:16:9로 대체 - I2V: 입력 이미지로 결정되며 이 필드는 무시
- 멀티모달 참조: 선택 사항, 기본값은
adaptive, 구체적인 비율도 지정 가능
string
동영상 첫 프레임으로 사용할 공개 이미지 URL.
string
마지막 프레임으로 사용할 공개 이미지 URL. 단독 또는
first_frame_image와 함께 사용할 수 있습니다.object[]
first_frame_image / last_frame_image / image_urls를 대체할 수 있는 역할 지정 이미지 배열.표시 image_with_roles 항목
표시 image_with_roles 항목
image_urls의 참조 이미지는 합계 최대 9장. 프레임 역할과 참조 이미지 역할을 함께 사용할 수 없습니다.string[]
참조 이미지의 공개 URL 배열.
image_with_roles의 참조 이미지와 합계 최대 9장. 모두 참조 이미지로 처리하며 첫·마지막 프레임으로 자동 인식하지 않습니다. 첫 프레임 제어에는 first_frame_image 또는 first_frame 역할을 사용하세요.string[]
참조 영상의 공개 URL 배열. 단일 영상은
video_url(string)로도 전달할 수 있습니다. 최대 3개, 각 2~15초, 참조 영상 총 길이는 15초 이하.제출 시 과금을 위해 참조 영상 길이를 읽습니다. 읽을 수 없으면 동기적으로 HTTP 400을 반환하며 작업 생성이나 과금은 이루어지지 않습니다.string[]
참조 오디오의 공개 URL 배열. 단일 오디오는
audio_url(string)로도 전달할 수 있습니다. 최대 3개, 각 2~15초, 참조 오디오 총 길이는 15초 이하. 참조 이미지나 영상이 하나 이상 필요하며 오디오만 사용할 수 없습니다.boolean
기본값:"false"
AIGC 워터마크 추가 여부. 별칭:
aigc_watermark.워터마크는 480P / 768P에서만 지원합니다. 1080P에서는 watermark와 별칭 aigc_watermark를 모두 생략하세요. 값이 false여도 전달하지 마세요.string
작업이 성공 또는 실패 상태로 종료되면 알림을 받습니다.
MiniMax의
callback_url 대신 webhook을 사용하세요. callback_url은 게이트웨이 내부용입니다.파라미터 제약
다음 잘못된 파라미터나 조합은 작업 생성 및 과금 전에 HTTP 400을 반환합니다.| 매개변수 / 값 | 이유 |
|---|---|
| 첫·마지막 프레임과 참조 자료 혼용 | I2V와 R2V는 상호 배타적 |
참조 이미지 9장 초과 또는 참조 영상·오디오 3개 초과 | 자료 개수 제한 초과 |
| 참조 오디오만 전달 | 참조 이미지 또는 영상 필요 |
resolution: "2K" | 480P, 768P, 1080P만 지원 |
duration: 4 또는 15 초과 | 5~15초만 지원 |
1080P에서는 watermark와 별칭 aigc_watermark를 모두 생략하세요. 값이 false여도 전달하지 마세요.2K, 중간 프레임 또는 4초 영상이 필요하면 MiniMax-H3를 사용하고 파라미터를 조정하세요.
입력 미디어 제한
전체 요청 본문은 64 MB 이하여야 합니다. 이미지·영상·오디오는 공개 URL을 사용하고 Base64는 사용하지 마세요.이미지
| 항목 | 제한 |
|---|---|
| 형식 | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| 파일당 | ≤ 30 MB |
| 너비와 높이 | 256~5760 px |
| 화면비 | 0.4~2.5 |
| 수량 | 첫 프레임 1장, 마지막 프레임 1장, 참조 이미지 9장까지. 프레임 이미지와 참조 이미지 혼용 불가 |
참조 영상
| 항목 | 제한 |
|---|---|
| 형식 | MP4 / MOV, H.264 / H.265 |
| 파일당 | ≤ 50 MB |
| 수량 | ≤ 3 |
| 개별 길이 | 2–15 s |
| 총 길이 | ≤ 15 s |
| 너비와 높이 | 256–5760 px |
| 화면비 | 0.4–2.5 |
| 프레임 속도 | 23.976–60 fps |
참조 오디오
| 항목 | 제한 |
|---|---|
| 형식 | WAV / MP3 |
| 파일당 | ≤ 15 MB |
| 수량 | ≤ 3 |
| 개별 길이 | 2–15 s |
| 총 길이 | ≤ 15 s |
예시
첫 프레임 이미지→동영상
{
"model": "MiniMax-H3-Max",
"prompt": "김이 피어오르며 카메라가 천천히 다가간다.",
"first_frame_image": "https://cdn.example.com/ramen.png",
"duration": 5,
"resolution": "480P"
}
첫·마지막 프레임 이미지→동영상
{
"model": "MiniMax-H3-Max",
"prompt": "아침에서 일몰로 천천히 전환된다.",
"first_frame_image": "https://cdn.example.com/morning.png",
"last_frame_image": "https://cdn.example.com/sunset.png",
"duration": 8,
"resolution": "768P"
}
1080P 텍스트 기반 영상
1080P에서는 watermark와 별칭 aigc_watermark를 모두 생략하세요. 값이 false여도 전달하지 마세요.
{
"model": "MiniMax-H3-Max",
"prompt": "해변의 일몰, 모래사장을 부드럽게 적시는 파도, 천천히 다가가는 카메라, 영화 같은 질감.",
"duration": 5,
"resolution": "1080P",
"aspect_ratio": "16:9"
}
멀티모달 참조 생성
참조 영상과 오디오는 각각 2~15초여야 합니다. 영상과 오디오 총 길이는 별도로 계산하며 각각 15초 이하여야 합니다. 초과 자료는 유효한 입력이 아니므로 제출 전에 잘라내세요.{
"model": "MiniMax-H3-Max",
"prompt": "참조 이미지 속 캐릭터가 참조 영상의 장면에서 달리며 참조 오디오의 리듬에 맞춘다.",
"image_urls": [
"https://cdn.example.com/role.png"
],
"video_urls": [
"https://cdn.example.com/scene.mp4"
],
"audio_urls": [
"https://cdn.example.com/beat.mp3"
],
"duration": 6,
"resolution": "1080P",
"aspect_ratio": "16:9"
}
작업 조회
제출 시task_id가 반환됩니다. 작업 상태를 5~10초마다 조회하고 클라이언트 제한 시간은 15분으로 설정하세요.
status | 의미 |
|---|---|
pending | 제출됨 또는 대기 중 |
processing | 생성 중 |
completed | 동영상 URL은 result.videos[0].url에 있음 |
failed | error.message 확인, 자동 환불 |
생성된 동영상 URL은 보통 약 24시간 후 만료됩니다. 즉시 다운로드해 보관하세요.
요금
총 비용에는 생성 영상, 초과 입력 이미지 및 참조 영상 요금이 포함됩니다.총 비용 = 영상 생성 초당 단가 × 출력 길이
+ 초과 이미지 단가 × max(0, 입력 이미지 수 − 2)
+ 참조 영상 초당 단가 × 참조 영상 총 길이
| 항목 | 단가 |
|---|---|
| 1080P 동영상 | 모델 가격 정책 기준 |
| 768P 동영상 | 모델 가격 정책 기준 |
| 480P 동영상 | 모델 가격 정책 기준 |
| 입력 이미지 | 처음 2장은 무료, 초과 이미지는 장당 과금; 모델 가격 정책 기준 |
| 참조 영상 | 입력 초 단위로 과금하며 단가는 모델 가격 정책 기준입니다. 출력 해상도에 따라 달라지며 영상 생성 단가와 별도입니다. |
| 참조 오디오 | 무료 |
| 예시 | 비용 |
|---|---|
| 768P / 5s | 768P 영상 생성 단가 × 5 |
| 768P / 10s | 768P 영상 생성 단가 × 10 |
| 480P / 10s | 480P 영상 생성 단가 × 10 |
| 480P / 15s | 480P 영상 생성 단가 × 15 |
| 768P / 5s + 이미지 × 3 | 768P 영상 생성 단가 × 5 + 초과 이미지 단가 × 1 |
| 480P / 10s + 참조 영상 (12s) | 480P 영상 생성 단가 × 10 + 480P 참조 영상 단가 × 12 |
| 1080P / 5s + 이미지 × 2 + 참조 오디오 | 1080P 영상 생성 단가 × 5 |
cost를 기준으로 합니다.
오류
| 상황 | 결과 |
|---|---|
비어 있거나 7000자를 넘는 prompt | 400, 작업 없음 |
duration이 5~15 범위 밖 | 400, 작업 없음 |
지원하지 않는 resolution | 400, 작업 없음 |
| 첫·마지막 프레임과 참조 자료 혼용 / 참조 오디오만 전달 | 400, 작업 없음 |
참조 이미지 9장 초과 또는 참조 영상·오디오 3개 초과 | 400, 작업 없음 |
| 참조 영상 길이를 읽을 수 없음 | 400, 작업 없음 |
| 잘못된 이미지 역할 또는 동일한 첫·마지막 프레임 역할에 이미지 1장 초과 | 400, 작업 없음 |
| 잔액 부족 | 402 |
| 콘텐츠 안전 거부 | 422 |
| 요청 제한 | 429, 지수 백오프로 재시도 |
status = failed와 error.message가 반환되고 자동 환불됩니다.
Response
integer
응답 상태 코드, 성공 시 200