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

flux-3-max/text-to-video의 기능과 적용 시나리오

flux-3-max/text-to-video는 HiAPI의 텍스트-투-비디오 엔드포인트입니다. 장면을 설명하는 프롬프트를 보내면 모델이 생성된 영상 클립을 반환합니다. 제품 티저, 소셜 미디어 숏폼 영상, 스토리보드 미리보기, 대량 생성된 빈 샷처럼 기존 소재 대신 문자로 된 구상만 있고, 생성 과정을 직접 실행하는 대신 관리형 작업으로 처리하고 싶을 때 적합한 도구입니다.

영상이 더 큰 흐름의 일부일 뿐인 워크플로에 적합합니다. 스크립트 생성기가 프롬프트를 만들고, flux-3-max/text-to-video가 이를 영상 클립으로 변환하며, 애플리케이션이 결과를 저장하거나 전달합니다. 호출이 비동기이므로 렌더링 시간 동안 요청을 열어 둘 수 없는 백엔드 서비스에도 적합합니다.

기존 영상을 프레임 단위로 정밀하게 편집해야 하거나 프롬프트가 사실상 정적 이미지 하나뿐일 때는 사용하지 마세요. 후자의 경우 텍스트-투-이미지 엔드포인트가 더 저렴하고 빠릅니다. 출력이 제공된 소재에 반응해야 한다면 이미지-투-비디오 변형을 사용해야 합니다. flux-3-max/text-to-video는 프롬프트에서 영상 클립 생성으로 이어지는 진입점으로 보고, 동기 응답이 아닌 작업 제출을 중심으로 통합을 설계하세요.

요청 구조: 엔드포인트, 인증 및 페이로드

flux-3-max/text-to-video에 대한 모든 요청은 세 부분으로 구성됩니다. 엔드포인트 경로, 인증 헤더, 모델과 입력을 지정하는 JSON 요청 본문입니다.

인증

HiAPI는 bearer 토큰을 사용합니다. API 키를 Authorization 헤더에 넣으세요.

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

키는 서버 측에 보관하세요. 클라이언트 코드에 포함하거나 버전 관리 시스템에 커밋하지 마세요. 개발 시에는 환경 변수에서, 프로덕션에서는 비밀 관리자에서 불러오세요.

모델 식별자

요청 본문에서 model 필드로 엔드포인트를 선택합니다. 정확한 식별자 flux-3-max/text-to-video를 사용하세요. 여기서의 오타는 요청이 거부되는 가장 흔한 원인입니다.

페이로드 구조

최소 요청 본문에는 모델 이름과 프롬프트가 포함됩니다.

{
  "model": "flux-3-max/text-to-video",
  "prompt": "일출 무렵 안개에 싸인 소나무 숲 상공을 천천히 지나가는 항공 촬영, 영화 같은 조명"
}

선택적 필드인 길이와 네이티브 오디오 스위치는 다음 섹션에서 다룹니다. 생성이 비동기이므로 이 POST 요청의 즉각적인 응답은 식별자가 포함된 작업 객체이며, 완성된 영상을 바로 받는 것이 아니라 해당 식별자를 폴링해야 합니다. 코드는 다른 정보보다 먼저 이 식별자를 읽도록 설계하세요.

길이와 네이티브 오디오 제어

두 가지 요청 수준 제어 항목이 결과를 결정합니다. 영상 클립의 길이와 모델이 영상과 함께 오디오를 생성할지 여부입니다.

길이

페이로드의 duration 필드로 클립 길이를 설정합니다. 서사에 필요한 가장 짧은 길이를 선택하세요. 짧은 영상은 더 빠르게 렌더링되고 검토하기 쉬우며, 언제든지 추가로 요청할 수 있습니다. 제출 전에 flux-3-max/text-to-video 문서의 범위에 따라 값을 검증하세요. 범위를 벗어난 길이는 제출 시 거부되며, 로컬에서 이 문제를 잡아내면 한 번의 왕복을 절약할 수 있습니다.

네이티브 오디오

네이티브 오디오 스위치는 모델이 영상 클립과 함께 오디오 트랙을 생성할지 결정합니다. 영상을 소리와 함께 시청할 때는 켜고, 영상을 무음으로 처리하거나 자막을 넣거나 후반에 별도로 음악을 입힐 때는 끄세요. 버릴 오디오를 생성하는 것은 이득 없이 작업 시간만 늘립니다.

의도적으로 선택하기

기본값이 대신 결정하게 두지 마세요. 빠른 스토리보드 검토에는 짧고 무음인 클립으로 보통 충분합니다. 최종 소셜 미디어 소재에는 네이티브 오디오가 포함된 더 긴 클립이 목표일 수 있습니다. 이 선택을 호출 지점에 하드코딩하지 말고 애플리케이션 구성에 담아 두면 요청 코드를 수정하지 않고도 기능별로 변경할 수 있습니다. 실제로 재정의하려는 필드만 보내고 나머지는 엔드포인트가 기본값을 적용하도록 두세요.

사용 가능한 curl 요청

자격 증명과 페이로드를 확인하는 가장 빠른 방법은 curl 호출 한 번으로 작업을 제출하는 것입니다.

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "빗물에 젖은 거리를 떠내려가는 종이배, 따뜻한 가로등, 얕은 심도",
    "duration": 5,
    "native_audio": false
  }'

먼저 셸에서 HIAPI_BASE_URL과 HIAPI_API_KEY를 설정하세요. 여기의 길이와 오디오 값은 예시일 뿐입니다. 해당 모델 문서 범위 내의 값을 사용하세요.

즉시 응답 읽기

응답은 영상이 아니라 작업 객체입니다. job_id(또는 동등한 식별자)와 queued 또는 processing 같은 상태가 포함됩니다. 이 식별자를 저장하세요. 이후 모든 호출에서 사용할 핸들입니다. 응답이 오류 객체처럼 보인다면 재시도 전에 상태 코드와 메시지를 확인하세요. 형식이 잘못된 페이로드는 매번 동일하게 실패합니다.

제출 성공은 작업이 접수되었다는 것만 의미합니다. 첫 응답에서 영상 URL을 찾으려 하지 마세요. 작업이 완료되기 전에는 그곳에 나타나지 않습니다.

비동기 작업 수명 주기 처리

영상 생성에는 수 초에서 수 분이 걸리므로 HiAPI는 이를 작업으로 모델링합니다. 클라이언트는 한 번 제출한 뒤 작업이 종료 상태에 도달할 때까지 상태를 확인합니다.

상태

작업은 queued에서 processing을 거쳐 종료 상태인 completed 또는 failed로 이동합니다. 종료 상태만이 최종 상태이며, 그 사이의 어떤 상태든 계속 기다려야 함을 의미합니다.

과도하지 않은 폴링

저장한 작업 식별자로 상태 엔드포인트를 폴링하세요. 두 가지 규칙이 폴링을 건강하게 유지합니다.

• 폴링 사이에 기다리세요. 짧은 간격에서 시작해 점진적으로 백오프하거나, 일반적인 대기 시간보다 확실히 긴 고정 간격을 사용하세요. 상태 엔드포인트를 연속으로 두드리는 것은 아무런 이득이 없습니다.
• 상한을 설정하세요. 총 대기 시간과 총 시도 횟수를 제한하세요. 그때까지 작업이 완료되지 않았다면 무한 루프에 빠지지 말고 애플리케이션에 보고하세요.

웹 핸들러에서는 요청 스레드가 폴링 루프에서 블로킹되게 하지 마세요. 제출하고, 작업 식별자를 저장하고, 즉시 반환한 뒤 백그라운드 워커나 클라이언트가 수명 주기를 폴링하도록 하세요. 배치 시나리오에서는 sleep이 포함된 단순 루프로 충분합니다.

결과 읽기

작업이 completed로 보고되면 응답에 출력 참조가 포함됩니다. 애플리케이션이 다운로드하거나 스트리밍할 수 있는 영상 URL 또는 소재 핸들입니다. 실패 시에는 error 필드를 읽으세요. 보통 원인(잘못된 매개변수, 콘텐츠 거부, 내부 오류)을 명시합니다. 지원 요청이나 재시도에 근거가 되도록 작업 식별자와 실패 메시지를 함께 기록하세요. 출력 필드가 없다고 해서 성공으로 간주하지 말고 상태를 명시적으로 확인하세요.

Python에서의 동일한 요청

curl 흐름은 Python으로 그대로 매핑됩니다. 최소 클라이언트에는 제출, 폴링 루프, 그리고 잘못된 요청과 느린 작업을 구분할 수 있을 만큼의 오류 처리가 필요합니다.

import os, time
import requests

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

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

구현 참고 사항

raise_for_status()는 전송 및 HTTP 오류(인증, 페이로드 형식 오류)를 성공 응답 내부에 나타나는 작업 수준 실패와 구분합니다. failed 확인은 상태가 completed라고 가정하지 않고 error 필드를 명시적으로 읽습니다. 시도 횟수 상한은 무한 대기를 예측 가능한 예외로 바꿉니다.

프로덕션에서는 폴링을 일시적 네트워크 오류에 대한 재시도 정책으로 감싸고 단일 requests.Session을 재사용하세요. 많은 작업을 실행한다면 wait를 요청 경로가 아닌 워커 스레드로 옮기세요.

일반적인 실패 문제 해결

대부분의 통합 문제는 몇 가지 범주로 나눌 수 있습니다. 각 범주에는 구체적인 확인 방법이 있습니다.

인증 오류

401 또는 403은 키가 없거나, 만료되었거나, 형식이 잘못되었음을 의미합니다. Authorization 헤더가 존재하고, Bearer 방식을 사용하며, 환경 변수가 셸뿐 아니라 실행 환경에서 실제로 채워져 있는지 확인하세요.

페이로드 형식 오류

400은 보통 요청 본문이 스키마와 맞지 않음을 의미합니다. JSON이 파싱 가능한지, model이 정확히 flux-3-max/text-to-video인지, 요청에 Content-Type: application/json이 포함되었는지 검증하세요. 문자열을 수작업으로 구성하지 말고 JSON 라이브러리로 직렬화하세요.

잘못된 매개변수 값

문서 범위를 벗어난 길이, 알 수 없는 필드 이름, 오디오 스위치의 잘못된 타입은 모두 제출 시 거부를 일으킵니다. 보내기 전에 모델 문서의 매개변수에 따라 로컬에서 검증하세요.

너무 이른 폴링

제출 직후 반복적으로 폴링해도 작업이 더 빨리 완료되지는 않습니다. 백오프 또는 고정 간격을 사용하고, 작업 객체가 queued 상태를 지났는지 알려주도록 하세요.

처리되지 않은 작업 실패

failed에 도달한 작업이 반드시 요청에 버그가 있다는 뜻은 아닙니다. 콘텐츠 거부나 내부 오류일 수 있습니다. 오류 메시지를 읽고, 작업 식별자를 기록하고, 수정된 프롬프트로 재시도할지 보고할지 결정하세요.

제출 응답을 결과로 착각하기

코드가 제출 직후 영상 URL을 기대한다면 오류가 발생합니다. 첫 응답은 작업이며, 종료 상태만이 출력을 담습니다. 이 여섯 가지 확인이 갖춰지면 대부분의 통합 문제가 해결됩니다.