FLUX 3 비디오를 비동기 HTTP API로 처리하기: 요청, 폴링, 키프레임 및 실제 가격 책정

curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F "model=flux-3" \
...

{
  "id": "video_task_id",
  "status": "queued"
...```

이 ID를 폴링하기 전에 자신의 작업 기록이나 사용자 레코드 옆에 저장하세요. 워커 재시작은 절대 사용자에게 청구되는 2초의 생성을 비용으로 전가해서는 안 됩니다. 그런 다음 폴링을 수행합니다:

10초 간격은 합리적인 시작 간격입니다. 제가 본 최종 성공 상태는 `completed`, `succeeded`, `success`였습니다. 최종 실패 상태는 `failed`, `failure`, `cancelled`, `canceled`였습니다.

제공자 URL을 영구 자산으로 고정하기보다는, 다운로드한 후 파일을 자신의 버킷으로 옮기세요:

### 완전한 Python 작업 실행기 (job runner)

이 코드는 생성, 저장, 폴링, 실패 상태 확인, MP4 서명 검증 및 디스크 쓰기를 수행합니다.

## Image-to-video와 keyframes: 하나의 스키마가 아닌 두 가지

I2V는 게이트웨이를 통해 지원되는 것으로 명시되어 있지만, 현재 공개 샘플은 텍스트-투-비디오(text-to-video)만을 시연합니다. 다른 모델의 문서를 복사한 참조 이미지 필드가 변경 없이 수용될 것이라고 가정하지 마세요. 해당 경로를 배포하기 전에 라이브 게이트웨이 레퍼런스를 확인하세요.

BFL의 네이티브 API는 명확합니다: I2V는 [mode `i2v`와 `keyframes` 필드](https://docs.bfl.ai/flux_3/flux3_overview)를 사용합니다. 이미지 하나는 시작 프레임을 고정하고, 두 개는 시작과 끝을 고정하며, 최대 열 개의 시간 지정 이미지는 연속적인 클립의 스토리보드를 구성합니다.

네이티브(native) 및 게이트웨이(gateway) 매개변수는 별도의 어댑터에 보관하세요. 이 둘을 혼합하는 것이 제가 검토 과정에서 가장 흔하게 보는 실패 사례입니다. 네이티브 필드는 `mode`, `keyframes`, `start_video`, `resolution`, `draft`이며, 검증된 게이트웨이 샘플은 `model`, `prompt`, `seconds`, `size`를 사용합니다.

### 매개변수 참조 (Parameter reference)

| 매개변수 | API | 제어 대상 | 가이드라인 |
| :--- | :--- | :--- |
| `model` | gateway | 모델 선택 | `flux-3` |
| ... | 

## 프롬프팅: 분위기(mood)가 아닌 샷 리스트 작성하기 (write a shot list, not a mood)

BFL의 [비디오 프롬프팅 가이드](https://docs.bfl.ai/guides/prompting_video_overview)는 주제와 동작, 카메라, 장면 및 분위기, 움직임 품질, 연속성에 대한 명확한 지시를 요청합니다. 오디오 기반 장면에는 대화(dialogue), 목소리(voice), 음향 효과(sound effects), 그리고 주변 환경 소음(ambience)을 구체적으로 설명해야 합니다.

제가 재사용하는 구조는 다음과 같습니다:

시네마틱 (Cinematic):

제품 (Product):

네이티브 오디오가 포함된 대화 (Dialogue with native audio):

워크플로우별 BFL 가격. T2V 및 I2V 전체 렌더링은 **HD 기준 초당 $0.17**과 **FHD 기준 초당 $0.29**이며, HD 드래프트 모드는 **초당 $0.06**입니다. 비디오 연속 생성(Video continuation)은 **HD 기준 초당 $0.43**과 **FHD 기준 초당 $0.54**이며, HD 드래프트는 **초당 $0.12**입니다. 게이트웨이에서는 `flux-3`를 **720p 기준 초당 $0.136** 및 **1080p 기준 초당 $0.232**로 나열합니다. 대규모 배치 작업 전에 반드시 실시간 가격을 재확인하세요.

| 워크플로우 | HD/720p | FHD/1080p | 드래프트 | 5초 전체 | 10초 전체 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| BFL T2V | $0.17/s | $0.29/s | $0.06/s (HD) | $0.85 / $1.45 | $1.70 / $2.90 |
| ... | 
실제 두 번째 열에서 첫 번째 수치는 HD/720p, 두 번째 수치는 FHD/1080p입니다.

### 반복 작업 비용 절감 (Cutting iteration cost)

-   720p로 프로토타입을 만든 후, 선택된 프롬프트만 1080p로 승격(promote)하세요.
-   5초 클립만으로도 구성(composition), 움직임(motion), 프롬프트 해석(prompt interpretation)을 검증하기에 충분합니다.
-   작업 실행당 주요 변수를 하나씩 변경하세요.
-   네이티브 API에서는 전체 품질 렌더링 전에 드래프트 모드(Draft Mode)를 사용하세요.
-   최종 결과물로 선택된 프롬프트와 참고 자료 결정 사항을 자체 메타데이터에 저장하세요.

## FLUX 3 vs Wan 3.0 vs Seedance 2.5

리더보드가 아닌 워크플로우별로 선택하세요. 이 지점에서 통합 엔드포인트(unified endpoint)가 가치를 발휘합니다: `flux-3`, Wan 3.0, 그리고 Seedance 2.5를 하나의 작업 파이프라인 뒤에 유지하는 것(저는 정확히 이를 위해 CometAPI를 통해 라우팅합니다)은 모델 교체가 재작성(rewrite)이 아닌 설정 변경(config change)임을 의미합니다.

| 차원 (Dimension) | FLUX 3 | Wan 3.0 | Seedance 2.5 |
| :--- | :--- | :--- |
| 최대 클립 길이 (Max clip) | T2V/I2V 기준 최대 20초 | 최대 30초 | 최대 30초 |
| ...
시작 가격은 해상도별로 동일하게 비교할 수 없으므로, 각 라이브 모델 페이지의 해상도표에서 예산을 책정하세요.

## 제작 참고 사항 (Production notes)

**비동기 작업 유지(Persist async jobs).** 제출 시점에 작업 ID를 저장하세요. 워커 재시도는 작업을 재청구해서는 안 됩니다.

**너무 자주 폴링하지 마세요(Do not poll tightly).** 라이브 문서에 다른 지침이 없다면 약 10초 간격으로 하세요. 1초 간격의 폴링은 체감 지연 시간(perceived latency)을 개선하지 못하면서 부하만 추가합니다.

**다운로드 검증(Validate the download).** 에셋 준비 완료로 표시하기 전에 길이와 MP4 `ftyp` 시그니처를 확인하세요. 200 응답 코드가 비디오를 받았다는 것을 증명하지는 않습니다.

**네이티브 스키마와 게이트웨이 스키마 분리.** 별도의 어댑터를 사용하면 네이티브 전용 필드가 게이트웨이 호출로 유출되는 것을 방지할 수 있습니다.

**전체 실패 컨텍스트 기록.** HTTP 상태, 응답 본문, 작업 ID(task ID), 모델 ID(model ID), 프롬프트 버전, 크기(size), 지속 시간(duration), 내부 작업 ID(internal job ID)를 기록해야 합니다. 핵심 키는 마스킹 처리합니다.

**고정 평가 세트 실행.** 카메라 움직임, 사람, 제품, 타이포그래피, 대화, 고속 움직임 장면 및 필요한 종횡비(aspect ratio)를 포함하는 10개에서 30개의 프롬프트를 다룹니다. 모든 모델 또는 통합 변경 시 재실행하고, 생성 과정이 확률적(stochastic)이기 때문에 중요한 프롬프트는 반복합니다.

## 알아두면 좋은 벤더 지표

BFL은 전체 대(all-vs-all) 인간 선호도 평가에서 텍스트-투-비디오(text-to-video) Elo 점수 **1135**를 보고했으며, 이미지-투-비디오(image-to-video) 선호도에서는 Seedance 2.0과 동률을 이루었습니다. 유용한 포지셔닝이지만, 벤더가 실행하는 선호도 테스트는 대기열 신뢰성, 게이트웨이 지연 시간, 비용 일관성 또는 세대 간 안정성을 측정할 뿐, 인식된 출력 품질을 측정하지는 않습니다. 귀하 자신의 프롬프트 세트만이 생산 환경을 예측하는 유일한 벤치마크입니다.

## FAQ

**모델 ID는 무엇인가요?** `flux-3`입니다.

**엔드포인트(Endpoints)는 무엇인가요?** `POST /v1/videos`를 사용하고, 이후 `GET /v1/videos/{task_id}` 및 `GET /v1/videos/{task_id}/content`를 사용합니다.

**동기식(Synchronous)인가요?** 아닙니다. 제출(Submit), 영속화(persist), 폴링(poll), 다운로드 순서로 진행됩니다.

**최대 지속 시간은 얼마인가요?** T2V/I2V의 경우 5초에서 20초, 연속 재생(continuation)의 경우 5초에서 15초입니다.

**오디오는 가능한가요?** 네, 기본적으로 내장된 API에서 동기화되어 활성화됩니다.

**BFL 키프레임을 게이트웨이를 통해 변경 없이 보낼 수 있나요?** 그렇게 가정하지 마십시오. 스키마가 다릅니다. 먼저 현재의 퀵스타트 가이드를 확인하십시오.

**5초 분량의 비용은 얼마인가요?** 현재 게이트웨이 요율 기준으로 720p에서 $0.68, 또는 1080p에서 $1.16입니다.

## 제가 가장 먼저 구현할 것들

짧은 720p 텍스트-투-비디오 요청, 영속적인 작업 ID(task ID), 보수적인 폴링(polling), 서명 검증을 통한 다운로드, 그 다음 프롬프트 템플릿, 객체 스토리지, 재시도 로직 및 반복 가능한 평가 세트를 구현할 것입니다. I2V 필드 매핑이 라이브 레퍼런스와 확인되면 키프레임과 연속 재생 기능을 추가하겠습니다.

원문 출처: [cometapi.com](https://www.cometapi.com/how-to-use-flux-3-api/?utm_source=dev.to&utm_medium=social&utm_campaign=content&utm_content=how-to-use-flux-3-api)