> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FLUX.2 이미지 생성 API: 가격과 사용법

> flux-2-pro, flux-2-flex, flux-2-max로 LaoZhang API의 JSON 엔드포인트 하나에서 이미지를 만들고, 출력 크기를 정하고, 결과를 제때 저장하는 방법을 안내합니다.

FLUX.2 작업은 대부분 `flux-2-pro`로 충분합니다. 생성과 편집은 건당 과금되는 같은 JSON 엔드포인트를 쓰며, 결과 URL은 생성 10분 후 만료되므로 곧바로 내려받아야 합니다.

| 항목 | 내용 |
| - | - |
| `flux-2-pro` | 호출당 \$0.03, 기본으로 권장 |
| `flux-2-flex` | 호출당 \$0.06, Black Forest Labs가 텍스트 렌더링과 작은 디테일에 특화된 모델로 소개 |
| `flux-2-max` | 호출당 \$0.07, Black Forest Labs 모델 중 프롬프트를 가장 충실히 따름 |
| 가격 기준 | 2026년 9월 24일 기준 공개 가격, [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md) 참고 |
| 엔드포인트 | `POST https://api.laozhang.ai/v1/images/generations`, JSON 본문 |
| 요청 | `model`, `prompt`, 출력 크기 |
| 결과 | `data[0].url`의 이미지 URL, 10분간 유효 |
| 편집 | 같은 엔드포인트에 참조 이미지 추가, [FLUX.2 편집](https://docs.laozhang.ai/ko/api-capabilities/flux-image-edit.md) 참고 |

세 모델 모두 요청 형식이 같습니다.

## 시작하기 전에

**1. API 키 발급**

FLUX.2 모델은 건당 과금입니다. [토큰 관리](https://api.laozhang.ai/token)에서 API 키(콘솔에서는 '토큰'이라고 부릅니다)를 새로 만들거나 기존 키를 편집해 **과금 방식**(计费模式)을 **사용량 우선**(按量优先, 권장) 또는 **건당 과금**(按次计费)으로 설정합니다. 사용량 우선 키는 건당 과금 모델과 사용량 과금 모델을 모두 호출할 수 있고, 건당 과금 키는 건당 과금 모델만 호출할 수 있습니다.

키는 서버 측 환경 변수에 보관하세요.

![토큰 관리에서 과금 방식을 건당 과금(按次计费)으로 설정하고 만들기를 눌러 토큰을 생성하는 화면](https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/token-create-per-request.png?fit=max\&auto=format\&n=_loZ0Jy0ZI__xJ9z\&q=85\&s=1fdceb804bb3ad50f83a21ec65b4d807)

**2. 환경 설정**

키를 환경 변수로 설정하고, Python 예제에서 쓰는 `requests`를 설치합니다.

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
python3 -m pip install requests
```

## 이미지 생성

1792×1024 가로 이미지를 만들고 응답을 `flux-generation.json`에 저장하는 요청입니다.

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "청록색 유리 온실 앞에서 노란 스케이트보드를 타는 루비색 레트로 로봇, 깔끔한 제품 일러스트 스타일",
    "size": "1792x1024"
  }' \
  -o flux-generation.json
```

### 결과 저장

응답의 `data[0].url`은 이미지 생성 10분 후 만료되므로 바로 내려받으세요. FLUX는 URL만 반환하고 `b64_json`은 반환하지 않습니다. 아래 스크립트를 `save_images.py`로 저장하면 응답의 모든 이미지를 내려받으며, 다른 이미지 모델이 반환하는 `b64_json`도 디코딩합니다.

```python save_images.py theme={null}
import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"{response_file}에 이미지가 없습니다: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # data:image/...;base64, 접두사가 있으면 떼고, 빠진 패딩을 채웁니다.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"저장 완료: {path}")
```

```bash theme={null}
python3 save_images.py flux-generation.json flux-robot
```

스크립트는 `저장 완료: flux-robot-1.jpg`를 출력합니다. `output_format`을 `png`로 설정하지 않으면 FLUX.2는 JPEG를 반환합니다.

### Python으로 생성하기

```python theme={null}
import os
from pathlib import Path

import requests

response = requests.post(
    "https://api.laozhang.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "model": "flux-2-pro",
        "prompt": "대리석 테이블 위에 놓인 투명한 스마트 스피커, 영화 같은 제품 사진",
        "size": "1024x1024",
    },
    timeout=240,
)
response.raise_for_status()
image_url = response.json()["data"][0]["url"]

# 결과 URL은 10분 후 만료되므로 바로 내려받습니다.
download = requests.get(image_url, timeout=120)
download.raise_for_status()
image = download.content

extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"flux-speaker.{extension}")
output.write_bytes(image)
print(f"저장 완료: {output}")
```

## 출력 크기

출력 크기는 OpenAI 방식의 `size` 문자열로 정하거나, `width`와 `height`를 픽셀로 지정합니다. 둘 중 하나만 쓰세요.

| `size` | 출력 | 주요 용도 |
| - | - | - |
| `1024x1024` | 1024×1024 | 정사각형 이미지, 아바타, 제품 사진 |
| `1792x1024` | 1792×1024 | 가로형 커버, 배너, 히어로 이미지 |
| `1024x1792` | 1024×1792 | 세로형 포스터, 모바일 커버, 스토리 이미지 |

`width`와 `height`는 16의 배수이고 64픽셀 이상이어야 하며, 전체 픽셀은 약 4메가픽셀(예: 2048×2048)을 넘을 수 없습니다. 편집에서도 같은 크기 필드를 씁니다.

## 이미지 편집

같은 JSON 요청에 `input_image`를 추가하면 텍스트만으로 생성하는 대신 이미지를 편집합니다. 다음은 공개 이미지의 주제는 유지하고 배경만 바꾸는 최소 편집 예제입니다.

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "주요 피사체는 그대로 두세요. 배경을 깔끔한 연한 파란색 스튜디오 배경으로 바꾸고 원래 조명은 유지하세요.",
    "input_image": "https://example.com/source.png",
    "size": "1792x1024",
    "output_format": "png"
  }' \
  -o flux-edit.json

python3 save_images.py flux-edit.json flux-edit
```

참조 이미지 여러 장은 이 엔드포인트의 JSON 필드로만 보낼 수 있습니다. 로컬 파일, 최대 8장의 참조 이미지, Python 헬퍼, 편집 프롬프트 작성법은 [FLUX.2 편집](https://docs.laozhang.ai/ko/api-capabilities/flux-image-edit.md)을 참고하세요.

## 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 예 | `flux-2-pro`, `flux-2-flex`, `flux-2-max` |
| `prompt` | string | 예 | 생성할 내용 |
| `size` | string | 아니요 | `1792x1024` 같은 출력 크기. 기본값 `1024x1024` |
| `width`, `height` | integer | 아니요 | 픽셀 단위 출력 크기. 16의 배수, 64 이상, 전체 약 4MP 이하. `size` 대신 사용 |
| `n` | integer | 아니요 | 이미지 수. `1`만 지원 |
| `output_format` | string | 아니요 | `jpeg`(기본값) 또는 `png` |
| `seed` | integer | 아니요 | 같은 결과를 재현하기 위한 고정 시드 |
| `input_image` … `input_image_8` | string | 아니요 | 공개 URL 또는 data URL 형식의 참조 이미지. 넣으면 편집 요청이 됨 |

## 레거시 호환: FLUX Kontext

`flux-kontext-pro`(호출당 \$0.035)와 `flux-kontext-max`(호출당 \$0.07)는 기존 연동을 위해 계속 제공됩니다. 엔드포인트는 같고, 다음 점이 다릅니다.

* `size` 대신 `aspect_ratio` 필드를 받습니다. OpenAI Python SDK에서는 `extra_body`로 전달합니다.
* `3:7`부터 `7:3`까지 어떤 비율이든 쓸 수 있으며, 출력은 약 1메가픽셀로 유지됩니다.

자주 쓰는 비율과 대략적인 출력 크기입니다.

| `aspect_ratio` | 대략적인 출력 |
| - | - |
| `1:1` | 1024×1024 |
| `3:2` / `2:3` | 1248×832 / 832×1248 |
| `16:9` / `9:16` | 1408×792 / 792×1408 |
| `21:9` | 1680×720 |
| `7:3` / `3:7` | 1544×662 / 662×1544 |

새로 생성이나 편집 작업을 만든다면 FLUX.2를 쓰세요.

## 자주 묻는 질문

### BFL API처럼 결과를 폴링해야 하나요?

아닙니다. BFL API는 작업 ID와 `polling_url`을 반환하고, 상태가 `Ready`가 될 때까지 폴링해야 합니다. LaoZhang API는 같은 요청 안에서 이미지가 완성되기를 기다렸다가 `data[0].url`로 반환합니다.

대신 클라이언트 타임아웃을 넉넉하게 잡으세요. Python 예제는 240초를 씁니다. 요청이 리버스 프록시나 서버리스 함수를 거친다면 그쪽의 타임아웃이나 실행 시간 제한도 늘려야 이미지가 완성되기 전에 연결이 끊기지 않습니다.

### 이미지 URL이 왜 열리지 않나요?

결과 URL은 생성 10분 후 만료되며, BFL 자체 결과 링크와 유효 기간이 같습니다. 요청이 끝나는 즉시 서버에서 이미지를 내려받아 자체 저장소에 보관하고, 데이터베이스나 프런트엔드에는 그 주소를 넘기세요.

배치 작업에서는 전체 배치가 끝나기를 기다리지 말고 요청이 끝날 때마다 결과를 내려받으세요. 다운로드가 밀리지 않도록 동시 요청 수도 적당히 낮게 유지하세요.

만료된 URL은 갱신할 수 없습니다. 요청을 다시 보내야 하며, 이는 새 호출로 과금됩니다.

### 같은 결과를 다시 얻으려면 어떻게 하나요?

같은 모델, 프롬프트, 크기에 같은 `seed`를 보내세요. 디자인 하나를 조금씩 다듬을 때 유용합니다.

### 텍스트와 브랜드 색상을 정확하게 넣으려면 어떻게 하나요?

포스터, 인포그래픽, UI 목업처럼 텍스트가 많은 이미지는 `flux-2-flex`부터 써 보세요. BFL은 이 모델을 텍스트 렌더링과 작은 디테일용으로 소개합니다. 최고 품질과 가장 충실한 프롬프트 반영이 필요하면 `flux-2-max`를 쓰세요.

브랜드 색상을 맞추려면 `the mug is #FF5A1F`처럼 프롬프트에 hex 코드를 넣으세요. 복잡한 장면은 피사체, 배경, 조명, 스타일을 JSON 문자열로 작성해 `prompt`로 보낼 수도 있습니다.

### 실패한 요청도 과금되나요?

과금되지 않습니다. FLUX.2는 건당 과금이므로 이미지가 반환된 요청만 한 번 과금되고, 파라미터 오류나 모더레이션 차단처럼 200이 아닌 응답은 과금되지 않습니다.

클라이언트 타임아웃은 실패와 다릅니다. 서버에서는 이미지가 완성되어 과금되었을 수 있으니, 다시 보내기 전에 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)를 확인하세요. 실제 청구 내역의 최종 기준은 호출 로그입니다.

### OpenAI SDK를 쓸 수 있나요?

네. `client.images.generate()`를 사용합니다.

* `base_url`을 `https://api.laozhang.ai/v1`로 설정합니다.
* `model`, `prompt`, `size`는 평소처럼 전달합니다.
* `width`, `height`, `seed` 같은 FLUX 전용 필드는 `extra_body`에 넣습니다.

이미지 URL은 `response.data[0].url`에 있으니 바로 내려받으세요.

편집도 `client.images.generate()`를 쓰고 `input_image`를 `extra_body`에 넣습니다. `client.images.edit()`는 이미지를 한 장만 받습니다. 자세한 내용은 [FLUX.2 편집](https://docs.laozhang.ai/ko/api-capabilities/flux-image-edit.md)의 자주 묻는 질문을 참고하세요.

## 관련 문서

* [FLUX.2 편집](https://docs.laozhang.ai/ko/api-capabilities/flux-image-edit.md): 이미지 한 장 편집 또는 참조 이미지 최대 8장 조합
* [이미지 API 비교](https://docs.laozhang.ai/ko/api-capabilities/image-generation-guide.md): FLUX.2와 다른 이미지 모델 비교
* [Images API](https://docs.laozhang.ai/ko/api-reference/images.md): 공통 요청·응답 형식
* [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md): FLUX 현재 가격과 그룹
* [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md): 요청별 모델과 청구 금액 확인
* [콘솔의 모델 및 가격](https://api.laozhang.ai/account/pricing): 내 계정에 적용되는 가격
* [Black Forest Labs: FLUX.2 개요](https://docs.bfl.ai/flux_2/flux2_overview): FLUX.2 모델별 용도, hex 색상 지정, 구조화 프롬프트
* [Black Forest Labs: API 연동 가이드](https://docs.bfl.ai/api_integration/integration_guidelines): BFL의 비동기 폴링 흐름과 10분짜리 결과 URL


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.