---
title: "이미지 생성 연동"
description: "OpenAI Images 인터페이스를 사용해 이미지를 생성하고, Base64 결과를 저장하며, 모델 권한과 타임아웃을 문제 해결합니다."
headingIds: {"인터페이스와 준비":"section-1","이미지 하나 생성 후 저장":"section-2","파라미터 추가 전에 모델 지원 여부 확인":"section-3","자주 발생하는 문제":"section-4"}
---

<aside className="docs-publication" data-pagefind-ignore>

[1ZheAI](https://1zheai.com/en/editorial/#publisher)가 관리하는 문서입니다. [출처 및 수정 사항](https://1zheai.com/en/editorial/).

오류를 발견하셨나요? 페이지 주소와 설명을 첨부하여 [고객 지원](mailto:support@1zheai.com)으로 문의해 주세요. API 키나 계정 정보는 보내지 마세요.

</aside>
본 사이트의 공개 모델 카탈로그에는 현재 `gpt-image-1.5` 및 `chatgpt-image-latest`이 나열되어 있습니다(2026-10-16 확인). 사용 전에 먼저 [키 사용 가능 모델](/ko/docs/api-models/)을 조회하고, [콘솔 모델 카탈로그](https://1zheai.com/model-catalog?lng=ko)에서 이미지 인터페이스와 파라미터를 확인하세요.

이 페이지는 OpenAI Images 프로토콜에 따라 연동 예제를 제공합니다. 이번 문서 업데이트에서는 유료 이미지 생성을 실행하지 않았으므로, 아래 예제를 모든 모델, 크기, 품질 조합이 실제로 테스트된 것으로 간주하지 마세요.

## 인터페이스와 준비

- 전체 주소: `POST https://1zheai.com/v1/images/generations`
- OpenAI SDK Base URL: `https://1zheai.com/v1`
- 본 사이트의 `ONEZHE_API_KEY` 환경 변수를 사용합니다.
- Python SDK 설치: `python -m pip install openai`.

## 이미지 하나 생성 후 저장

`generate-image.py`로 저장하고, 터미널에서 `python generate-image.py`를 실행합니다:

```python
import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEZHE_API_KEY"],
    base_url="https://1zheai.com/v1",
    timeout=300.0,
    max_retries=0,
)
result = client.images.generate(
    model=os.environ.get("ONEZHE_IMAGE_MODEL", "gpt-image-1.5"),
    prompt="一只白色陶瓷茶杯放在浅灰色桌面上，柔和自然光，无文字。",
)
if not result.data:
    raise RuntimeError("响应没有图片数据，请检查错误信息与调用日志。")
item = result.data[0]
if item.b64_json:
    target = Path("generated-image.png")
    target.write_bytes(base64.b64decode(item.b64_json, validate=True))
    print(f"图片已保存到 {target.resolve()}")
elif item.url:
    print("返回的是图片地址，请及时下载：", item.url)
else:
    raise RuntimeError("响应没有 b64_json 或 url。")
```

예제는 기본 출력 형식을 사용합니다. JPEG / WebP 등을 별도로 지정하는 경우 저장 시에도 해당 파일 확장자로 변경하세요. Base64 문자열을 텍스트 파일로 직접 저장한 뒤 PNG로 이름을 바꾸지 마세요.

## 파라미터 추가 전에 모델 지원 여부 확인

먼저 `model`과 `prompt`만 포함된 요청으로 검증하세요. 크기, 품질, 투명 배경, 출력 형식 등의 파라미터는 모든 이미지 모델에 공통이 아닙니다. 다른 제공업체의 모델 이름이나 고유 파라미터를 그대로 복사하지 마세요.

`data[].b64_json`이 반환되면 Base64를 디코딩하고, `data[].url`이 반환되면 즉시 다운로드하여 임시 URL을 영구 저장소로 사용하지 마세요. 애플리케이션은 결과 저장을 직접 구성해야 합니다.

## 자주 발생하는 문제

| 상황 | 문제 해결 방법 |
| --- | --- |
| 400 파라미터 미지원 | 사용자 지정 크기, 품질 등 선택적 파라미터를 제거한 뒤 항목별로 검증 |
| 403 / 404 | 이미지 모델 ID, 키 권한, 전체 인터페이스 경로 확인 |
| 대기 시간이 김 | 생성에 적절한 타임아웃을 설정하고 진행 상태를 표시하여 반복 클릭으로 중복 제출 방지 |
| 타임아웃 후 이미지 없음 | 호출 로그를 먼저 확인; 결과를 받지 못했다고 상류에서 요청을 처리하지 않았다는 의미는 아님 |
| 기존 이미지 편집 원함 | 이미지 편집은 별도의 인터페이스와 입력 방식이며, 이 페이지의 텍스트 기반 이미지 생성 예제로 대체할 수 없음 |

프로토콜 파라미터 참고: [OpenAI 이미지 생성 참조](https://developers.openai.com/api/reference/resources/images/methods/generate). 비용은 본 사이트의 실시간 모델 카탈로그 기준입니다. 재시도 전략은 [타임아웃과 재시도](/ko/docs/retries/)을 참조하세요.