FLUX 3 API 사용 방법: 종합 개발자 가이드

빠른 답변

FLUX 3은 동기화 오디오가 포함된 텍스트-투-비디오 및 이미지-투-비디오 생성을 위한 Black Forest Labs의 멀티모달 비디오 모델입니다. CometAPI에서 프로덕션 모델 ID는 flux-3입니다. 검증된 비동기 워크플로는 작업 생성을 위해 POST /v1/videos, 폴링을 위해 GET /v1/videos/{task_id}, 완료된 MP4 다운로드를 위해 **GET /v1/videos/{task_id}/content**를 사용합니다.

가용성 업데이트(2026년 9월 24일 검증): Black Forest Labs는 FLUX 3 Video를 7월 Early Access 단계를 넘어 2026년 8월 4일에 BFL API 및 일부 파트너를 통해 텍스트-투-비디오와 이미지-투-비디오의 초기 릴리스를 일반 공개했습니다. CometAPI는 2026년 8월 13일에 Video API 형식으로 프로덕션 모델 ID flux-3를 추가했습니다. 가용성, 필드, 가격에 대해서는 BFL 릴리스 공지와 라이브 CometAPI 모델 페이지를 신뢰 가능한 기준으로 사용하세요.

FLUX 3 Early Access 이후 무엇이 달라졌나요?

핵심 변화는 운영상 가용성입니다. 초기 보도는 7월의 신청 기반 롤아웃에 초점이 있었지만, BFL의 8월 릴리스는 호출 가능한 비디오 엔드포인트, 공개 제약 사항, 프로덕션 가격을 도입했습니다. 이후 CometAPI가 flux-3를 통합 Video API 워크플로로 노출했습니다.

CometAPI의 이전 글인 FLUX 3 API: Availability, Early Access, Video & Dev는 출시 히스토리와 7월의 예비 평가에 여전히 유용합니다. 보다 광범위한 비교인 Best AI Video APIs in 2026은 시장 관점의 선택을 다룹니다. 본 가이드는 해당 주제를 간결히 유지하고, 실제 요청, 폴링, 프롬프트, 비용 제어, 프로덕션 처리에 집중합니다.

FLUX 3란 무엇인가?

FLUX 3는 비디오, 오디오, 이미지, 액션 관련 예측을 위한 BFL의 멀티모달 모델 제품군입니다. 현재 비디오 릴리스는 하나의 제공자-네이티브 엔드포인트를 통해 텍스트-투-비디오, 이미지-투-비디오, 비디오 연장을 지원합니다.

비디오 개발자를 위한 핵심 역량은 최대 20초 24 fps, HD 또는 Full HD 출력, 동기화 오디오, 립싱크를 포함한 다국어 음성, 한 번의 생성에서 다중 샷, 이미지-투-비디오 제어를 위한 최대 10개의 고정 키프레임입니다.

FLUX 3 API 사양

FLUX 3 비디오 품질은 어느 정도인가요?

BFL은 자사 전면 비교(all-vs-all) 인간 선호 평가에서 텍스트-투-비디오 Elo 점수 1135를 보고합니다. 같은 공개 비교에서, FLUX 3은 이미지-투-비디오 선호도에서 Seedance 2.0과 동률을 이루었고, 테스트된 다른 모델들보다 앞섰습니다.

이 결과는 포지셔닝에 유용한 자료이지만, 벤더가 수행한 인간 선호 평가이며 독립적인 프로덕션 벤치마크는 아닙니다. 게이트웨이 지연, 큐 신뢰성, 비용 일관성, 반복 생성 안정성을 측정하지 않으므로, 프로덕션 팀은 자체 프롬프트 세트로 여전히 평가를 수행해야 합니다.

FLUX 3 벤치마크 성능

출처: Black Forest Labs — FLUX 3 Video, Part 1: Generation.

FLUX 3 API 사용 전 준비 사항

• CometAPI 계정과 백엔드 환경 변수에 저장된 API 키
• 주제, 동작, 카메라 방향, 분위기, 필요한 오디오나 대사를 정의하는 프롬프트
• 비디오 생성이 비동기이므로 내구성 있는 작업 처리 경로
• 반복 테스트를 위한 충분한 크레딧; 요금은 생성된 길이와 해상도에 따라 청구

API 키는 CometAPI API 대시보드에서 생성하세요. 프런트엔드 JavaScript, 모바일 번들, 공개 저장소, 스크린샷에 키를 두지 마세요.

FLUX 3 모델 ID 및 엔드포인트

CometAPI로 FLUX 3 API 사용하는 방법

1단계: API 키 설정

macOS 또는 Linux:

export COMETAPI_KEY="your_api_key"

Windows PowerShell:

$env:COMETAPI_KEY="your_api_key"

2단계: FLUX 3 비디오 생성

현재 FLUX 3 퀵스타트는 model, prompt, seconds, size를 포함하는 multipart 요청을 사용합니다. 이 예시는 5초 길이의 720p 클립을 요청합니다:

curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F "model=flux-3" \
  -F "prompt=A paper boat glides across a still pond in soft morning light" \
  -F "seconds=5" \
  -F "size=1280x720"

이 요청은 작업을 시작합니다. 같은 HTTP 응답에서 완료된 MP4를 받는 방식으로 애플리케이션을 설계하지 마세요.

3단계: 작업 ID 저장

생성 요청이 성공하면 식별자를 즉시 영속화하세요:

{
  "id": "video_task_id",
  "status": "queued"
}

폴링을 시작하기 전에 사용자 또는 작업 레코드 옆에 작업 ID를 저장하세요. 프로세스가 재시작되더라도 이미 청구된 생성을 잃어버리지 않도록 하세요.

4단계: 비디오 상태 폴링

curl https://api.cometapi.com/v1/videos/{task_id} \
  -H "Authorization: Bearer $COMETAPI_KEY"

초기 폴링 간격은 10초처럼 보수적으로 시작하세요. completed, succeeded, success는 최종 성공 상태로, failed, failure, cancelled, canceled는 최종 실패 상태로 간주하세요.

5단계: MP4 다운로드

curl https://api.cometapi.com/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  --output flux3_output.mp4

완료 후에는 임시 제공자 URL을 영구 자산으로 삼지 말고, 파일을 자체 오브젝트 스토리지 또는 미디어 파이프라인에 복사하세요.

FLUX 3 비디오 생성을 위한 전체 Python 워크플로

다음 예시는 작업을 생성하고, ID를 저장하고, 완료될 때까지 폴링하며, 실패 상태를 점검하고, MP4 시그니처를 검증한 다음 출력을 디스크에 기록합니다.

import os
import time
from pathlib import Path

import requests

api_key = os.environ["COMETAPI_KEY"]
base_url = "https://api.cometapi.com"
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.post(
    f"{base_url}/v1/videos",
    headers=headers,
    files={
        "model": (None, "flux-3"),
        "prompt": (
            None,
            "A product bottle rotates slowly on wet black stone, "
            "soft rim lighting, macro lens, realistic reflections.",
        ),
        "seconds": (None, "5"),
        "size": (None, "1280x720"),
    },
    timeout=120,
)
response.raise_for_status()

task = response.json()
data = task.get("data") or {}
task_id = (
    task.get("id")
    or task.get("task_id")
    or data.get("id")
    or data.get("task_id")
)
if not task_id:
    raise RuntimeError(f"Create response has no task ID: {task}")

while True:
    response = requests.get(
        f"{base_url}/v1/videos/{task_id}",
        headers=headers,
        timeout=60,
    )
    response.raise_for_status()
    task = response.json()
    data = task.get("data") or {}
    status = str(task.get("status") or data.get("status") or "").lower()
    progress = task.get("progress") or data.get("progress") or "unknown"
    print(f"Status: {status or 'unknown'}; progress: {progress}")

    if status in {"failed", "failure", "cancelled", "canceled"}:
        raise RuntimeError(f"Video generation failed: {task}")
    if status in {"completed", "succeeded", "success"} or progress == "100%":
        break
    time.sleep(10)

response = requests.get(
    f"{base_url}/v1/videos/{task_id}/content",
    headers=headers,
    timeout=300,
)
response.raise_for_status()
video = response.content

if len(video) < 12 or video[4:8] != b"ftyp":
    raise RuntimeError("Content response is not a non-empty MP4 file")

output_dir = Path("output")
output_dir.mkdir(parents=True, exist_ok=True)
output_path = output_dir / f"{task_id}.mp4"
output_path.write_bytes(video)
print(f"Saved: {output_path} ({len(video)} bytes)")

이미지-투-비디오 및 키프레임 사용 방법

CometAPI FLUX 3 페이지는 이미지-투-비디오를 지원 기능로 기재합니다. 현재 공개 샘플은 텍스트-투-비디오를 보여주므로, 다른 모델에서 참조 이미지를 사용하는 필드를 그대로 복사해도 동작한다고 가정하지 말고 라이브 게이트웨이 문서를 먼저 확인하세요.

BFL의 네이티브 API는 명확합니다: 이미지-투-비디오는 mode i2v 및 keyframes 필드를 사용합니다. 이미지 한 장은 시작 프레임을 고정하고, 두 장은 시작과 끝을 고정하며, 최대 열 장의 타이밍 있는 이미지로 연속 클립을 스토리보딩할 수 있습니다.

BFL-네이티브 키프레임 예시

curl -X POST https://api.bfl.ai/v1/flux-3-video \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2v",
    "prompt": "They sprint through the lantern-lit alley as the camera tracks behind them.",
    "keyframes": [
      [0, "data:image/png;base64,<first-frame>"],
      [8, "data:image/png;base64,<last-frame>"]
    ],
    "duration": 8
  }'

제공자-네이티브와 게이트웨이 파라미터는 별도의 어댑터로 유지하세요. BFL은 mode, keyframes, start_video, resolution, draft 같은 필드를 사용하며, CometAPI의 검증된 샘플은 model, prompt, seconds, size를 사용합니다.

FLUX 3 API 파라미터 해설

더 나은 FLUX 3 프롬프트 작성법

BFL의 비디오 프롬프트 가이드는 주제와 동작, 카메라, 장면과 분위기, 모션 품질, 연속성에 대한 명확한 지시를 권장합니다. 오디오 주도 장면에서는 대사, 보이스, 효과음, 앰비언스를 명시하세요.

실용적인 프롬프트 구조

Subject + Environment + Action + Camera + Lighting
+ Dialogue/Voice + Sound Effects + Ambience + Constraints

시네마틱 프롬프트

A lone cyclist rides through a rain-soaked neon street at midnight.
The camera begins low beside the rear wheel, then rises into a smooth tracking shot.
Reflections stretch across wet asphalt under moving cyan and magenta light.
Audio: steady rainfall, chain noise, distant traffic, no music, no dialogue.
Keep the same rider, bicycle, jacket, and weather throughout the shot.

제품 영상 프롬프트

A premium stainless-steel espresso machine stands on a dark stone counter.
Begin with a macro close-up of water droplets on the metal housing.
Orbit clockwise as the machine brews; steam catches warm side light.
Finish on a clean three-quarter hero angle with the cup in the foreground.
Audio: pump vibration, steam hiss, ceramic contact, quiet cafe ambience.
Do not change the product shape, logo placement, material, or color.

대사 및 네이티브 오디오 프롬프트

A young chef works alone in a compact Tokyo ramen shop at night.
Start close on boiling broth, then pull back as the chef sets down a bowl.
Warm tungsten lighting, natural reflections, documentary handheld motion.
The chef quietly says in Japanese: 「お待たせしました。」
Audio: bubbling broth, soft rain outside, distant street traffic.
No subtitles and no background music.

“make a cinematic ramen shop video” 같은 프롬프트는 모션, 프레이밍, 사운드, 연속성을 명시하지 않습니다. 명확한 지시는 보다 테스트 가능한 프로덕션 브리프를 제공합니다.

FLUX 3 API 가격

BFL 가격은 워크플로별로 다릅니다: 전체 텍스트-투-비디오와 이미지-투-비디오 렌더는 HD $0.17/s, FHD $0.29/s이며, HD Draft Mode는 $0.06/s입니다. 비디오 연장은 HD $0.43/s, FHD $0.54/s이며, HD 드래프트는 $0.12/s입니다. CometAPI는 현재 flux-3를 720p $0.136/s, 1080p $0.232/s로 기재하고 있습니다. 대량 배치 전에 라이브 가격을 확인하세요.

마지막 두 열 읽는 방법: 값은 HD/720p가 먼저, FHD/1080p가 두 번째로 표시됩니다.

반복 비용을 줄이는 방법

• 선택된 프롬프트를 1080p로 옮기기 전에 720p로 프로토타이핑하세요.
• 구성, 모션, 프롬프트 해석을 검증하기 위해 5초 클립을 사용하세요.
• 한 번에 하나의 주요 프롬프트 변수를 변경하세요.
• BFL 네이티브 API 사용 시, 전체 품질 렌더 전 Draft Mode로 테스트하세요.
• 성공한 프롬프트와 참조 결정을 애플리케이션 메타데이터에 저장하세요.

FLUX 3 vs Wan 3.0 vs Seedance 2.5

FLUX 3, Wan 3.0, Seedance 2.5는 단일 만능 승자를 찾기보다 워크플로 기준으로 비교하세요. 권위 있는 사양 링크는 아래 표의 헤더에 남아 있습니다.

가격 참고: 시작 가격은 품질이나 해상도가 동일한 비교가 아닙니다. 예산 책정 시 각 라이브 모델 페이지의 해상도별 표를 사용하세요.

어떤 비디오 API를 선택해야 하나요?

• FLUX 3: 리얼리스틱 모션, 동기화 사운드, 멀티샷 로직, 네이티브 키프레임 또는 연장이 필요할 때
• Wan 3.0: 많은 입력 타입으로 시작하고 30초 생성 윈도우가 중요한 워크플로
• Seedance 2.5: 더 길고 참조가 많은 스토리텔링, 정체성/제품/스타일 제어가 중요한 경우

FLUX 3 API 프로덕션 베스트 프랙티스

비동기 작업을 내구성 있는 상태로 보존

제출 직후 작업 ID를 저장하세요. 서버 재시작이나 워커 재시도로 인해 애플리케이션이 원래 작업을 잃어 유저가 다시 비용을 지불하지 않도록 하세요.

과도한 폴링을 피하기

라이브 문서의 별도 권장 사항이 없다면 약 10초 간격으로 시작하세요. 초 단위 폴링은 요청 부하만 늘리고 체감 경험을 크게 개선하지 못합니다.

다운로드 검증

자산을 완료로 표시하기 전에 콘텐츠 길이와 MP4 시그니처를 확인하세요. 성공적인 HTTP 응답이 항상 유효한 비디오 본문을 보장하지는 않습니다.

네이티브와 게이트웨이 스키마 분리

BFL-네이티브와 CometAPI 요청을 별도 어댑터로 유지하세요. 이렇게 하면 mode, keyframes, start_video 같은 네이티브 필드가 model, prompt, seconds, size를 기대하는 게이트웨이 호출로 유입되는 것을 방지합니다.

전체 실패 컨텍스트 저장

HTTP 상태, 응답 본문, 작업 ID, 모델 ID, 프롬프트 버전, 크기, 길이, 내부 작업 ID를 기록하세요. API 키는 마스킹하세요.

출시 전 소규모 평가 세트 사용

카메라 모션, 인물, 제품, 타이포그래피, 대사, 고모션 장면, 필요한 종횡비를 아우르는 10–30개의 대표 프롬프트를 구축하세요. 모델이나 통합 버전이 변경될 때 동일 세트를 실행하고, 비디오 생성이 확률적이므로 중요한 프롬프트는 반복하세요.

FAQ

CometAPI에서 FLUX 3 모델 ID는 무엇인가요?

현재 모델 ID는 flux-3입니다.

FLUX 3는 어떤 CometAPI 엔드포인트를 사용하나요?

검증된 Video API 워크플로는 POST /v1/videos 이후 GET /v1/videos/{task_id}, GET /v1/videos/{task_id}/content를 사용합니다.

FLUX 3는 동기식인가요?

아니요. 비동기 작업으로 다루세요: 제출, 작업 ID 저장, 폴링, 다운로드.

FLUX 3는 얼마나 길게 생성할 수 있나요?

BFL 문서에 따르면 T2V/I2V는 5–20초, 연장은 5–15초입니다.

FLUX 3는 오디오를 생성하나요?

예. BFL 네이티브 API는 기본적으로 동기화 오디오 활성화를 문서화합니다.

FLUX 3는 이미지-투-비디오를 지원하나요?

예. CometAPI는 이미지-투-비디오 지원을 기재하며, BFL 네이티브 API는 i2v 모드와 키프레임으로 구현합니다.

BFL 키프레임을 CometAPI에서 그대로 사용할 수 있나요?

그렇다고 가정하지 마세요. 요청 스키마가 다릅니다. 게이트웨이 참조-이미지 워크플로를 배포하기 전에 최신 CometAPI 퀵스타트를 확인하세요.

CometAPI에서 5초 FLUX 3 비디오 비용은 얼마나 되나요?

현재 CometAPI 요율 기준으로 5초는 720p $0.68, 1080p $1.16입니다. 라이브 참조 링크는 위의 통합 가격 표를 참조하세요.

FLUX 3가 Wan 3.0이나 Seedance 2.5보다 낫나요?

워크플로에 따라 다릅니다. FLUX 3는 모션 일관성이 있는 오디오비주얼 샷과 BFL-네이티브 키프레임 또는 연장 제어에 강하며, Wan 3.0은 입력 폭에 중점을 둡니다. Seedance 2.5는 더 길고 참조 중심의 스토리텔링에 강점이 있습니다.

결론

FLUX 3는 CometAPI에서 작동하는 비동기 Video API 경로를 갖추었고, BFL 네이티브 문서는 키프레임, 연장, 오디오, Draft Mode에 대한 더 깊은 제어를 제공합니다.

안전한 통합 경로는 간단합니다: 짧은 720p 텍스트-투-비디오 요청으로 시작하고, 작업 ID를 저장하고, 보수적으로 폴링하며, MP4를 다운로드 및 검증한 다음 프롬프트 템플릿, 스토리지, 재시도 로직, 반복 가능한 평가 세트를 추가하세요. 네이티브와 게이트웨이 스키마를 분리하고, 필드나 가격을 하드코딩하기 전에 라이브 모델 페이지를 확인하세요.