Skip to main content
FLUX 3 Video에 대한 API 레퍼런스입니다. FLUX 3 Video는 Black Forest Labs의 비디오 생성 모델로, 텍스트 프롬프트를 동기화된 오디오가 포함된 짧은 클립으로 변환합니다.

빠른 시작

Comfy 워크스페이스에서 키를 생성하고 COMFY_API_KEY로 내보내세요. Python 및 TypeScript 스니펫은 Comfy SDK(pip install comfy-sdk, npm install @comfyorg/sdk)를 사용하며, cURL 스니펫은 동일한 호출을 raw HTTP로 수행한 것입니다. 모델 ID: bfl/flux-3-video 엔드포인트: POST https://api.comfy.org/v2/models/bfl/flux-3-video

스키마

입력

string
기본값:"\"auto\""
출력 화면 비율: auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 또는 9:16입니다. auto는 BFL이 프롬프트와 참조 자료를 바탕으로 선택하도록 합니다.
boolean
기본값:"false"
초안 모드: 결과에 draft_cache 다운로드 URL이 포함되는 빠른 미리보기를 생성합니다. 해당 번들을 mode draft_enhance와 함께 다시 전송하면 같은 생성 작업을 최고 품질 버전으로 렌더링합니다.
string
draft_enhance 전용입니다. 이전 초안 생성에서 만들어진 암호화된 초안 캐시 번들로, base64로 인코딩된 다운로드 번들이나 아직 유효한 http(s) URL 형태입니다. 원본 입력은 번들에 포함되어 있습니다.
integer | string
기본값:"\"auto\""
비디오 재생 시간(초)으로, 5에서 20 사이의 정수 초를 사용하거나 콘텐츠에 맞게 auto를 사용합니다.범위: 5 ~ 20
boolean
기본값:"true"
비디오와 함께 동기화된 오디오를 생성합니다.
string | number | string[] | string[] | number | string[][]
i2v 전용입니다. 비디오의 프레임이 될 이미지로, 각각 http(s) URL 또는 base64이며 총 1~10개입니다. 단일 이미지, 이미지 목록(하나는 비디오를 시작하고, 둘은 시작과 끝을 담당하며, 그보다 많으면 균등하게 배치되고 재생 시간을 지정해야 함), 또는 시간 순서대로 정렬된 [초, 이미지] 타임스탬프 쌍(예: [[0, ”…”], [3.5, ”…”]])을 받습니다. 쌍은 두 요소 배열로, 먼저 초 단위 숫자가 오고 그다음 이미지가 옵니다.
string
필수
생성 모드: t2v(텍스트 기반 비디오 생성), i2v(이미지 이어가기), v2v(비디오 이어가기) 또는 draft_enhance(이전 초안의 최고 품질 렌더링)입니다. text-to-video처럼 풀어 쓴 별칭도 허용됩니다.
string
비디오를 설명하는 자유 형식 프롬프트입니다. draft_enhance를 제외한 모든 모드에서 필수입니다.
string
비디오 해상도 등급: hd 또는 비디오 업샘플러로 마무리되는 더 높은 해상도의 결과를 위한 fhd입니다. t2v, i2v, v2v에서는 기본값이 hd이고 draft_enhance에서는 fhd입니다. 정확한 크기는 화면 비율에 따라 달라집니다.가능한 값: hd, fhd
integer
기본값:"2"
입력 및 출력 유해성 검열에 대한 허용치 수준이며 0이 가장 엄격합니다. 성적 콘텐츠는 요청한 허용치와 관계없이 레벨 3으로, 혐오 콘텐츠는 레벨 2로 제한되며, 조건화 미디어가 포함된 요청은 레벨 2로 제한됩니다.범위: 0 ~ 4
string
v2v 전용입니다. 계속할 비디오로, http(s) URL 또는 base64 MP4입니다. 생성된 클립은 해당 비디오의 마지막 프레임부터 이어집니다.
string
기본값:"\"latest\""
엔드포인트 버전입니다. latest는 현재 릴리스를 제공하며, 날짜가 지정된 고정 가능 릴리스 태그는 게시되는 대로 추가됩니다.
Router가 GET /v2/models/bfl/flux-3-video/openapi.json에서 제공하는 스키마에서 생성되었으며, 이는 요청이 공급자에게 도달하기 전에 호출을 검증하는 데 사용하는 것과 동일한 문서입니다.

출력

number
공급자가 보고한 크레딧 단위 비용으로, 작업이 Ready 상태가 되면 채워집니다.형식: float
string
필수
BFL 작업 식별자입니다.
number
BFL이 보고하는 선택적 생성 진행률입니다.범위: 0 ~ 1형식: float
object
필수
완료된 생성 결과입니다. 두 URL 리프 중 정확히 하나만 채워집니다. 기본 모드에서는 sample, draft: true 모드에서는 draft_cache입니다.
number
공급자가 보고한 작업 비용입니다. 이는 Comfy 청구 금액이 아니라 BFL의 수치입니다.형식: double
string (uri)
draft: true 모드에서 sample 대신 반환되는 서명된 URL이며, sample과 같은 방식으로 Comfy 스토리지에 다시 호스팅됩니다. 일반적으로 최대 24시간 동안 유효한 Comfy 호스팅 URL이고, 재호스팅을 수행할 수 없었을 때는 BFL 자체의 약 2시간짜리 전달 URL입니다.형식: uri
string (uri)
생성된 MP4의 서명된 URL입니다. Router는 자산을 Comfy 스토리지에 다시 호스팅하고 이 필드를 다시 작성하므로, 일반적으로 최대 24시간 동안 유효한 Comfy 호스팅 URL입니다. 발급 시점에 24시간으로 서명되고 23시간짜리 메모에서 재생되므로, 나중에 폴링하면 남은 시간이 1시간도 안 되는 URL을 돌려받을 수 있습니다. 재호스팅을 수행할 수 없었던 리프는 대신 BFL 자체의 약 2시간짜리 전달 URL을 유지합니다. draft: true 모드에서는 없습니다.형식: uri
string
필수
작업 상태: Pending, Reasoning, Generating, Ready, Request Moderated, Content Moderated, Error 또는 Task not found입니다. 대소문자를 구분하지 않고 비교하세요. Router는 BFL의 표기를 그대로 전달합니다.

예시

입력

출력

result.sample은 일반적으로 Comfy에서 호스팅하는 서명된 URL이며, 생성 시점부터 최대 24시간 동안 유효합니다. 다시 재생하면 더 오래된 URL이 반환될 수 있고, 재호스팅할 수 없는 asset은 수명이 더 짧은 공급자 URL을 그대로 유지합니다. 링크를 저장해 두기보다 MP4 파일을 promptly 다운로드하세요. draft: true인 경우에는 result.sample을 기대하지 말고 result.draft_cache를 읽으세요.

배포 전 확인

SDK는 Idempotency-Key를 생성하고 자동 재시도에서 재사용합니다. 수동 재시도 시에는 원래 키를 재사용하세요. Router는 연결을 최대 10분간 유지할 수 있습니다. 요청이 실패하면 Router는 이유를 설명하는 X-Comfy-Error-Type 응답 헤더를 보냅니다. 422는 Router가 프로바이더를 호출하기 전에 입력을 거부했음을 의미합니다. 생성된 에셋은 결과 URL이 만료될 수 있으므로 즉시 다운로드하세요.

헤더

인증, 멱등성, 요청 ID, 오류 분류, 재시도 간격, 지출 한도.

Router API 사용

모델 검색, 유효성 검사 오류, 재시도, 과금.

제한 사항

Router가 현재 지원하지 않는 기능과 대체 방법.