> ## 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에 참조 이미지를 최대 8장까지 JSON으로 보내 LaoZhang API에서 이미지를 편집하고, 결과가 만료되기 전에 저장하는 방법을 안내합니다.

FLUX.2는 생성에 쓰는 JSON 엔드포인트로 편집도 처리합니다. 이미지 한 장을 보내 수정하거나 여러 장을 합칠 수 있고, 요청은 건당 과금되며 결과 URL은 생성 10분 후 만료됩니다.

| 항목 | 내용 |
| - | - |
| 엔드포인트 | `POST https://api.laozhang.ai/v1/images/generations`, JSON 본문 |
| 편집할 이미지 | `prompt`와 `input_image` 전송 |
| 추가 참조 이미지 | `input_image_2`\~`input_image_8`, 전체 최대 8장 |
| 참조 이미지 형식 | 공개 이미지 URL 또는 `data:` URL |
| 가격 | 호출당 `flux-2-pro` \$0.03, `flux-2-flex` \$0.06, `flux-2-max` \$0.07. 2026년 9월 24일 기준 공개 가격([AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md) 참고) |
| 결과 | `data[0].url`. 이미지 생성 10분 후 만료되므로 바로 내려받으세요 |

`flux-2-pro`부터 시작하세요. Black Forest Labs는 가장 정밀한 편집에는 `flux-2-max`를, 텍스트 렌더링이나 작은 디테일처럼 세밀한 제어에는 `flux-2-flex`를 권장합니다. 세 모델 모두 요청 형식이 같습니다.

## 시작하기 전에

**1. API 키 발급**

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

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

![LaoZhang 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="sk-..."  # LaoZhang API 키로 바꾸세요
python3 -m pip install requests
```

**3. 다운로드 스크립트 저장**

아래 스크립트를 `save_images.py`로 저장합니다. cURL 예제는 응답 파일에 이 스크립트를 실행해 모든 이미지를 내려받습니다. FLUX는 URL만 반환하지만, 스크립트는 다른 이미지 모델이 반환하는 `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}")
```

## 이미지 편집

생성 요청에 `input_image`를 추가하면 편집 요청이 됩니다. URL은 공개적으로 접근 가능한 이미지로 바꾸세요.

```bash theme={null}
curl --fail-with-body --max-time 300 "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",
    "width": 1792,
    "height": 1024,
    "output_format": "png"
  }' \
  -o flux-edit.json

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

스크립트는 `저장 완료: flux-edit-1.png`를 출력합니다. 참조 URL은 요청 처리 중에 가져오므로 로그인, 쿠키, 봇 확인 없이 열려야 합니다.

> [!WARNING]
>
> 여러 참조 이미지를 조합하려면 `/v1/images/generations`로 JSON을 보내고 각 참조 이미지를 `input_image` 계열 필드에 넣으세요. multipart 엔드포인트 `/v1/images/edits`는 `image` 필드로 파일 한 개만 받으므로 참조 이미지를 조합할 수 없습니다.

### 로컬 파일 편집

내 컴퓨터의 파일을 편집하려면 파일과 MIME 타입이 일치하는 data URL로 보냅니다. 예를 들어 PNG는 `data:image/png;base64,...`입니다. 본문을 heredoc으로 넘기면 큰 이미지가 명령줄에 들어가지 않습니다.

```bash theme={null}
IMG=$(base64 < product.png | tr -d '\n')

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-local-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "부드러운 아침 햇살이 드는 대리석 카운터 위에 제품을 놓아 주세요. 제품과 라벨은 바꾸지 마세요.",
  "input_image": "data:image/png;base64,$IMG",
  "size": "1024x1024",
  "output_format": "png"
}
EOF

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

## 참조 이미지 조합

참조 이미지를 더 넣으려면 `input_image_2`부터 `input_image_8`까지 추가하고, 프롬프트에서는 필드 순서대로 이미지 1, 이미지 2처럼 가리킵니다. 다음 예제는 현재 디렉터리의 PNG 파일 세 개를 읽습니다.

```bash theme={null}
IMG1=$(base64 < robot.png | tr -d '\n')
IMG2=$(base64 < greenhouse.png | tr -d '\n')
IMG3=$(base64 < skateboard.png | tr -d '\n')

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-multi-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "세 참조 이미지를 하나의 자연스러운 새 이미지로 합쳐 주세요. 이미지 1은 빨간 로봇, 이미지 2는 청록색 유리 온실 배경, 이미지 3은 노란 스케이트보드입니다. 세 이미지의 디테일을 모두 살리고, 콜라주나 화면 분할 구성은 만들지 마세요.",
  "input_image": "data:image/png;base64,$IMG1",
  "input_image_2": "data:image/png;base64,$IMG2",
  "input_image_3": "data:image/png;base64,$IMG3",
  "width": 1792,
  "height": 1024,
  "output_format": "png"
}
EOF

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

## Python으로 편집하기

이 스크립트는 참조 이미지를 1\~8장 받아, 로컬 파일은 data URL로 바꾸고 공개 URL은 그대로 전달하며, 요청이 끝나는 즉시 결과를 저장합니다.

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

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def to_image_input(source):
    """URL은 그대로 반환하고, 로컬 파일은 data URL로 변환합니다."""
    if source.startswith(("https://", "http://", "data:")):
        return source
    path = Path(source)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def flux_edit(prompt, sources, width=1024, height=1024, model="flux-2-pro"):
    if not 1 <= len(sources) <= 8:
        raise ValueError("FLUX.2 참조 이미지는 1~8장이어야 합니다")
    payload = {
        "model": model,
        "prompt": prompt,
        "width": width,
        "height": height,
        "output_format": "png",
    }
    for number, source in enumerate(sources, start=1):
        field = "input_image" if number == 1 else f"input_image_{number}"
        payload[field] = to_image_input(source)
    response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=240)
    response.raise_for_status()
    return response.json()


def save_first_image(result, stem):
    # FLUX가 반환하는 URL은 10분 후 만료되므로 바로 내려받습니다.
    download = requests.get(result["data"][0]["url"], timeout=120)
    download.raise_for_status()
    image = download.content
    extension = "png" if image.startswith(b"\x89PNG") else "jpg"
    path = Path(f"{stem}.{extension}")
    path.write_bytes(image)
    return path


result = flux_edit(
    "이미지 1은 빨간 로봇, 이미지 2는 온실 배경, 이미지 3은 노란 스케이트보드입니다. "
    "콜라주가 아닌 하나의 자연스러운 새 장면을 만들어 주세요.",
    ["robot.png", "greenhouse.png", "skateboard.png"],
    width=1792,
    height=1024,
)
print("저장 완료:", save_first_image(result, "flux-python-edit"))
```

## 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 예 | `flux-2-pro`, `flux-2-flex`, `flux-2-max` |
| `prompt` | string | 예 | 편집 지시. 참조 이미지가 여러 장이면 이미지 1, 이미지 2처럼 지칭 |
| `input_image` | string | 편집 시 필수 | 첫 번째 참조 이미지. 공개 URL 또는 data URL |
| `input_image_2` … `input_image_8` | string | 아니요 | 추가 참조 이미지. 순서대로 번호 지정 |
| `size` | string | 아니요 | `1792x1024` 같은 출력 크기 |
| `width`, `height` | integer | 아니요 | 픽셀 단위 출력 크기. 16의 배수, 64 이상, 전체 약 4MP 이하. `size` 대신 사용 |
| `output_format` | string | 아니요 | `jpeg`(기본값) 또는 `png` |
| `seed` | integer | 아니요 | 같은 결과를 재현하기 위한 고정 시드 |
| `n` | integer | 아니요 | 이미지 수. `1`만 지원 |

출력 크기는 `size` 또는 `width`와 `height` 중 하나로만 정하세요. 자주 쓰는 `size` 값은 [FLUX.2 생성](https://docs.laozhang.ai/ko/api-capabilities/flux-image-generation.md)의 출력 크기 절에 있습니다.

## 응답 처리

응답은 `data[0].url`로 이미지 한 장을 반환합니다. FLUX는 `b64_json`을 반환하지 않으므로 `response_format`은 보내지 마세요. 링크는 이미지 생성 10분 후 만료되므로, 특히 배치 작업에서는 요청이 끝나는 즉시 내려받으세요.

`output_format`을 `png`로 설정하지 않으면 이미지는 JPEG입니다.

## 프롬프트 작성 팁

* 각 원본은 필드 순서대로 이미지 1, 이미지 2, 이미지 3처럼 지칭합니다.
* 로고, 얼굴, 제품 색상처럼 각 참조 이미지에서 반드시 유지할 요소를 적습니다.
* 결과가 하나의 자연스러운 이미지여야 한다고 명시합니다.
* 콜라주, 화면 분할, 테두리, 라벨처럼 피해야 할 것을 적습니다.

```text theme={null}
이미지 1은 캐릭터, 이미지 2는 배경, 이미지 3은 제품입니다.
하나의 자연스러운 상업 포스터를 만들어 주세요.
캐릭터의 옷차림, 배경의 조명, 제품 로고는 그대로 유지하세요.
콜라주나 화면 분할 구성은 만들지 마세요.
```

## 오류와 과금

* **HTTP 400**: 필드 이름, 참조 이미지 수, 출력 크기를 확인하세요.
  * 필드 이름: `input_image` 다음에 `input_image_2` 이상
  * 참조 이미지 수: 최대 8장
  * 출력 크기: 16의 배수, 64픽셀 이상, 약 4MP 이하. `size` 또는 `width`와 `height`로 지정
* **참조 이미지를 불러오지 못함**: URL이 공개되어 있어야 합니다. 그렇지 않으면 파일을 data URL로 보내세요.
* **결과 링크가 더 이상 열리지 않음**: 생성 10분 후 만료된 것입니다. 요청을 다시 실행하고 결과를 즉시 내려받으세요.
* **HTTP 401**: 키와 `Authorization: Bearer` 헤더를 확인하세요.
* **HTTP 429, 5xx, 타임아웃**: 백오프를 두고 재시도하세요. 타임아웃 후에는 이중 과금을 피하도록 다시 보내기 전에 [호출 로그](https://api.laozhang.ai/log)를 확인하세요.

요청마다 모델의 호출당 가격으로 과금됩니다. 호출 로그에서 요청별 모델과 청구 금액을 볼 수 있습니다.

## 레거시 FLUX Kontext 모델

`flux-kontext-pro`와 `flux-kontext-max`는 기존 연동을 위해 목록에 남아 있습니다. `size` 대신 `aspect_ratio` 필드를 쓰며, 자세한 내용은 [FLUX.2 생성](https://docs.laozhang.ai/ko/api-capabilities/flux-image-generation.md)의 레거시 호환 절에 있습니다. 새 편집 작업은 FLUX.2로 만드세요.

## 자주 묻는 질문

### 이미지의 일부만 편집할 수 있나요?

네, 프롬프트로 설명하면 됩니다. 요청에 마스크 필드는 없으므로 바꿀 요소와 유지할 부분을 프롬프트에 적으세요.

### 편집이 생성보다 비싼가요?

아닙니다. FLUX.2는 건당 과금이므로 참조 이미지가 1장이든 8장이든, 출력 크기가 얼마든 편집도 생성과 같은 호출당 가격입니다. 실제 청구 금액은 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)에서 확인하세요.

### 편집과 생성은 같은 모델을 쓰나요?

네. `flux-2-pro`, `flux-2-flex`, `flux-2-max`가 둘 다 처리합니다. `input_image`가 있으면 편집이고, 없으면 [FLUX.2 생성](https://docs.laozhang.ai/ko/api-capabilities/flux-image-generation.md)처럼 새 이미지를 만듭니다.

### OpenAI SDK의 `images.edit()`로 편집할 수 있나요?

이미지 한 장을 편집할 때만 가능합니다. `images.edit()`는 multipart 폼 데이터를 `/v1/images/edits`로 올리는데, 이 엔드포인트는 이미지를 한 장만 받으므로 참조 이미지를 조합할 수 없습니다.

대신 `client.images.generate()`를 쓰고 `input_image`(참조 이미지가 더 있으면 번호 붙은 필드도)를 공개 URL이나 data URL로 `extra_body`에 넣으세요. 이 페이지의 Python 헬퍼는 같은 작업을 `requests`로 합니다.

## 관련 문서와 참고 자료

* [FLUX.2 생성](https://docs.laozhang.ai/ko/api-capabilities/flux-image-generation.md): 텍스트로 이미지 생성, 출력 크기, 레거시 Kontext 모델
* [이미지 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): 요청별 모델과 청구 금액 확인
* [Black Forest Labs: FLUX.2 이미지 편집](https://docs.bfl.ai/flux_2/flux2_image_editing): 다중 참조 편집, 참조 이미지 제한, 결과 URL 유효 기간
* [Black Forest Labs: FLUX.2 개요](https://docs.bfl.ai/flux_2/flux2_overview): FLUX.2 모델별 용도


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