FLUX 3 Max API: hiapi에서 텍스트-비디오, 이미지-비디오, 키프레임 사용하기

요약

• hiapi의 FLUX 3 Max는 동일한 POST /v1/tasks 엔드포인트에 있는 세 개의 독립 모델 ID입니다: flux-3-max/text-to-video, flux-3-max/image-to-video, flux-3-max/keyframes-to-video. 모드를 전환하려면 model과 입력 필드 하나만 변경하면 됩니다.
• 세 모델 모두 5–20초, 720p 또는 1080p 클립을 생성하며, 출력 초 수와 해상도에 따라 과금됩니다. 실시간 가격은 /en/pricing에서 확인하세요.
• 키프레임의 프레임 번호 규칙은 제출 시 검사되지 않습니다. 타임라인이 잘못되어도 인터페이스는 HTTP 200과 taskId를 반환하지만, 작업은 약 2초 후 실패합니다. 반드시 로컬에서 먼저 검증하세요.

이 가이드는 Max 등급을 대상으로 합니다. 초안 모드와 비디오 이어쓰기를 지원하는 기본 flux-3 모델은 FLUX.3 비디오 API 가이드를, 기존 소재 편집은 flux-3 비디오 편집을 참고하세요.

사전 준비

hiapi 콘솔에서 키를 생성하고 내보내세요:

export HIAPI_KEY=sk-your-key

모든 모드의 요청 흐름은 동일합니다: POST /v1/tasks가 taskId를 반환하면 GET /v1/tasks/<taskId>를 폴링하거나 콜백을 사용하여 status가 success가 될 때까지 기다린 후 data.output[0].url을 다운로드합니다.

입력에 따라 어떤 모델 ID를 사용할까

보유한 입력	모델 ID	변경할 입력
텍스트 프롬프트만 있는 경우	flux-3-max/text-to-video	prompt
정지 이미지 한 장 (선택적으로 마지막 프레임 한 장 추가)	flux-3-max/image-to-video	image_url, 선택적으로 end_image_url
특정 시점에 반드시 배치해야 하는 1–10장의 이미지	flux-3-max/keyframes-to-video	keyframes: [{image_url, frame_index}]

세 모델이 공유하는 선택 필드: duration(정수 초, 5–20, 기본값 5), resolution(720p 또는 1080p), aspect_ratio(auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16), generate_audio(불리언, 기본값 켜짐), reasoning_level(low 또는 high, 기본값 high). 모델 페이지: 텍스트-비디오, 이미지-비디오, 키프레임-비디오.

최소 예제: curl로 텍스트-비디오

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "input": {
      "prompt": "a slow aerial shot of ocean waves at sunrise, photorealistic",
      "duration": 5,
      "resolution": "720p",
      "generate_audio": false,
      "reasoning_level": "low"
    }
  }'

요청이 유효하면 {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}가 반환됩니다. 그런 다음:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... -H "Authorization: Bearer $HIAPI_KEY"

generate_audio와 5초 low 추론 설정은 프롬프트 효과를 저렴하게 확인하는 방법입니다. 모델 페이지에 따르면 오디오는 가격을 변경하지 않습니다.

세 가지 모드를 모두 다루는 Python 보조 스크립트

# pip install requests
import os, time, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://api.hiapi.ai/v1/tasks"

def submit(mode: str, **inp) -> str:
    """mode: text-to-video | image-to-video | keyframes-to-video"""
    body = {"model": f"flux-3-max/{mode}", "input": inp}
    res = requests.post(BASE, json=body, headers=H, timeout=30).json()
    if res.get("code") != 200:
        # sync 400s look like {"code":400,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}
        raise RuntimeError(res)
    return res["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900, every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

# 1) text-to-video
t2v = submit("text-to-video",
    prompt="A single white sneaker rotates slowly on a wet black plinth, studio softbox lighting, macro product shot",
    duration=5, resolution="720p", aspect_ratio="16:9", generate_audio=False)

# 2) image-to-video: first frame, optional last frame
i2v = submit("image-to-video",
    prompt="Morning mist drifts over the harbor; the boats rock gently and the camera slowly pushes forward.",
    image_url="https://example.com/harbor.jpg",
    # end_image_url="https://example.com/harbor-end.jpg",   # optional fixed ending
    duration=5, resolution="720p", generate_audio=False)

# 3) keyframes-to-video
FPS = 24
def keyframes_ok(duration: int, frames: list[dict]) -> None:
    idx = [f["frame_index"] for f in frames]
    assert 1 <= len(frames) <= 10, "1-10 keyframes"
    assert len(set(idx)) == len(idx), "frame_index must be unique"
    assert all(0 <= i <= duration * FPS for i in idx), f"frame_index must be 0..{duration * FPS}"

frames = [
    {"image_url": "https://example.com/harbor.jpg", "frame_index": 0},
    {"image_url": "https://example.com/latte.jpg",  "frame_index": 120},
]
keyframes_ok(5, frames)
kf = submit("keyframes-to-video",
    prompt="A continuous cinematic morph from the misty harbor into a close-up of an iced matcha latte.",
    keyframes=frames, duration=5, resolution="720p", generate_audio=False)

url = wait(kf)
open("clip.mp4", "wb").write(requests.get(url).content)

출력 URL은 만료되므로 작업 성공 후 링크를 저장하지 말고 즉시 다운로드하거나 파일을 복사해야 합니다.

키프레임: 타임라인 작동 방식

frame_index는 백분율이 아니라 0에서 시작하는 24fps 시계상의 위치입니다. 허용되는 최댓값은 duration × 24입니다: 5초는 120, 10초는 240, 20초는 480입니다. 인덱스는 고유해야 하며 1~10개의 키프레임을 전달할 수 있습니다. 깔끔한 A에서 B로의 전환을 만들려면 첫 앵커를 0에, 마지막 앵커를 duration × 24에 배치하세요. 마지막 앵커를 앞당기면 결말이 유지되고, 늦추면 변화가 압축됩니다. 모든 키프레임의 종횡비를 일치시키고, 매끄러운 루프를 원하면 첫 이미지와 마지막 이미지가 같은 순간처럼 보이게 하세요.

프로덕션 환경 유의 사항

• 폴링과 콜백. 작업 API는 callback.url과 when: "final"을 허용하므로 폴링할 필요가 없습니다. 위처럼 10초마다 폴링하는 것도 스크립트와 배치 작업에는 문제없습니다.
• 폴링 루프에는 항상 타임아웃을 설정하고, 폴링 전에 taskId를 영속화하여 프로그램이 충돌해도 이미 과금된 작업을 잃지 않도록 하세요.
• 즉시 다운로드하세요. output[0].url은 단기 유효한 것으로 간주하세요.
• 비용 제어. 과금은 출력 초 수와 해상도에 따라 계산되므로 20초 1080p 클립은 5초 720p 테스트보다 몇 배 더 비쌉니다. 먼저 5초와 720p로 프로토타이핑하고, 프롬프트가 효과적이면 둘 다 높이세요. 현재 요금은 가격 페이지에서 확인하세요.

내가 테스트한 것과 하지 않은 것

이 검사들은 2026년 10월 23일 읽기 전용 테스트 키로 실제 API를 대상으로 수행되었습니다. 이 글은 전체 클립을 렌더링하지 않았으므로 출력 품질에 대해 어떠한 주장도 하지 않습니다. 예제 프롬프트는 모델 페이지에 포함된 예제에서 가져왔습니다.

동기 검증 (HTTP 400, 대기열 미등록). 범위를 벗어난 값은 제출 시 즉시 거부되며 error_code: INVALID_REQUEST와 읽을 수 있는 message가 반환됩니다:

요청	응답 message
duration: 3	invalid input: duration: minimum: got 3, want 5
resolution: "4k"	value must be one of '720p', '1080p'
aspect_ratio: "5:4"	value must be one of 'auto', '21:9', '2:1', '16:9', '4:3', '1:1', '3:4', '9:16'
reasoning_level: "medium"	value must be one of 'low', 'high'
이미지-비디오에 image_url 대신 image_urls 사용	image_url: missing required field "image_url"; ... additional properties 'image_urls' not allowed

마지막 행은 흔한 실수입니다: hiapi의 다른 이미지 입력 모델은 복수형 필드를 사용하지만, FLUX 3 Max 이미지-비디오는 단일 image_url만 허용합니다. 알 수 없는 필드는 무시되지 않고 거부됩니다.

키프레임 타임라인 오류는 비동기입니다. 저는 타임라인에 문제가 있는 5초 키프레임 요청 두 개를 제출했습니다: 하나는 frame_index: 121(120 상한 초과)을 사용했고, 다른 하나는 두 키프레임 모두 frame_index: 0에 있었습니다. 둘 다 수락되어 HTTP 200과 taskId가 반환되었습니다. 생성 후 약 1–2초 뒤 폴링하면 종료 상태가 반환됩니다:

{"code":200,"data":{"status":"fail","model":"flux-3-max/keyframes-to-video",
 "error":{"code":"INVALID_REQUEST","message":"Invalid request parameters for this model. Please check the request and try again."},
 "taskId":"tk-hiapi-..."},"message":"success"}

여기서 두 가지를 알 수 있습니다. 첫째, 제출이 200을 반환한다고 해서 타임라인이 유효한 것은 아니므로 폴링 시 status와 error.code를 확인해야 합니다. 둘째, 실패 메시지가 매우 포괄적이어서 어느 프레임에 문제가 있는지 알려주지 않으므로, 위의 keyframes_ok 검사를 제출 전에 실행할 가치가 있습니다. 모델 페이지에 따르면 실패한 작업은 과금되지 않습니다. 저는 두 작업의 청구 기록을 확인하지 않았습니다.

자주 묻는 질문

첫 프레임과 마지막 프레임에는 어떤 모델 ID를 사용해야 하나요? flux-3-max/image-to-video를 사용하고 image_url과 end_image_url을 전달하세요. 첫 프레임과 마지막 프레임 사이에 앵커를 설정해야 할 때만 키프레임을 사용하세요.

키프레임을 늘리면 더 비싸지나요? 모델 페이지에 따르면 아닙니다: 과금은 출력 초 수와 해상도에 따라 계산되며 앵커 수는 가격에 영향을 주지 않습니다.

flux-3와 무엇이 다른가요? flux-3-max/*는 모드별(텍스트, 이미지, 키프레임)로 분리된 독립 모델 ID이고, 기본 flux-3는 하나의 ID로 입력에 따라 모드를 전환하며 초안 모드와 이어쓰기도 지원합니다. FLUX.3 비디오 API 가이드를 참고하세요. 저는 두 모델의 출력 품질을 비교하지 않았으므로 기능과 가격 페이지의 요금을 기준으로 선택하세요.

다른 이미지-비디오 모델로 바꿀 수 있나요? 네. 다른 이미지-비디오 솔루션은 Ray 3.2 이미지-비디오 API 사용 방법을 참고하세요.