FLUX.3 Image API 사용법? 5분 만에 첫 이미지 생성하기

TL;DR

• FLUX.3 Image는 Black Forest Labs가 2026년 10월에 출시한 이미지 모델이며, 모델명은 flux-3-image입니다. 하나의 모델명으로 텍스트 기반 이미지 생성과 이미지 편집을 모두 처리하며, 편집 시 최대 10장의 참조 이미지를 전송할 수 있습니다. 모델 페이지 열기에서 온라인으로 체험할 수 있습니다.
• 장당 과금: 1K(기본) $0.048, 2K $0.10, 4K $0.607, 10월 31일까지 각 등급 20% 할인. 작업당 1장 생성.
• 가장 빠른 호출 방법: POST /v1/tasks에 prompt를 전송하고, success가 될 때까지 폴링한 후 output[0].url을 다운로드합니다. resolution을 명시적으로 작성하고, 실패 상태인 fail과 failed를 모두 판단해야 합니다.

FLUX.3 Image란 무엇이고, 무엇이 새로운가?

• 생성과 편집이 하나의 모델명. image_urls를 전송하지 않으면 텍스트 기반 이미지 생성이고, 1–10장의 참조 이미지를 전송하면 참조 이미지를 중심으로 편집하며, 프롬프트에 각 이미지의 역할을 명확히 작성합니다.
• 5단계 해상도: 768($0.041)부터 4K($0.607)까지; 21:9부터 9:21까지 15가지 화면 비율, 별도로 auto 제공.
• 웹 검색으로 세부 정보 보충. grounding은 기본적으로 활성화되어 있으며, 생성 전에 웹페이지와 이미지를 검색하여 화면 정보를 보충할 수 있습니다.
• Artificial Analysis 텍스트 기반 이미지 생성 순위 9위.

1.5K, 3:2의 실내 이미지:

Architectural interior photograph of a cedar alpine reading cabin,
floor-to-ceiling window opening onto a misty mountain lake, linen armchair and a
small brass lamp, warm wood grain, quiet morning atmosphere, restrained
Scandinavian design, no text.

이 프롬프트로 생성 → (1.5K, 3:2)

flux-3-image, 1.5K, 3:2, $0.07.

두 가지 시작 방법

온라인 체험(코딩 없음):

1. FLUX.3 Image 모델 페이지를 열고 로그인합니다(신규 가입 시 200 크레딧 제공).
2. 프롬프트를 붙여넣고, 해상도와 화면 비율을 선택하며, 필요하면 참조 이미지를 업로드합니다.
3. 생성 버튼을 누르고 결과를 다운로드합니다.

API 호출:

1. 콘솔에서 API Key를 생성합니다.
2. POST /v1/tasks, "model": "flux-3-image".
3. GET /v1/tasks/{taskId}를 폴링하거나 콜백을 수신하고, output[0].url을 저장합니다.

curl: 첫 이미지 생성하기

1K, 4:3, $0.048:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "input": {
      "prompt": "A refined still life of a terracotta architectural model on ivory paper, brass desk lamp, olive leaves, soft late-afternoon sunlight, no text",
      "resolution": "1K",
      "aspect_ratio": "4:3"
    }
  }'

응답에 data.taskId가 포함됩니다. GET /v1/tasks/{taskId}를 폴링하고, status가 success로 바뀌면 output[0].url을 다운로드합니다.

Python: 제출, 폴링, 다운로드

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # 동일한 제출을 재시도할 때 같은 Idempotency-Key를 재사용하면 한 번만 과금됨
    r = requests.post(API, json={"model": "flux-3-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A cinematic rainy Tokyo side street at blue hour, a small bookstore with warm amber windows, a red bicycle outside, no readable signs",
    resolution="2K", aspect_ratio="16:9",
)
ext = url.split("?")[0].rsplit(".", 1)[-1]  # 반환된 파일 타입에 따라 저장
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

참조 이미지로 편집하기

image_urls를 전송하고(1–10장의 공개 링크), 프롬프트에 각 이미지가 무엇을 제공하는지, 무엇을 가져오지 말아야 하는지 명확히 작성합니다. 아래는 세 장 합성 예시입니다: 이미지 1은 주제, 이미지 2는 장면, 이미지 3은 색상만 차용합니다.

Create a refined product photograph. Use the cobalt blue ceramic teapot and
walnut handle from Image 1 as the main subject, place it on a pale stone side
table inside the cedar reading cabin from Image 2. Borrow only the subtle teal
and amber lighting palette from Image 3. Preserve the teapot shape and glaze,
keep the lake window visible in the background, realistic scale, no lettering.

url = generate(
    prompt=open("teapot_prompt.txt").read(),
    image_urls=[
        "https://your-cdn.example.com/teapot.jpg",   # 이미지 1: 주제
        "https://your-cdn.example.com/cabin.jpg",    # 이미지 2: 장면
        "https://your-cdn.example.com/street.jpg",   # 이미지 3: 색상만 차용
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image, 참조 이미지 3장, 3:2, $0.048. 참조 이미지 추가 요금 없음.

파라미터 빠른 조회

필드	값	설명
prompt	문자열, 필수, 최대 5000자	화면을 설명하거나, 무엇을 변경하고 무엇을 유지할지 명확히 작성
image_urls	1–10장의 공개 링크, 선택 사항	전송하지 않으면 텍스트 기반 이미지 생성
resolution	768 / 1K / 1.5K / 2K / 4K, 기본 1K	가격을 결정하며, 실제 너비와 높이는 화면 비율에 따라 달라짐
aspect_ratio	21:9 2:1 16:9 3:2 7:5 4:3 5:4 1:1 4:5 3:4 5:7 2:3 9:16 1:2 9:21 auto, 기본 auto	고정 배치에는 비율을 명시적으로 선택
safety_tolerance	0–4, 기본 2	0이 가장 엄격
grounding	불리언, 기본 true	생성 전에 웹페이지와 이미지 검색

출시 전 주의사항

• 매번 resolution을 작성하세요. 실수로 4K로 작성하면 한 장이 $0.048에서 $0.607로 바뀝니다.
• fail과 failed를 모두 판단하세요. 문서에는 failed라고 되어 있지만, 둘 다 판단하는 것이 더 안정적입니다.
• 폴링 대신 콜백 사용: input과 같은 레벨에 "callback": {"url": "https://your-app.example.com/hiapi/callback"}을 추가하고, taskId로 중복을 제거하세요.
• 결과를 즉시 저장하세요. output[0].url에는 유효 기간이 있으므로 제때 다운로드하거나 작업 생성 시 영구 저장을 선택하세요.
• Idempotency-Key 요청 헤더를 포함하세요, 재시도 시 동일한 Key로 작업을 한 번만 생성합니다.

자주 묻는 질문

한 작업에 몇 장이 생성되나요?

1장입니다. 여러 방향이 필요하면 각각 작업을 제출하세요.

PNG 또는 JPEG를 선택할 수 있나요?

이 모델은 형식 선택을 제공하지 않습니다. 특정 형식이 필요하면 다운로드 후 변환하세요.

언제 웹 검색을 꺼야 하나요?

이미 자신만의 참조 이미지가 있고 창작 방향도 정해졌을 때입니다. grounding: false를 작성하면 가격은 변하지 않습니다.

생성 실패 시 요금이 부과되나요?

부과되지 않습니다. 성공적으로 이미지가 생성된 경우에만 과금됩니다.

각 등급 가격은 FLUX.3 Image API 가격에서, 더 많은 프롬프트는 FLUX.3 Image 프롬프트 사례에서, 이전 세대와 동일 프롬프트 비교는 FLUX.3 Image vs FLUX.2에서 확인하세요. 또는 바로 모델 페이지에서 이 삼나무 오두막을 생성하세요.