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 定價文件說明的是圖像／文字 token 與處理級距費用，實際成本取決於尺寸、品質、參考輸入與輸出。僅因兩者都提到 1k 或 2k 就進行比較，並不是同條件的折扣計算。

為避免無依據的省費宣稱，GPT Image 2 已刻意隱藏舊的聚合供應商 USD per image 參考價與折扣標籤。RequestBeam 價格仍可見，計費契約維持不變。未來若要進行有依據的比較，請記錄確切模型、端點、圖像品質、尺寸、輸入條件、官方來源網址及參考資料的驗證日期。付費呼叫前請確認您帳號的實際生效價格。

請求主體

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。
支援可公開存取的圖像網址。
支援像 data:image/...;base64,... 這樣的 Base64 資料 URI。
同一陣列可混用網址與 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，或上傳至可存取的網址。
不支援遮罩式局部重繪。傳送 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 回應中傳回圖像網址。
設定 stream: true 時，目前 SSE 連線會持續開啟，直到 image_generation.completed 與 [DONE]。

請勿使用 GET https://api.apihop.ai/v1/jobs/{id} 取得此端點結果。只有非同步建立端點明確回傳 jobId 時，才使用查詢非同步任務。

非串流回應

回應包含圖像網址。上游路由提供計量資訊時，會包含 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：服務暫時不可用或圖像生成失敗