> ## 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.

# Images API 사용법: 이미지 생성과 편집

> LaoZhang API로 텍스트에서 이미지를 생성하거나 기존 이미지를 편집합니다. 파일 업로드부터 결과 저장까지 cURL과 Python 전체 예제로 안내합니다.

텍스트로 이미지를 만들거나, 이미지를 업로드하고 바꿀 내용을 설명해 편집합니다. 두 엔드포인트 모두 OpenAI Images 응답 형식을 씁니다.

| 항목 | 내용 |
| - | - |
| 생성 | `POST /v1/images/generations` |
| 편집 | `POST /v1/images/edits` |
| 결과 | `data[]`의 각 이미지가 `b64_json` 또는 `url`로 반환 |
| 예제 모델 | 생성 `gpt-image-2.5-flare-vip`, 편집 `gpt-image-2.5-sunburst-vip` |

Nano Banana 모델로 Gemini 네이티브 이미지 생성·편집을 하려면 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)를 참고하세요. 이미지 모델과 엔드포인트를 비교하려면 [이미지 API 비교](https://docs.laozhang.ai/ko/api-capabilities/image-generation-guide.md)를 보세요.

## 인증 정보 설정

[토큰 관리](https://api.laozhang.ai/token)에서 모델용 API 키(콘솔에서는 '토큰'이라고 부릅니다)를 만들고, `LAOZHANG_API_KEY` 환경 변수로 설정하세요. 키의 그룹이 GPT Image 2.5 VIP 모델을 쓸 수 있는지는 콘솔의 [모델 및 가격](https://api.laozhang.ai/account/pricing)에서 확인합니다.

터미널에서 자리표시자를 실제 키로 바꿔 설정합니다.

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

아래 예제는 다음 값을 씁니다.

* **API 호스트:** `https://api.laozhang.ai`
* **OpenAI SDK base URL:** `https://api.laozhang.ai/v1`
* **인증:** `Authorization: Bearer $LAOZHANG_API_KEY`
* **모델:** `gpt-image-2.5-flare-vip`(생성), `gpt-image-2.5-sunburst-vip`(편집)

API 호출과 이미지 저장에 쓰는 Python 패키지를 설치하세요. cURL 예제도 응답을 디코딩하고 알맞은 확장자를 고르는 데 Python을 씁니다.

```bash theme={null}
python -m pip install openai pillow httpx
```

### 응답에서 이미지 저장

예제를 실행할 디렉터리에 아래 헬퍼를 `save_images.py`로 저장하세요. `data[]` 항목이 `b64_json`이든 `url`이든 모든 이미지를 디스크에 저장합니다.

```python theme={null}
"""OpenAI Images API 응답의 이미지를 모두 저장합니다."""
import base64
import io
import json
import sys
from pathlib import Path

import httpx
from PIL import Image

EXTENSIONS = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}


def image_bytes(item):
    """data[] 항목 하나의 이미지 바이트를 반환합니다."""
    encoded = item.get("b64_json")
    if encoded:
        encoded = "".join(encoded.split())
        if encoded.startswith("data:"):
            encoded = encoded.split(",", 1)[1]  # data:image/...;base64, 접두사를 떼어 냅니다
        encoded += "=" * (-len(encoded) % 4)  # 빠진 패딩을 복원합니다
        return base64.b64decode(encoded)
    if item.get("url"):
        # LaoZhang API 키를 보내지 않고 결과를 내려받습니다.
        download = httpx.get(item["url"], timeout=120, follow_redirects=True)
        download.raise_for_status()
        return download.content
    raise ValueError("data[] 항목에 b64_json도 url도 없습니다")


def save_images(response, stem):
    """각 이미지를 <stem>.<ext>, <stem>-2.<ext> 순서로 저장합니다."""
    entries = response.get("data") or []
    if not entries:
        raise RuntimeError(f"응답에 이미지가 없습니다: {json.dumps(response)[:500]}")
    for number, item in enumerate(entries, start=1):
        raw = image_bytes(item)
        with Image.open(io.BytesIO(raw)) as image:
            image.load()
            extension = EXTENSIONS.get(image.format, (image.format or "bin").lower())
            size = f"{image.width} × {image.height}"
        suffix = "" if number == 1 else f"-{number}"
        output = Path(f"{stem}{suffix}.{extension}")
        output.write_bytes(raw)
        print(f"저장됨: {output} ({size})")


if __name__ == "__main__":
    save_images(json.loads(Path(sys.argv[1]).read_text(encoding="utf-8")), sys.argv[2])
```

cURL 요청 뒤에는 `python save_images.py <response.json> <이름>`으로 실행하고, Python에서는 `save_images`를 import해서 쓰세요.

## 이미지 생성

`model`과 `prompt`를 담은 JSON 본문을 다음 주소로 보냅니다.

```text theme={null}
POST https://api.laozhang.ai/v1/images/generations
```

아래 예제는 제품 이미지를 만들고, 반환된 파일 형식에 따라 `generated.png`, `generated.jpg`, `generated.webp` 중 하나로 저장합니다.

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 360 \
>   "https://api.laozhang.ai/v1/images/generations" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-image-2.5-flare-vip",
>     "prompt": "흰 테이블 위의 파란 세라믹 컵, 부드러운 자연광, 제품 사진."
>   }' \
>   -o generation-response.json
> ```
>
> 요청이 끝나면 `generation-response.json`에서 이미지를 저장합니다.
>
> ```bash theme={null}
> python save_images.py generation-response.json generated
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
> from save_images import save_images
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=360.0,
>     max_retries=0,
> )
> response = client.images.generate(
>     model="gpt-image-2.5-flare-vip",
>     prompt="흰 테이블 위의 파란 세라믹 컵, 부드러운 자연광, 제품 사진.",
> )
> save_images(response.model_dump(), "generated")
> ```

저장된 이미지를 열어 결과를 확인하세요. `.json` 파일은 API 응답이므로 확장자를 `.png`로 바꿔도 이미지가 되지 않습니다.

## 이미지 편집

명령을 실행할 디렉터리에 `input.png`라는 이미지를 두세요. 파일과 지시문을 multipart 폼 데이터로 다음 주소에 보냅니다.

```text theme={null}
POST https://api.laozhang.ai/v1/images/edits
```

아래 예제는 배경을 바꾸고, 결과를 `edited.png`, `edited.jpg`, `edited.webp` 중 하나로 저장합니다.

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 360 \
>   "https://api.laozhang.ai/v1/images/edits" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -F "model=gpt-image-2.5-sunburst-vip" \
>   -F "image[]=@input.png" \
>   -F 'prompt=배경을 연한 파란색으로 바꿔 주세요. 피사체는 그대로 유지하세요.' \
>   -o edit-response.json
> ```
>
> 요청이 끝나면 `edit-response.json`에서 이미지를 저장합니다.
>
> ```bash theme={null}
> python save_images.py edit-response.json edited
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
> from save_images import save_images
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=360.0,
>     max_retries=0,
> )
> with open("input.png", "rb") as source:
>     response = client.images.edit(
>         model="gpt-image-2.5-sunburst-vip",
>         image=[source],
>         prompt="배경을 연한 파란색으로 바꿔 주세요. 피사체는 그대로 유지하세요.",
>     )
> save_images(response.model_dump(), "edited")
> ```

`image[]=@input.png`는 파일 내용을 업로드합니다. JSON에 경로 문자열만 적으면 로컬 파일이 업로드되지 않습니다. cURL의 `-F` 옵션을 쓸 때는 multipart Content-Type과 boundary를 cURL이 정하게 두고, `Content-Type: application/json`을 추가하지 마세요.

바꿀 내용과 유지할 부분을 함께 설명하세요. 이미지 편집은 생성 방식이므로, 피사체를 그대로 두라고 지시해도 편집 영역 밖의 픽셀이 완전히 같다는 보장은 없습니다.

## 요청 옵션

위 최소 예제는 모델의 기본 출력 설정을 씁니다. 크기나 품질을 지정하려면 [GPT Image 2.5 가이드](https://docs.laozhang.ai/ko/api-capabilities/gpt-image-2-5.md)나 [GPT Image 2 가이드](https://docs.laozhang.ai/ko/api-capabilities/gpt-image-2.md)에서 해당 모델의 옵션을 확인하세요.

| 필드 | 용도 |
| - | - |
| `model` | 필수. `-vip` 같은 접미사까지 포함한 모델 ID |
| `prompt` | 필수. 만들 이미지나 바꿀 내용에 대한 설명 |
| `image[]` | multipart 편집 요청에서 필수인 파일 업로드 |
| `size` | 선택. 출력 크기이며 허용 값은 모델마다 다름 |
| `quality` | 선택. 품질 설정이며 허용 값은 모델마다 다름 |
| `n` | 선택. 이미지 수이며 모델별 제한을 따름 |

GPT Image와 DALL·E는 옵션이 다릅니다. DALL·E의 `quality="hd"`나 `style`을 GPT Image 요청에 그대로 옮기지 마세요. 마스크, 여러 참조 이미지, 투명 배경, 출력 형식 지정도 모델별 안내를 따라야 하며, 로컬 이미지 한 장을 편집할 때는 위의 기본 파일 업로드를 쓰세요.

## 이미지 결과 읽기

`data[]`의 각 항목은 출력 이미지 한 장이며, 다음 두 형태 중 하나로 반환됩니다.

* **`b64_json`**: Base64로 인코딩된 이미지 바이트입니다. 응답에 따라 `data:image/...;base64,` 접두사가 붙거나 끝의 `=` 패딩이 빠지므로, `save_images.py`처럼 접두사를 떼고 패딩을 복원한 뒤 디코딩하세요.
* **`url`**: 다운로드 링크입니다. LaoZhang API 키 없이 바로 내려받아 사본을 보관하세요. URL 결과는 만료될 수 있습니다.

이미지를 여러 장 요청했다면 `data[]`의 모든 항목을 처리하세요. 이미지 생성 작업 ID나 Gemini `candidates` 응답은 형식이 다르므로 해당 API에 맞는 처리 코드가 필요합니다.

## 오류와 재시도

* **400:** 요청 필드와 모델 옵션을 확인하세요. 편집이라면 파일이 multipart 데이터로 업로드되었는지 확인하세요.
* **401 또는 403:** API 키, 토큰 그룹, 모델 권한을 확인하세요.
* **404 또는 모델을 쓸 수 없다는 오류:** 엔드포인트와 정확한 모델 ID를 콘솔의 [모델 및 가격](https://api.laozhang.ai/account/pricing)에서 확인하세요.
* **429:** 오류 본문을 읽고 속도·동시 요청 제한 때문인지, 계정 잔액 문제인지 구분하세요.
* **5xx 또는 타임아웃:** 이미지 요청을 다시 보내기 전에 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)를 확인하세요.

클라이언트 타임아웃이 나도 서버 쪽 생성은 취소되지 않습니다. Python 예제는 SDK 자동 재시도를 꺼 두었으므로, 요청을 다시 보낼지는 애플리케이션이 정할 수 있습니다.

최신 가격과 과금 단위는 콘솔에 표시되며, 서비스와 환불 조건은 [이용약관](https://www.laozhang.ai/terms)을 따릅니다.

## 관련 문서

* [API 연동 가이드](https://docs.laozhang.ai/ko/api-manual.md)
* [이미지 API 비교](https://docs.laozhang.ai/ko/api-capabilities/image-generation-guide.md)
* [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)
* [OpenAI 이미지 생성 가이드](https://developers.openai.com/api/docs/guides/image-generation)
* [OpenAI 이미지 편집 레퍼런스](https://developers.openai.com/api/reference/resources/images/methods/edit)


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