GPT-Image-2 이미지 생성 | API 문서

# GPT-Image-2 Image Generation

Generate images or edit reference images with gpt-image-2 and receive results in the current JSON response or SSE connection.

POST https://api.apihop.ai/openai/v1/images/generations

`gpt-image-2` supports image generation and reference-image editing for product images, poster drafts, illustrations, social assets, high-resolution visuals, style transfer, and multi-reference fusion.

```text
POST https://api.apihop.ai/openai/v1/images/generations
```

## Authentication

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Quick Start

```json
{
  "model": "gpt-image-2",
  "prompt": "A minimal black wireless earbud product poster on a white background, clean studio lighting, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "low"
}
```

## Pricing comparison scope

RequestBeam's published **1K / 2K / 4K** image tiers are *RequestBeam selling prices*, not official fixed per-image OpenAI rates. The [OpenAI pricing documentation](https://developers.openai.com/api/docs/pricing) describes image/text-token and processing-tier charges; realized cost depends on size, quality, reference inputs, and output. Comparing the two merely because both mention `1k` or `2k` is not a like-for-like discount calculation.

To avoid an unsupported savings claim, the old aggregate-provider `USD per image` reference and discount badge are intentionally hidden for GPT Image 2. The RequestBeam price remains visible and its billing contract is unchanged. For a defensible future comparison, record the exact model, endpoint, image quality, size, input conditions, official source URL, and the date the reference was verified. Check your account's effective price before making a paid call.

## Body

### `model` (string, required, Default: gpt-image-2)

Image model ID. Use `gpt-image-2`.

### `prompt` (string, required)

Image prompt. Describe the subject, scene, composition, style, material, lighting, colors, and whether text should appear.

### `n` (integer, Default: 1)

Number of images to generate. The current `gpt-image-2` public contract only supports `1`. Other values return `400` before reservation.

### `size` (string, Default: auto)

Output aspect ratio or pixel dimensions.

Common values:

- `1:1`
- `4:3`
- `16:9`
- `9:16`
- `1024x1024`
- `1536x1024`
- `1024x1536`
- `2048x2048`
- `2048x1152`
- `3840x2160`
- `2160x3840`
- `auto`

### `quality` (string, Default: auto)

Output quality. Supported values include `low`, `medium`, `high`, and `auto`.

### `resolution` (string, Default: 1k)

Output resolution tier. Supported values are `1k`, `2k`, and `4k`.

It can be combined with `size`, for example `size: "16:9"` and `resolution: "2k"`.

### `image_urls` (array<string>)

Reference images used for instruction-based editing or multi-image fusion.

- Up to 16 images.
- Each image can be up to 20 MB, with a 256 MB total input limit.
- Publicly accessible image URLs are supported.
- Base64 data URIs such as `data:image/...;base64,...` are supported.
- URLs and base64 data URIs can be mixed in the same array.

### `output_format` (string, Default: png)

Output format. Supported values include `png`, `jpeg`, and `webp`.

### `stream` (boolean, Default: false)

Whether to return Server-Sent Events.

## Reference Images And Editing

Reference-image editing uses the same JSON endpoint. Add `image_urls` and describe what to preserve and change in `prompt`:

```json
{
  "model": "gpt-image-2",
  "prompt": "Keep the product unchanged, replace the background with a dark blue studio, and add soft rim lighting",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "size": "1:1",
  "resolution": "2k"
}
```

Multiple references can provide the subject, composition, or visual style:

```json
{
  "model": "gpt-image-2",
  "prompt": "Use the product from the first image and the composition from the second image to create a clean ecommerce hero image",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "4:3",
  "resolution": "2k"
}
```

Current public contract boundaries:

- Whole-image editing, style transfer, and multi-reference fusion are supported through `image_urls`.
- There is no separate `POST https://api.apihop.ai/openai/v1/images/edits` route.
- `multipart/form-data` uploads are not accepted. Convert local images to base64 data URIs or upload them to accessible URLs first.
- Mask-based inpainting is unsupported. Sending `mask`, `mask_url`, or `maskUrl` returns `400` before reservation.

## Request Examples

### 1:1 Product Image

```json
{
  "model": "gpt-image-2",
  "prompt": "A transparent glass cup on a light gray background, commercial product photography, soft shadow, no text",
  "n": 1,
  "size": "1024x1024",
  "resolution": "1k",
  "quality": "low",
  "output_format": "png"
}
```

### 16:9 Poster

```json
{
  "model": "gpt-image-2",
  "prompt": "A futuristic city night poster with neon lights, wet streets, cinematic composition, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "medium",
  "output_format": "jpeg"
}
```

## How Results Are Returned

This OpenAI-compatible endpoint does not first return a task submission response containing `data.jobId` for later polling:

- With `stream: false`, the current HTTP request waits for completion and

returns image URLs in the JSON response.

- With `stream: true`, the current SSE connection remains open through

`image_generation.completed` and `[DONE]`.

Do not use `GET https://api.apihop.ai/v1/jobs/{id}` to retrieve results from this endpoint. Use [Get Async Job](https://apihop.ai/en/docs/api-reference/jobs) only when an asynchronous creation endpoint explicitly returns a `jobId`.

## Non-Streaming Response

The response contains image URLs. `usage` is included when the upstream route provides metering information.

```json
{
  "created": 1777270000,
  "data": [
    {
      "url": "https://image.example.com/generated/123456789012345678/0.png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1234,
    "total_tokens": 1254
  }
}
```

## Streaming Response

```text
event: image_generation.completed
data: {"type":"image_generation.completed","data":[{"index":0,"url":"https://image.example.com/generated/123456789012345678/0.png"}],"usage":{"input_tokens":20,"output_tokens":1234,"total_tokens":1254}}

data: [DONE]
```

## Size Reference

| Target Ratio | 1K Recommended | 2K Recommended | 4K Recommended |
| --- | --- | --- | --- |
| `1:1` | `1024x1024` | `2048x2048` | Not recommended |
| `3:2` | `1536x1024` | `2048x1360` | Not recommended |
| `2:3` | `1024x1536` | `1360x2048` | Not recommended |
| `4:3` | `1024x768` | `2048x1536` | Not recommended |
| `3:4` | `768x1024` | `1536x2048` | Not recommended |
| `16:9` | `1536x864` | `2048x1152` | `3840x2160` |
| `9:16` | `864x1536` | `1152x2048` | `2160x3840` |
| `21:9` | `2016x864` | `2688x1152` | `3840x1648` |
| `9:21` | `864x2016` | `1152x2688` | `1648x3840` |

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

```json
{
  "code": 10000,
  "message": "prompt is required",
  "type": "api_error"
}
```

Common errors:

- `400`: missing required parameters or unsupported parameter combination
- `401`: authentication failed or API Key is incorrect
- `402`: insufficient balance
- `404`: model does not exist or is not enabled
- `429`: rate limit exceeded
- `5xx`: service temporarily unavailable or image generation failed

gpt-image-2는 제품 이미지, 포스터 초안, 일러스트, 소셜 콘텐츠, 고해상도 시각 자료, 스타일 전환 및 여러 참조의 융합을 위한 이미지 생성과 참조 이미지 편집을 지원합니다.

text

POST https://api.apihop.ai/openai/v1/images/generations

인증

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

빠른 시작

json

{
  "model": "gpt-image-2",
  "prompt": "A minimal black wireless earbud product poster on a white background, clean studio lighting, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "low"
}

가격 비교 범위

RequestBeam의 공개 1K / 2K / 4K 이미지 구간은 *RequestBeam 판매 가격*이며 OpenAI의 공식 고정 이미지당 요금이 아닙니다. OpenAI 가격 문서는 이미지/텍스트 토큰 및 처리 구간 요금을 설명하며 실제 비용은 크기, 품질, 참조 입력 및 출력에 따라 달라집니다. 둘 다 1k 또는 2k를 언급한다는 이유만으로 비교하면 같은 조건의 할인 계산이 아닙니다.

근거 없는 절약 주장을 피하기 위해 GPT Image 2의 기존 공급자 통합 USD per image 참고 가격과 할인 배지를 의도적으로 숨겼습니다. RequestBeam 가격은 계속 표시되며 청구 계약은 바뀌지 않습니다. 향후 근거 있는 비교를 하려면 정확한 모델, 엔드포인트, 이미지 품질, 크기, 입력 조건, 공식 출처 URL 및 참고 자료 검증 날짜를 기록하세요. 유료 호출 전에 계정에 실제 적용되는 가격을 확인하세요.

요청 본문

modelstring필수기본값: gpt-image-2

이미지 모델 ID입니다. gpt-image-2를 사용하세요.

promptstring필수

이미지 프롬프트입니다. 대상, 장면, 구도, 스타일, 재질, 조명, 색상 및 텍스트 포함 여부를 설명하세요.

ninteger기본값: 1

생성할 이미지 수입니다. 현재 gpt-image-2 공개 계약은 1만 지원합니다. 다른 값은 예약 전에 400을 반환합니다.

sizestring기본값: auto

출력 가로세로 비율 또는 픽셀 크기입니다.

일반적인 값:

1:1
4:3
16:9
9:16
1024x1024
1536x1024
1024x1536
2048x2048
2048x1152
3840x2160
2160x3840
auto

qualitystring기본값: auto

출력 품질입니다. low, medium, high, auto를 지원합니다.

resolutionstring기본값: 1k

출력 해상도 구간입니다. 1k, 2k, 4k를 지원합니다.

size와 조합할 수 있습니다. 예: size: "16:9"와 resolution: "2k".

image_urlsarray<string>

지시 기반 편집 또는 다중 이미지 융합에 사용하는 참조 이미지입니다.

최대 16개 이미지.
이미지당 최대 20 MB이며 전체 입력 한도는 256 MB입니다.
공개적으로 접근 가능한 이미지 URL을 지원합니다.
data:image/...;base64,... 같은 Base64 데이터 URI를 지원합니다.
같은 배열에서 URL과 Base64 데이터 URI를 혼합할 수 있습니다.

output_formatstring기본값: png

출력 형식입니다. png, jpeg, webp를 지원합니다.

streamboolean기본값: false

Server-Sent Events 반환 여부입니다.

참조 이미지 및 편집

참조 이미지 편집은 동일한 JSON 엔드포인트를 사용합니다. image_urls를 추가하고 prompt에 유지하거나 변경할 내용을 설명하세요:

json

{
  "model": "gpt-image-2",
  "prompt": "Keep the product unchanged, replace the background with a dark blue studio, and add soft rim lighting",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "size": "1:1",
  "resolution": "2k"
}

여러 참조에서 대상, 구도 또는 시각적 스타일을 제공할 수 있습니다:

json

{
  "model": "gpt-image-2",
  "prompt": "Use the product from the first image and the composition from the second image to create a clean ecommerce hero image",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "4:3",
  "resolution": "2k"
}

현재 공개 계약 범위:

image_urls로 전체 이미지 편집, 스타일 전환 및 여러 참조의 융합을 지원합니다.
별도 POST https://api.apihop.ai/openai/v1/images/edits 경로는 없습니다.
multipart/form-data 업로드는 허용하지 않습니다. 로컬 이미지를 먼저 Base64 데이터 URI로 변환하거나 접근 가능한 URL에 업로드하세요.
마스크 기반 인페인팅은 지원하지 않습니다. mask, mask_url, maskUrl을 전송하면 예약 전에 400을 반환합니다.

요청 예제

1:1 제품 이미지

json

{
  "model": "gpt-image-2",
  "prompt": "A transparent glass cup on a light gray background, commercial product photography, soft shadow, no text",
  "n": 1,
  "size": "1024x1024",
  "resolution": "1k",
  "quality": "low",
  "output_format": "png"
}

16:9 포스터

json

{
  "model": "gpt-image-2",
  "prompt": "A futuristic city night poster with neon lights, wet streets, cinematic composition, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "medium",
  "output_format": "jpeg"
}

결과 반환 방식

이 OpenAI 호환 엔드포인트는 이후 폴링을 위한 data.jobId가 포함된 작업 제출 응답을 먼저 반환하지 않습니다:

stream: false이면 현재 HTTP 요청이 완료를 기다리고 JSON 응답으로 이미지 URL을 반환합니다.
stream: true이면 현재 SSE 연결이 image_generation.completed와 [DONE]까지 유지됩니다.

이 엔드포인트의 결과에 GET https://api.apihop.ai/v1/jobs/{id}를 사용하지 마세요. 비동기 생성 엔드포인트가 jobId를 명시적으로 반환할 때만 비동기 작업 조회를 사용하세요.

비스트리밍 응답

응답에는 이미지 URL이 포함됩니다. 공급자 경로가 계량 정보를 제공하면 usage가 포함됩니다.

json

{
  "created": 1777270000,
  "data": [
    {
      "url": "https://image.example.com/generated/123456789012345678/0.png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1234,
    "total_tokens": 1254
  }
}

스트리밍 응답

text

event: image_generation.completed
data: {"type":"image_generation.completed","data":[{"index":0,"url":"https://image.example.com/generated/123456789012345678/0.png"}],"usage":{"input_tokens":20,"output_tokens":1234,"total_tokens":1254}}

data: [DONE]

크기 참조

목표 비율	1K 권장 크기	2K 권장 크기	4K 권장 크기
`1:1`	`1024x1024`	`2048x2048`	권장하지 않음
`3:2`	`1536x1024`	`2048x1360`	권장하지 않음
`2:3`	`1024x1536`	`1360x2048`	권장하지 않음
`4:3`	`1024x768`	`2048x1536`	권장하지 않음
`3:4`	`768x1024`	`1536x2048`	권장하지 않음
`16:9`	`1536x864`	`2048x1152`	`3840x2160`
`9:16`	`864x1536`	`1152x2048`	`2160x3840`
`21:9`	`2016x864`	`2688x1152`	`3840x1648`
`9:21`	`864x2016`	`1152x2688`	`1648x3840`

오류 응답

전체 코드 참조, 프로토콜 차이 및 진단 절차는 오류 코드 및 문제 해결을 참조하세요.

json

{
  "code": 10000,
  "message": "prompt is required",
  "type": "api_error"
}

일반적인 오류:

400: 필수 매개변수 누락 또는 지원하지 않는 조합
401: 인증 실패 또는 잘못된 API 키
402: 잔액 부족
404: 모델이 없거나 비활성화됨
429: 속도 제한 초과
5xx: 일시적인 서비스 사용 불가 또는 이미지 생성 실패