FLUX 3 Image API 가이드: 4K와 다중 레퍼런스 편집

FLUX 3 Image를 실제로 연동할 수 있는 경로가 열렸다. Black Forest Labs가 소유한 Replicate 모델과 파트너 엔드포인트를 통해 4K 출력과 최대 10개 레퍼런스를 활용한 편집이 가능하다. 다만 BFL의 공식 문서는 여전히 FLUX 3 Video를 중심으로 구성돼 있고, 이미지 API는 제공업체마다 요청 형식과 제한, 과금 방식이 제각각이다.

FLUX 3 Image API는 실제로 사용할 수 있나?

결론부터 말하면 FLUX 3 Image API는 사용할 수 있다. 다만 ‘공식’이라는 표현은 어디까지를 의미하는지 구분해야 한다. 가장 확실한 근거는 Black Forest Labs가 소유한 Replicate의 black-forest-labs/flux-3-image 모델 페이지다. 텍스트 기반 이미지 생성 요청을 받을 뿐 아니라 이미지를 입력하면 편집 모드로 전환하고, 해상도 옵션으로 4k도 제공한다.

BFL의 FLUX 3 도움말 문서는 비디오 모델만 설명한다. 이미지 편집 기능은 별도로 확인되는 BFL 소유 Replicate 모델과 파트너 엔드포인트를 통해 검증된다.

엔드포인트가 등장하기 전, Reddit 사용자 u/rerri는 API 우선 출시를 예상했다.

“API 전용 Flux 3 Image가 먼저 출시돼도 놀랍지 않을 것 같다.” — r/StableDiffusion의 u/rerri

실제 출시 방식은 이 예상과 맞아떨어진다. 다만 API를 이용할 수 있다는 사실이 오픈 웨이트 공개를 의미하는 것은 아니다.

4K와 다중 레퍼런스 편집을 실제 작업에 적용하는 법

FLUX 3 Image는 4k 출력 옵션을 제공하고 최대 10개의 레퍼런스 이미지를 받을 수 있다. 그렇다고 모든 결과가 인물의 정체성이나 제품 디테일, 작은 글자까지 완벽하게 보존한다는 뜻은 아니다. 각 제공업체 페이지에는 제어 항목과 예시가 공개돼 있지만, 독립적인 품질 점수는 제시되지 않는다.

BFL 소유 모델인 Replicate README에는 768sq, 1k, 1.5k, 2k, 4k가 해상도 옵션으로 정리돼 있다. 레퍼런스 파일은 JPEG, PNG, GIF, WebP를 사용할 수 있으며, 최소 크기는 256×256픽셀이고 최대 크기는 16메가픽셀이다. aspect_ratio: auto를 사용하면 첫 번째 레퍼런스가 편집 결과의 화면 비율을 결정한다.

fal의 편집 스키마는 비슷하지만 완전히 같지는 않다. URL 또는 데이터 URI 형식의 입력을 1~10개까지 받고, 각 입력은 4메가픽셀로 제한된다. 512sq부터 4k까지 지원하며 4K 렌더링에는 몇 분이 걸릴 수 있다고 안내한다. 레퍼런스 순서도 의미가 있다. image_urls의 첫 번째 항목이 “image 1”이다.

다중 레퍼런스 편집에서는 각 입력 이미지에 역할을 하나씩 부여하는 편이 좋다. 기본 구도, 인물이나 사물의 정체성, 제품, 스타일처럼 용도를 나누는 방식이다. fal도 요청 하나당 하나의 편집만 수행할 것을 권장한다. 예를 들어 “image 1을 기본 이미지로 사용하고, image 2의 제품으로 병만 교체하되 손, 카메라 앵글, 조명, 배경은 유지하라”는 요청이 옷과 타이포그래피, 장소까지 한 번에 바꾸라는 요청보다 결과를 검토하기 쉽다.

실전용 큐 기반 API 워크플로

FLUX 3 Image를 운영 환경에 넣을 때는 생성을 비동기 작업으로 다루는 것이 안전하다. 애플리케이션은 안정적인 입력 URL을 준비하고, 범위를 좁힌 요청을 제출한 뒤, 프로바이더가 반환한 요청 ID를 저장하고, 백오프로 상태를 확인해야 한다. 작업이 끝나면 결과 파일을 자체 스토리지로 복사한다.

아래 예시는 fal이 문서에 공개한 엔드포인트 식별자와 요청 필드를 사용한다. 이 리뷰 과정에서 실제로 실행한 요청이 아니라 연동을 위한 템플릿이다.

import os
import time
import requests

ENDPOINT = "https://queue.fal.run/blackforestlabs/flux-3/edit-image"
headers = {
    "Authorization": f"Key {os.environ['FAL_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "prompt": (
        "Use image 1 as the base. Replace only its package with the product "
        "from image 2. Preserve the hands, camera angle, shadows, and background."
    ),
    "image_urls": [
        "https://cdn.example.com/base.jpg",
        "https://cdn.example.com/product.png",
    ],
    "resolution": "1k",
    "aspect_ratio": "auto",
    "output_format": "png",
    "safety_tolerance": 2,
}

submitted = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)
submitted.raise_for_status()
job = submitted.json()

status_url = job["status_url"]
response_url = job["response_url"]
while True:
    status = requests.get(status_url, headers=headers, timeout=30)
    status.raise_for_status()
    state = status.json().get("status")
    if state == "COMPLETED":
        break
    if state in {"FAILED", "CANCELLED"}:
        raise RuntimeError(status.text)
    time.sleep(2)

result = requests.get(response_url, headers=headers, timeout=30)
result.raise_for_status()
print(result.json())

모델 페이지에서 연결되는 fal 큐 문서에는 sync_mode도 있지만, 4K에서는 큐 실행을 기본값으로 삼는 편이 안전하다. 렌더링이 일반적인 HTTP 요청 타임아웃보다 오래 걸릴 수 있기 때문이다. Layer는 이 비동기 계약을 더 명확하게 정의한다. 요청 제출 시 HTTP 202와 inference_id를 반환하고, 권장 폴링 간격도 안내한다. 또한 24시간 동안 재사용할 수 있는 멱등성 키를 지원해 네트워크 재시도에 따른 중복 과금을 줄이는 데 도움이 된다.

트래픽을 받기 전에 다음 항목을 먼저 처리하자.

1. 한 변이 256픽셀보다 작은 이미지를 거부하고, 선택한 프로바이더의 메가픽셀 제한을 적용한다.
2. 배열 순서를 유지하고 image 1, image 2처럼 각 입력을 가리키는 프롬프트를 생성한다.
3. 프로바이더가 지원한다면 고유한 멱등성 키를 사용한다. 그렇지 않다면 재시도 전에 요청 정보를 저장한다.
4. 폴링 시간을 제한하고 애플리케이션 요청을 계속 붙잡아 두는 대신 대기 상태를 반환한다.
5. 호스팅 결과 URL의 보존 정책이 애플리케이션과 다를 수 있으므로 완료된 파일을 관리하는 스토리지로 복사한다.
6. 모든 작업에 모델 ID, 프로바이더, 해상도, 레퍼런스 수, 예상 비용, 처리 시간, 모더레이션 결과를 기록한다.

비용과 품질 사이의 현실적인 선택

확인한 페이지에는 해상도별 가격표가 완전히 공개돼 있지 않아, 프로바이더 간 비용을 정밀하게 비교하기는 어렵다. fal은 1K 이미지당 프로모션 가격으로 $0.024를 안내했고, 프로모션 종료 후에는 $0.048로 오른다고 밝혔다. 레퍼런스 수는 과금액에 영향을 주지 않는다고도 설명했다. 하지만 해당 모델 페이지에는 정확한 2K 및 4K 가격이 표시되지 않았으므로 1K 가격만으로 4K 예산을 계산할 수는 없다.

4K가 언제나 최선이라고 가정하지 말고, 다음과 같은 2단계 정책을 적용하는 편이 낫다.

고해상도는 픽셀을 늘려줄 뿐 편집 충실도를 높여주지는 않는다. 1K에서 잘못된 편집이 나왔다면 4K에서는 더 큰 실패가 될 뿐이다. 인쇄물, 빌보드 레이아웃, 강한 크롭이 필요한 승인 완료 결과물에만 4K를 사용하는 것이 좋다.

애플리케이션이 시작될 때 최소한의 유효한 테스트 작업을 보내거나 프로바이더의 가격 정보를 조회해 예상 비용을 확보하자. 가격 정보가 없거나 작업 예산을 초과하면 4K를 비활성화한다. Layer의 초기 응답에는 estimated_price_creative_units가 포함될 수 있지만, 공개 모델 페이지에는 이를 달러로 환산하는 기준이 제시되지 않았다. Replicate의 확인된 모델 페이지에도 입력 항목은 문서화돼 있었지만 고정 가격은 없었다. 이런 부분은 코드에서 임의의 숫자를 가정할 문제가 아니라, 출시 전에 계정 대시보드에서 확인해야 할 조달상의 공백이다.

운영 방식에 맞춰 엔드포인트 고르기

프로바이더는 애플리케이션이 필요한 계약을 기준으로 선택해야 한다. 모델의 소유권이 같거나 이름이 비슷하다고 해서 스키마까지 호환되는 것은 아니다.

• Replicate: 출처와 소유권이 가장 중요하고 이미 Replicate의 prediction 워크플로를 사용하는 스택이라면 BFL 소유 모델을 선택한다. 여기서 확인한 경로 중 가장 넉넉한 16 MP 입력 제한을 제공하며, 선택적으로 웹/이미지 그라운딩도 지원한다.
• fal: 명확한 이미지 편집 제어 항목과 큐 기반 워크플로, 공개된 1K 가격이 중요하다면 파트너 편집 엔드포인트를 선택한다. 이미지당 4 MP 입력 제한이 있으므로 더 이른 단계에서 다운스케일링해야 한다.
• Layer: 워크스페이스 구성, 명확한 HTTP 202 계약, 폴링 안내, 24시간 멱등성이 필요하다면 적합하다. 다만 예산을 정하기 전에 Creative Units가 실제 달러 금액으로 어떻게 환산되는지 확인해야 한다.

도메인이나 저장소 이름에 “FLUX3”가 들어 있다는 이유만으로 프로바이더를 판단해서는 안 된다. 모델 ID, 소유자 또는 파트너 표시, 현재 enum 값, 상용 조건, 저비용 요청의 성공 여부를 직접 확인해야 한다. 검색 상위에 노출된 Anil-matcha/Flux-3-Dev-API 래퍼는 확인 당시에도 이미지 라우트를 “coming soon”으로 표시하고 있었다. 반면 BFL 소유 Replicate 경로와 fal 파트너 경로는 실제로 작동했다.

운영 배포 전 최종 점검표

FLUX 3 Image는 4K와 최대 10개 레퍼런스를 포함한 API 테스트에 적합하다. 다만 실제 배포는 선택한 엔드포인트가 대표적인 편집 세트를 1K와 최종 해상도 모두에서 통과한 뒤 진행해야 한다.

현실적인 권장 순서는 1K 편집부터 시작해 비용 견적과 지연 시간 데이터를 쌓고, 승인된 최종 결과에만 2K 또는 4K를 적용하는 것이다. 이렇게 하면 고해상도 품질과 비용을 확인하지 않은 채 가정하지 않으면서도, 현재 문서로 확인된 FLUX 3 Image의 핵심 기능을 활용할 수 있다.

관련 글

• FLUX 3 제품 개요
• 가장 저렴한 이미지 생성 API 비교