FLUX.2 텍스트-투-이미지 API 사용법? 파라미터, 코드, 그리고 실제 생성 이미지 한 장

TL;DR

• FLUX.2 Pro 텍스트-투-이미지의 HiAPI 모델명은 flux-2/text-to-image이며, Black Forest Labs 제품으로 프롬프트 준수와 이미지 내 텍스트가 강점입니다. 모델 페이지 열기에서 바로 온라인으로 시험해 볼 수 있습니다.
• 해상도 등급별로 과금됩니다: 0.5 MP $0.0375, 1 MP(기본) $0.05, 2 MP $0.075, 4 MP $0.125. 비율은 가격에 영향을 주지 않습니다.
• 가장 빠른 방법: POST /v1/tasks에 prompt를 전달하고, success가 될 때까지 폴링한 뒤 output[0].url을 다운로드합니다. resolution 값 중간에 공백이 있으므로 "1 MP"로 작성해야 합니다.

먼저 실제 생성 이미지 한 장

아래 이미지는 본문의 요청으로 생성한 것이며, 2 MP, 16:9입니다:

A wide overhead flat-lay of a modern developer desk: a matte black mechanical
keyboard on the left, a ceramic mug of steaming coffee on the right, a small
potted succulent in the top corner, and an open spiral notebook in the center
with the handwritten words 'API ready' clearly visible on the page, soft
natural window light falling from the left, a muted teal and warm wood color
palette, no other text or logos anywhere in the frame

이 프롬프트로 생성하기 → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0.075. 노트북의 'API ready'가 정확히 쓰였고, 화면에 불필요한 글자가 없습니다.

파라미터 빠른 조회

필드	필수	값	설명
prompt	예	문자열	중요 요소를 문장 첫머리에 두고, 30–80개의 영어 단어가 가장 효과적임
aspect_ratio	아니오	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, 기본 1:1	custom 선택 시 width / height를 함께 사용
resolution	아니오	0.5 MP / 1 MP / 2 MP / 4 MP, 기본 1 MP	가격 결정, custom일 때 무시됨
width / height	custom 시에만	256–2048	자동으로 16의 배수로 반올림됨
output_format	아니오	webp(기본) / jpg / png
output_quality	아니오	0–100, 기본 80	webp, jpg에만 적용됨
seed	아니오	정수	고정하면 동일한 결과를 재현 가능
safety_tolerance	아니오	1–5, 기본 2	1이 가장 엄격함

파라미터는 엄격하게 검증됩니다: 문서에 없는 필드를 하나라도 더 전달하면 바로 HTTP 400(additional properties ... not allowed)이 반환됩니다. 이 엔드포인트는 텍스트만 받으며, 참조 이미지로 이미지를 수정하려면 flux-2/image-to-image를 사용하세요.

curl: 첫 이미지 생성하기

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A matte charcoal coffee bag on a rustic oak counter, kraft paper label reading DAYBREAK ROAST, warm morning window light",
      "aspect_ratio": "4:3",
      "resolution": "1 MP",
      "output_format": "png"
    }
  }'

응답에는 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-2/text-to-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 wide overhead flat-lay of a modern developer desk, an open notebook with the handwritten words 'API ready', soft window light",
    aspect_ratio="16:9", resolution="2 MP", output_format="png", seed=42,
)
with open("desk.png", "wb") as f:
    f.write(requests.get(url).content)

얼마인가요

해상도	장당	100장
0.5 MP	$0.0375	$3.75
1 MP(기본)	$0.05	$5.00
2 MP	$0.075	$7.50
4 MP	$0.125	$12.50

HiAPI 현재 가격, 2026년 10월 18일 확인.

비율, seed, 출력 형식은 가격에 영향을 주지 않으며 오직 해상도 등급만 봅니다. 실패 시 과금되지 않습니다. 더 저렴하게 이용하려면 FLUX.2 [klein] 4B 1 MP가 장당 $0.00143이며, 등급별 비교는 FLUX.2 API 가격에서 확인하세요.

출시 전 주의사항

• resolution 중간에 공백이 있음: "1 MP"로 작성하며, "1MP"나 "1K"가 아닙니다. 잘못 쓰면 400이 반환되고 선택 가능한 값이 나열됩니다.
• custom 크기는 resolution을 무시함: aspect_ratio를 custom으로 쓰면 width × height 기준으로 이미지를 생성합니다.
• 재현하려면 seed를 고정: 동일한 프롬프트, 동일한 seed면 결과가 매우 일관되어 문구를 미세 조정할 때 대조하기 편리합니다.
• 결과를 즉시 저장: output[0].url에는 유효 기간이 있으므로 다운로드 후 자체 스토리지에 저장하세요.
• 폴링 대신 콜백 사용: input과 같은 레벨에 "callback": {"url": "https://your-app.example.com/hiapi/callback"}을 추가하고 taskId로 중복을 제거하세요.

자주 묻는 질문

resolution은 반드시 써야 하나요?

필수는 아니며 기본값은 1 MP입니다. 하지만 4 MP와 혼동하지 않도록 매번 쓰는 것을 권장합니다.

참조 이미지를 전달할 수 있나요?

이 엔드포인트에서는 불가능합니다. 참조 이미지로 이미지를 수정하거나 여러 이미지를 합성하려면 flux-2/image-to-image를 사용하며 최대 8장의 참조 이미지를 지원합니다. 바로 쓸 수 있는 프롬프트는 FLUX.2 이미지 수정 프롬프트에서 확인하세요.

왜 'additional properties not allowed'가 반환되나요?

이 모델에 없는 필드, 예를 들어 strength, prompt_upsampling을 전달했기 때문입니다. 위 파라미터 표에 있는 필드만 사용하세요.

FLUX.3 Image와 어떻게 선택하나요?

FLUX.3 Image는 하나의 모델명으로 생성과 수정을 모두 하고 4K 출력, 최대 10장의 참조 이미지를 지원합니다. FLUX.2 Pro는 seed와 사용자 지정 너비/높이를 지원하며 4 MP가 단 $0.125입니다. 동일 프롬프트 비교는 FLUX.3 Image vs FLUX.2에서 확인하세요.

위의 책상 프롬프트를 복사해서 모델 페이지에서 첫 이미지를 생성하세요.