튜토리얼

HiAPI API로 flux-3-max/keyframes-to-video를 호출하는 방법: curl 및 Python 가이드

개발자를 위한 인증, 키프레임 제출, 작업 폴링 및 결과 가져오기

Nov 3, 2026

이 통합이 실제로 하는 일

flux-3-max/keyframes-to-video는 키프레임 이미지를 기반으로 동영상을 생성하는 비동기 작업 API입니다. 결과를 동일한 HTTP 응답으로 반환하는 동기 엔드포인트와 달리, 이 모델은 키프레임을 받아 백그라운드 작업을 생성하고 진행 상황을 확인할 수 있는 작업 식별자를 반환합니다.

전체 수명 주기는 네 단계로 나뉩니다:

인증 — 모든 요청에 HiAPI API 키가 포함됩니다.
제출 — 키프레임과 파라미터를 보내 동영상 작업을 시작합니다.
폴링 — 최종 상태에 도달할 때까지 작업 상태를 반복 조회합니다.
가져오기 — 작업 성공 시 반환된 URL에서 생성된 동영상을 다운로드합니다.

이 수명 주기를 염두에 두면 클라이언트 작성 방식이 결정됩니다: 제출과 결과 가져오기는 별도의 호출이며, 애플리케이션은 수십 초에서 수 분이 걸릴 수 있는 작업을 견딜 수 있어야 합니다. 아래의 curl 및 Python 예제는 동일한 네 단계를 따르므로 이 흐름을 어떤 언어나 작업 러너로든 이식할 수 있습니다.

API 키 발급 및 인증

API 키는 HiAPI 대시보드에서 발급됩니다. 비밀번호처럼 취급하세요: 계정을 식별하고 과금 호출을 승인하므로 소스 코드, 커밋 기록, 로그 출력에 절대 나타나서는 안 됩니다.

인증은 모든 요청에서 HTTP 헤더로 전달됩니다:

Authorization: Bearer $HIAPI_API_KEY

실제로는 키를 환경 변수에 저장하고 런타임에 읽으세요. 셸 예제의 경우 세션마다 한 번 익스포트합니다:

export HIAPI_API_KEY="your-key-here"

Python의 경우 문자열을 하드코딩하지 말고 os.environ["HIAPI_API_KEY"]로 읽으세요. .env 파일을 .gitignore에 추가하고, 디버깅을 위해 요청을 로깅한다면 Authorization 헤더가 로그 수집기에 도달하기 전에 마스킹하세요. 키가 노출된 적이 있다면 즉시 대시보드에서 교체하세요.

curl로 요청 구성하기

동영상 작업을 제출한다는 것은 모델을 지정하고 키프레임을 담은 JSON 본문을 보내는 것입니다. 키프레임 입력과 생성 파라미터의 정확한 필드 이름은 모델 페이지에 문서화되어 있으므로 이를 권위 있는 출처로 삼으세요. 아래 구조는 요청의 형태를 보여줍니다.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/keyframes-to-video",
    "input": {
      "keyframes": [
        "https://example.com/frame-01.png",
        "https://example.com/frame-02.png"
      ]
    }
  }'

각 부분의 역할:

model — flux-3-max/keyframes-to-video를 선택하므로, 나중에 전송 코드를 변경하지 않고도 같은 엔드포인트를 다른 모델로 라우팅할 수 있습니다.
input.keyframes — 순서가 있는 이미지 URL 목록입니다. 순서가 중요합니다: 첫 프레임이 클립의 시작을 고정하고 이후 프레임이 이어지는 순간을 이끕니다.
Authorization — 위에서 설명한 bearer 헤더입니다.
Content-Type — JSON 본문에 필요합니다.

응답은 식별자를 포함한 작업 객체입니다. 이 ID를 저장하세요. 이후 모든 폴링의 핸들입니다.

Python에서의 동일한 요청

Python 버전은 curl 호출을 그대로 반영합니다. requests를 사용하면 간결하게 유지할 수 있지만, 의존성이 전혀 없기를 원한다면 표준 라이브러리도 충분히 가능합니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"


def submit_video_task(keyframe_urls: list[str]) -> str:
    response = requests.post(
        f"{BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "flux-3-max/keyframes-to-video",
            "input": {"keyframes": keyframe_urls},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


task_id = submit_video_task([
    "https://example.com/frame-01.png",
    "https://example.com/frame-02.png",
])
print(task_id)

유지할 가치가 있는 두 가지 세부 사항: 명시적인 timeout으로 멈춘 연결이 작업 프로세스를 영원히 차단하지 않게 하고, raise_for_status()로 4xx 또는 5xx가 조용한 오류 페이로드가 아니라 예외로 드러나게 합니다. 함수를 작고 순수하게 유지하세요 — 제출하고 ID를 반환하는 것, 그게 전부여야 합니다. 폴링은 별개의 일입니다.

작업 상태 폴링 및 결과 가져오기

동영상 생성에는 실제 연산 시간이 필요하므로 API는 파일이 나타날 때까지 블록하지 않습니다. 대신 작업이 완료될 때까지 조회합니다. 상태가 succeeded이면 출력 URL을 담고, failed이면 오류를 담으며, 그 밖의 값은 계속 기다리라는 의미입니다.

import time
import requests


def wait_for_video(task_id: str, poll_interval: int = 5, max_wait: int = 600) -> str:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "succeeded":
            return task["output"]["video_url"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(poll_interval)

    raise TimeoutError(f"task {task_id} did not finish in time")

프로덕션 설계 지침:

폴링 간격 — 몇 초면 충분합니다. 엔드포인트를 마구 호출하면 부하만 늘어날 뿐 작업이 더 빨리 끝나지는 않습니다.
기한 — 항상 총 대기 시간을 제한하고, 영원히 반복하지 말고 실패 시 크게 오류를 내세요.
다운로드 — 반환된 URL은 임시입니다. 작업 성공 후 즉시 파일을 가져와 자체 스토리지로 옮기세요.
분리 — 웹 애플리케이션에서는 이 루프를 백그라운드 작업 프로세스에서 실행하고 HTTP 요청을 열린 채 유지하지 말고 webhook이나 큐를 통해 클라이언트에 알리세요.

오류 및 엣지 케이스 처리

대부분의 통합 실패는 네 가지 범주로 나뉩니다.

인증 오류 (401/403). 키가 없거나, 형식이 잘못되었거나, 더 이상 유효하지 않습니다. 환경 변수가 실제로 호출을 수행하는 프로세스에 익스포트되었는지 확인하세요 — 로컬 셸에서는 정상 작동하지만 컨테이너나 cron 작업에는 변수가 없는 것이 흔한 함정입니다.

입력 오류 (4xx). 접근할 수 없는 키프레임 URL, 지원되지 않는 이미지 형식 또는 허용 범위를 벗어난 파라미터는 제출을 거부합니다. 제출 전에 모든 키프레임 URL이 공개적으로 접근 가능한지 검증하세요. 느리거나 제한된 호스트는 원래 올바른 요청이 실패하는 가장 흔한 원인입니다.

작업 실패. 작업이 수락된 후 생성 중에 실패할 수 있습니다. 완료된 폴링을 성공으로 간주하지 말고 항상 오류 필드를 확인하세요. 지원 요청과 연관 지을 수 있도록 작업 ID를 오류와 함께 기록하세요.

타임아웃 및 재시도. 제출 시 네트워크 오류는 일반적으로 백오프를 사용해 안전하게 재시도할 수 있습니다. 성공 제출 후 재시도는 안 됩니다 — 중복 작업을 생성하고 중복 요금이 발생할 수 있습니다. 재시도 전에 응답을 읽고, 폴링 루프에서도 지터를 포함한 지수 백오프를 사용하세요.

마지막 위생 팁: Authorization 헤더를 절대 기록하지 말고, 키프레임 URL에 서명된 쿼리 문자열이 포함되어 있다면 정리하세요. 이 모델의 필드 이름이나 제한에 대해 의문이 있을 때는 flux-3-max/keyframes-to-video 문서를 확인하고 클라이언트에서 그 값을 그대로 따르세요.