튜토리얼

HiAPI API로 flux-3-video 호출하는 방법: curl, Python 및 실제로 동작하는 요청 예제

텍스트 투 비디오, 비디오 연장, 네이티브 오디오 파라미터를 아우르는 실용 통합 가이드

Nov 3, 2026

flux-3-video가 API를 통해 제공하는 기능

첫 줄의 코드를 작성하기 전에 flux-3-video 모델이 HiAPI API를 통해 정확히 무엇을 할 수 있는지 이해하면 큰 도움이 됩니다. 이 엔드포인트 계열은 동일한 요청 구조를 공유하는 두 가지 호출 모드를 제공하며, 그와 더불어 사용 사례에 따라 켜거나 무시할 수 있는 선택적 오디오 기능도 있습니다.

두 가지 호출 모드

텍스트 투 비디오 — 텍스트 프롬프트를 보내면 새로 생성된 비디오 클립을 받습니다. 아이디어만 있고 모델이 동작, 구도, 리듬을 생성해 주길 원할 때 이 모드를 사용합니다.
비디오 연장 — 기존 비디오 클립(또는 그 참조)과 지시를 보내면 모델이 이를 앞으로 이어 붙입니다. 이미 소재가 있고 눈에 띄는 이음새 없이 더 많은 내용을 얻고 싶을 때 이 모드를 사용합니다.

네이티브 오디오

이 모델은 비디오를 생성하면서 동시에 네이티브 오디오를 산출할 수도 있으며, 이는 같은 요청 페이로드 내의 선택적 파라미터로 제어됩니다. 이들 파라미터는 선택 사항이므로 순수 비디오 워크플로에서는 전혀 고려할 필요가 없습니다. 오디오 필드를 생략하기만 하면 요청은 그것들이 없을 때와 완전히 동일하게 동작합니다.

이 가이드의 이후 내용이 의존하는 핵심 멘털 모델은 이것입니다: 이것은 서로 독립된 두 개의 API도, 두 개의 별도 튜토리얼도 아닙니다. 같은 요청의 두 가지 형태이며, 공유 골격을 한 번 이해하면 두 모드 사이를 오가는 일은 입력 몇 개를 바꾸는 것에 불과합니다. 나머지 전부—자격 증명, 요청 헤더, 모델 식별자, 응답 처리—는 그대로 유지됩니다.

이 설계는 의도된 것입니다. 즉, 인증 코드, 오류 처리, 재시도 로직, 응답 파싱을 한 번만 작성하면 두 모드에서 재사용할 수 있고, 나중에 오디오를 추가한다고 해서 다시 작성해야 하는 일도 없습니다.

인증, 엔드포인트, 요청 구조 해부

flux-3-video에 대한 모든 호출은 동일한 골격을 따릅니다. 한 번 익히면 두 호출 모드는 같은 주제의 변형일 뿐입니다.

자격 증명

HiAPI는 API key로 요청을 인증합니다. 보통 bearer token 형태로 요청 헤더에 담아 전달합니다. 키를 소스 코드에 쓰지 말고—환경 변수나 비밀 관리자에서 읽어 버전 관리 시스템에 절대 들어가지 않도록 하세요:

export HIAPI_API_KEY="your-key-here"

엔드포인트와 모델 식별자

호출은 HiAPI API의 기본 URL로 전송되며, 페이로드에서 식별자 flux-3-video로 모델을 명시합니다. 모델 이름을 URL에 하드코딩하지 않고 요청 본문에 두면, 동일한 클라이언트 코드가 나중에 한 줄만 수정해 다른 모델을 가리킬 수 있습니다.

공유 페이로드 구조

모드에 관계없이 페이로드는 개념적으로 세 부분으로 구성된 JSON 객체입니다:

model 필드 — 항상 flux-3-video입니다.
모드를 정의하는 입력 — 텍스트 투 비디오에서는 프롬프트이고, 연장에서는 소스 비디오 클립과 프롬프트입니다. 두 모드 사이에서 실질적으로 달라지는 유일한 부분입니다.
선택적 수정 항목 — 오디오 파라미터와 기타 조정 항목입니다. 생략하면 기본 동작이 됩니다.

한 요청의 의사 구조는 다음과 같습니다:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

전체적인 아이디어는 이렇습니다: 모델 식별자 하나, 모드 전용 필드를 담는 중첩된 input 객체 하나, 그리고 필요할 때만 추가하는 선택적 키입니다. 다음 섹션에서 각 모드의 구체적인 내용을 하나씩 설명합니다.

텍스트 투 비디오: 첫 번째로 동작하는 curl 요청

아래는 프롬프트로 비디오를 생성하는 최소하지만 완전한 요청입니다. HIAPI_API_KEY가 셸에 이미 export되어 있다고 가정합니다.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

각 필드의 역할

Authorization — bearer token을 담습니다. 이것이 없으면 생성이 시작되기도 전에 요청이 거부됩니다.
Content-Type: application/json — 요청 본문은 JSON이므로 이를 선언해야 합니다. 이를 빠뜨리는 것이 혼란스러운 4xx 응답을 초래하는 흔한 원인입니다.
model — flux-3-video를 대상 모델로 지정합니다.
input.prompt — 텍스트 투 비디오 모드에서 유일하게 필수인 창작 입력입니다. 샷 묘사처럼 작성하세요: 피사체, 동작, 구도, 조명, 분위기.

투자할 가치가 있는 프롬프트 작성 요령

이 모드에서 프롬프트가 유일한 창작 제어 수단이므로 그 품질이 결과를 직접 좌우합니다. 두 가지 습관이 도움이 됩니다:

내용뿐 아니라 동작을 묘사하세요. “A dolly shot through…”(돌리 샷이 …을 관통하는)는 모델이 애니메이션화할 카메라 동작을 제공하지만, 정적인 묘사는 아무것도 할 수 없게 만듭니다.
구체적으로 유지하세요. 구체적인 조명과 재질 단서(“wet asphalt”, “neon reflections”)가 추상적인 형용사보다 일관성 있는 화면을 만들어내는 경우가 많습니다.

이 요청을 실행하고 응답을 확인하면 키, 헤더, 기본 페이로드를 검증한 것이며, 이것이 이후 모든 것의 기반이 됩니다.

비디오 연장: 기존 클립 이어 붙이기

연장은 이전 섹션의 골격을 재사용하지만 input 객체의 형태가 달라집니다. 프롬프트가 단독으로 존재하지 않고, 모델이 연장할 소스 클립과 짝을 이룹니다.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

텍스트 투 비디오와의 차이

비디오 입력이 등장합니다. 모델이 기반으로 삼을 기존 클립을 제공합니다. 이것이 두 모드를 가르는 결정적 차이입니다.
프롬프트가 생성적이 아니라 방향 제시적이 됩니다. 텍스트 투 비디오에서는 전체 장면을 묘사하지만, 여기서는 다음에 무엇이 일어날지를 묘사합니다. 연장 지시로 작성하세요: 카메라가 어디로 가는지, 무엇이 화면에 들어오는지, 장면이 어떻게 전개되는지.
나머지는 모두 동일합니다. 동일한 엔드포인트, 동일한 헤더, 동일한 모델 식별자, 동일한 input 래퍼입니다. 클라이언트 코드는 페이로드를 구성할 때까지 분기할 필요가 없습니다.

이음새에서의 일관성 유지

모델은 눈에 띄는 컷을 피하기 위해 소스 클립의 룩을 맞출 필요가 있습니다. 기존 스타일을 유지하는 짧고 구체적인 지시가 장면을 재구성하는 긴 묘사보다 더 나은 결과를 내는 경우가 많습니다. 첫 연장이 어긋난다면 다른 곳에 세부 사항을 더하는 대신, 프롬프트를 소스 클립의 실제 내용에 더 가깝게 다듬으세요.

클립 참조에 관한 참고

소스 클립의 정확한 입력 규약은 HiAPI에서 해당 모델의 입력 schema로 정의됩니다. 필드 형식을 추측하지 말고 그 schema를 따르세요—그것이 연장 입력으로 어떤 형식이 허용되는지의 권위 있는 출처입니다.

네이티브 오디오 파라미터 추가

네이티브 오디오는 선택적 수정 항목 패턴이 가치를 발휘하는 지점입니다. 오디오 파라미터는 다른 필드와 마찬가지로 같은 input 객체 안에 있으며, 선택 사항이므로 이전 두 섹션의 요청은 그것들이 없어도 여전히 유효합니다.

위치

오디오 설정은 input 내부에, prompt 및 (연장 모드의) video와 나란히 위치합니다. 개념적으로:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

순수 비디오 워크플로 보호하기

여기서 중요한 원칙은 간단합니다: 오디오 블록은 순전히 부가적인 것으로 취급하세요.

오디오 필드를 명시적으로 “꺼짐” 값으로 설정하지 마세요 — 생략하면 됩니다. 해당 블록이 없으면 명시적으로 비활성화하는 것보다 더 깔끔하고, 향후 schema 변경과 충돌할 가능성도 적습니다.
페이로드를 점진적으로 구성하세요. 최소 요청 본문에서 시작하여 사용자가 실제로 오디오를 요청하는 코드 경로에서만 audio 키를 추가하세요. 이렇게 하면 기본 경로가 순수 비디오 예제와 정확히 일치합니다.
오디오를 프로덕션에 연결하기 전에 schema를 확인하여 정확한 플래그 이름과 허용 값을 확인하세요. 파라미터 명명은 HiAPI에서 해당 모델의 입력 schema로 정의됩니다. 위 블록 이름은 위치만 보여줄 뿐 필드 철자를 보장하지 않습니다.

언제 활성화할까

결과물이 완성된 자기완결적 비디오 클립일 때—소셜 미디어 콘텐츠, 데모, 짧은 내러티브 작품—오디오를 활성화하세요. 다운스트림에서 별도의 사운드트랙이나 내레이션을 입힐 때는 비활성화하세요. 결국 버릴 오디오를 생성하는 것은 파이프라인에서 연산을 낭비하는 일입니다.

오디오는 다른 모든 것과 같은 페이로드에 실리므로 별도의 호출도, 두 번째 자격 증명도, 응답이 반환하는 내용을 읽는 것 외에 추가적인 응답 처리 분기도 필요하지 않습니다.

Python으로 같은 요청 작성하기

curl 호출을 Python으로 옮기는 것은 요청 구조가 완전히 동일하기 때문에 기계적인 작업입니다. 아래 예제는 표준 라이브러리만 사용하므로 어떤 환경에서도 실행됩니다. requests나 httpx를 선호한다면 구조는 그대로 대응됩니다.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

이렇게 구성한 이유

하나의 함수, 두 가지 모드. video 파라미터는 선택 사항이며, None이면 함수가 텍스트 투 비디오 요청을 생성합니다. 값이 설정되면 같은 함수가 연장 요청을 생성합니다. 별도의 클라이언트도, 중복된 헤더도 없습니다.
오디오는 명시적으로 활성화해야 합니다. audio 플래그는 기본값이 False이므로 명시적으로 요청하지 않는 한 오디오 블록이 절대 추가되지 않습니다—이것이 앞서 설명한 패턴입니다.
키는 환경에서 옵니다. API key는 HIAPI_API_KEY에서 읽으며 절대 하드코딩하지 않습니다.

변형할 때는 print 호출을 파이프라인에 필요한 작업—응답을 매니페스트에 쓰기, 후속 작업 큐에 넣기, 또는 어떤 큐에 알림 보내기—으로 대체하기만 하면 됩니다. 요청 로직 자체는 바꿀 필요가 없습니다.

문제 해결 및 프로덕션 환경 체크리스트

호출이 실패하면 다음 목록을 순서대로 점검하세요—대부분의 문제를 포괄합니다.

진단 체크리스트

401 또는 인증 오류 — HIAPI_API_KEY가 코드를 실행하는 셸이나 프로세스에 실제로 export되어 있나요? 한 터미널에서 설정한 키는 cron 작업으로 전달되지 않습니다.
415 또는 예기치 않은 파싱 오류 — Content-Type: application/json이 있나요? 이를 빠뜨리는 것이 가장 전형적인 조용한 실패입니다.
연장 호출이 4xx 반환 — 페이로드에 소스 클립이 모델 입력 schema가 기대하는 형식으로 포함되어 있나요? 형식이 잘못된 클립 참조는 생성이 시작되기 전에 실패합니다.
출력에 오디오가 없음 — audio 블록이 실제로 페이로드에 들어갔나요? 디버깅할 때는 직렬화된 요청 본문을 기록하세요. 딕셔너리를 만들고 키를 붙이는 것을 잊는 일은 흔히 발생합니다.
input이 비어 있거나 잘림 — 실제로 전송하는 정확한 JSON을 출력하세요. 거의 모든 “이상한” 실패는 전송 중인 요청 본문을 직접 보면 해결됩니다.

배포 전

키를 절대 하드코딩하지 마세요. 항상 환경 변수나 비밀 관리자를 사용하세요.
요청 본문과 응답 본문을 모두 기록하세요, 최소한 스테이징 환경에서는 그렇게 하세요. 정확한 페이로드 없이 실패를 재현하는 것은 추측에 불과합니다.
선택 필드는 선택 사항으로 취급하세요. 페이로드를 점진적으로 구성하세요—먼저 최소 요청 본문, 그다음 video 추가, 마지막으로 필요할 때만 audio 추가. 이렇게 하면 기본 경로가 문서 예제와 일치하게 유지됩니다.
자신의 코드에서 모드 선택을 명시적으로 보이게 하세요. 선택적 video 파라미터가 있는 함수 하나는 괜찮지만, 불리언을 세 겹 깊이에 묻는 것은 안 됩니다.
필드를 추가할 때마다 HiAPI에서 해당 모델의 입력 schema를 다시 확인하세요. 그것이 파라미터 이름과 허용 형식의 권위 있는 참조이며 어떤 튜토리얼보다도 최신입니다.

핵심 요점을 다시 강조할 가치가 있습니다: 텍스트 투 비디오, 연장, 네이티브 오디오는 같은 요청 형태의 세 가지 변형입니다. 골격을 한 번 익히면 새로운 기능 각각은 재작성이 아니라 부가적인 변경일 뿐입니다. 즐겁게 구축하세요.

모든 아티클 보기 →