Hailuo（MiniMax）시리즈

MiniMax의 Hailuo 동영상 생성 모델로 모두 두 가지이며, OfoxAI 동영상 API POST /v1/videos로 호출합니다. 작업은 비동기로 실행됩니다. 작업을 생성하면 작업 ID를 받고, 그 ID로 결과를 조회합니다.

모델 선택

핵심2K 출력이 필요하면 Hailuo 3, 480p가 필요하면 Hailuo 3 Max를 선택하십시오. 두 모델 모두 720p와 1080p를 지원하지 않습니다.

모델	해상도（기본값）	길이	화면비
Hailuo 3	`768p` `2k`（`768p`）	4–15초	`21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive`
Hailuo 3 Max	`480p` `768p`（`768p`）	5–15초	위와 동일

두 모델 모두 텍스트-투-비디오, 이미지-투-비디오, 동영상 참조를 지원하며, 동기화된 오디오 트랙을 생성할 수 있습니다（generate_audio 기본값 true）. adaptive는 입력 이미지의 비율을 그대로 사용한다는 뜻입니다.

모델 ID（호출 시 그대로 복사）

Hailuo 3minimax/hailuo-3768p, 2K

Hailuo 3 Maxminimax/hailuo-3-max480p, 768p, 최소 5초

위 표는 Models API가 반환하는 video_attributes와 일치합니다. 모델 기능이 조정되면 API 반환값을 기준으로 하십시오. 초 단위로 과금되며 실제 비용은 작업 결과의 usage.video_cost를 기준으로 합니다. 가격은 모델 페이지 를 참고하십시오.

호출 예시

아래 예시는 작업 생성 요청만 보여 줍니다. 생성 후 상태 조회와 결과 다운로드까지의 전체 흐름은 Video API · 빠른 시작을 참고하십시오.

텍스트-투-비디오

prompt만 전달합니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "와이드스크린 샷: 사막 도로 위 클래식 자동차가 석양을 향해 달린다",
    "duration": 6,
    "resolution": "768p",
    "aspect_ratio": "21:9"
  }'

이미지-투-비디오

frame_images에 first_frame 1장을 전달하면 해당 이미지를 첫 프레임으로 하는 동영상이 생성됩니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "화면 속 인물이 몸을 돌려 먼 곳으로 걸어간다",
    "duration": 5,
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/first.jpg" }, "frame_type": "first_frame" }
    ]
  }'

동영상 참조

input_references에 동영상 1개를 참조로 전달합니다. 동영상을 입력으로 사용하면 과금 초에 입력 동영상의 길이가 포함될 수 있습니다.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "카메라 움직임은 유지하고, 화면을 수묵 애니메이션 스타일로 바꾼다",
    "duration": 5,
    "input_references": [
      { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" } }
    ]
  }'

frame_images와 input_references는 함께 전달할 수 없으며, 함께 전달하면 400 references_conflict가 반환됩니다.
오디오 트랙이 필요 없으면 "generate_audio": false를 전달합니다.
필드 구조의 전체 설명은 동영상 작업 생성을 참고하십시오.

해상도 표기

Hailuo의 해상도 구간은 다른 시리즈와 달리 768p와 2k（소문자 k）입니다. 다른 시리즈에서 흔히 쓰는 720p, 1080p를 전달하면 400이 반환됩니다.

자주 발생하는 오류

핵심파라미터 검증 오류는 생성 시점에 바로 반환되며, 작업이 생성되지 않고 비용도 발생하지 않습니다. 오류 메시지에 허용 값이 표시됩니다.

HTTP · code	오류 메시지 원문	원인	해결 방법
400 `unsupported_parameter`	`resolution "1080p" not supported; allowed: [768p 2k]`	Hailuo는 1080p를 지원하지 않음	Hailuo 3에서는 `768p` 또는 `2k` 사용
400 `unsupported_parameter`	`duration 4 out of range [5, 15]`	Hailuo 3 Max는 최소 5초	5초 이상으로 변경하거나 Hailuo 3 사용
400 `references_conflict`	`frame_images and input_references are mutually exclusive`	두 가지 소재 필드를 함께 전달함	둘 중 하나만 선택
404 `model_not_found`	`model not found`	모델 ID 철자 오류	이 페이지에서 모델 ID 복사

전체 오류 코드는 Video API 오류 코드를 참고하십시오.

공식 문서

자주 묻는 질문

Hailuo 3는 1080p를 지원합니까?

지원하지 않습니다. Hailuo 3의 해상도는 768p와 2k, Hailuo 3 Max는 480p와 768p입니다. 720p나 1080p를 전달하면 400 resolution not supported가 반환됩니다.

Hailuo 3 Max에서 duration 4 out of range [5, 15] 오류가 납니다

Hailuo 3 Max는 작업 하나당 최소 5초, 최대 15초입니다. 4초 동영상이 필요하면 Hailuo 3를 사용하십시오.

Hailuo 동영상은 21:9를 지원합니까?

지원합니다. Hailuo 3와 Hailuo 3 Max 모두 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive를 지원합니다.