GPT Image 2.5 | Tài liệu API

# GPT Image 2.5

Generate images with Flare or edit reference images with Sunburst.

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

Use `gpt-image-2.5-flare` for fast image generation or `gpt-image-2.5-sunburst` for precise editing. Check `GET https://api.apihop.ai/v1/models` for availability with your API key.

## Request

```http
POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}
```

| Parameter | Values |
| --- | --- |
| `model` | Required: `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst` |
| `prompt` | Required text describing the image or edit |
| `n` | Integer from 1 to 4; default 1 |
| `size` | `auto`, aspect ratio, or pixel dimensions such as `1600x1200` |
| `resolution` | `1k` (default), `2k`, `4k`; ignored for exact pixel sizes |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (default) |
| `image_urls` | Up to 16 publicly accessible HTTP(S) image URLs |
| `output_format` | `png` (default), `jpeg`, `webp` |
| `output_compression` | Integer from 0 to 100 for JPEG or WebP |
| `background` | `auto`, `opaque`, `transparent`; transparent requires PNG or WebP |
| `moderation` | `low` (default), `auto` |
| `stream` | `false` (default) for JSON, `true` for SSE completion events |

Supported aspect ratios: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`. Exact pixel dimensions must be multiples of 16, have no side above 3840 pixels, an aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. For example, square `4k` output is 2880x2880, not 4096x4096.

## Reference Images

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

References use this JSON generation endpoint. Upload local images to your own storage first. Base64 data URIs, multipart uploads, masks, and a separate `/images/edits` endpoint are outside this model's public contract.

## Response

The HTTP connection waits for completion; clients do not poll an upstream task. JSON responses include final image URLs and available token usage:

```json
{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}
```

With `stream: true`, wait for `image_generation.completed` and `[DONE]` on the same connection. Partial image previews are not guaranteed.

## Pricing

Billing uses actual text input, cached text input, image input, cached image input, and image output tokens. Both variants have the same token prices. The model catalog shows your current price and the separate OpenAI reference price. An image is not a fixed-price unit: prompt length, references, size, quality, and count affect the total. A temporary reservation is reconciled after completion. Choosing an explicit quality makes expected usage clearer.

Invalid parameters return 400; authentication failures return 401; insufficient balance returns 402. An unavailable model returns 404, rate limits return 429, and generation failures return 5xx. Do not automatically resubmit a request whose completion status is unknown.

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for error codes, streaming failures, and retry boundaries.

Dùng gpt-image-2.5-flare để tạo ảnh nhanh hoặc gpt-image-2.5-sunburst để chỉnh sửa chính xác. Kiểm tra GET https://api.apihop.ai/v1/models để biết khả dụng với khóa API của bạn.

Yêu cầu

http

POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}

Tham số	Giá trị
`model`	Bắt buộc: `gpt-image-2.5-flare` hoặc `gpt-image-2.5-sunburst`
`prompt`	Văn bản bắt buộc mô tả ảnh hoặc chỉnh sửa
`n`	Số nguyên từ 1 đến 4; mặc định 1
`size`	`auto`, tỷ lệ khung hình hoặc kích thước pixel như `1600x1200`
`resolution`	`1k` (mặc định), `2k`, `4k`; bị bỏ qua với kích thước pixel chính xác
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (mặc định)
`image_urls`	Tối đa 16 URL ảnh HTTP(S) truy cập công khai
`output_format`	`png` (mặc định), `jpeg`, `webp`
`output_compression`	Số nguyên từ 0 đến 100 cho JPEG hoặc WebP
`background`	`auto`, `opaque`, `transparent`; trong suốt yêu cầu PNG hoặc WebP
`moderation`	`low` (mặc định), `auto`
`stream`	`false` (mặc định) cho JSON, `true` cho sự kiện hoàn tất SSE

Tỷ lệ khung hình hỗ trợ: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3. Kích thước pixel chính xác phải là bội số của 16, không cạnh nào trên 3840 pixel, tỷ lệ khung hình tối đa 3:1 và tổng từ 655,360 đến 8,294,400 pixel. Ví dụ, đầu ra vuông 4k là 2880x2880, không phải 4096x4096.

Ảnh tham chiếu

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Ảnh tham chiếu dùng điểm cuối tạo JSON này. Tải ảnh cục bộ lên kho lưu trữ của bạn trước. Data URI Base64, tải lên multipart, mặt nạ và điểm cuối /images/edits riêng nằm ngoài hợp đồng công khai của mô hình này.

Phản hồi

Kết nối HTTP chờ hoàn tất; máy khách không truy vấn tác vụ thượng nguồn. Phản hồi JSON gồm URL ảnh cuối cùng và lượng token sử dụng hiện có:

json

{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}

Với stream: true, chờ image_generation.completed và [DONE] trên cùng kết nối. Không bảo đảm có bản xem trước ảnh từng phần.

Giá

Tính phí theo token đầu vào văn bản thực tế, đầu vào văn bản lưu đệm, đầu vào ảnh, đầu vào ảnh lưu đệm và đầu ra ảnh. Hai biến thể có cùng giá token. Danh mục mô hình hiển thị giá hiện tại của bạn và giá tham chiếu OpenAI riêng. Ảnh không phải đơn vị giá cố định: độ dài prompt, ảnh tham chiếu, kích thước, chất lượng và số lượng ảnh hưởng tổng phí. Khoản giữ chỗ tạm thời được đối soát sau khi hoàn tất. Chọn chất lượng rõ ràng giúp dự kiến lượng sử dụng dễ hơn.

Tham số không hợp lệ trả 400; xác thực thất bại trả 401; số dư không đủ trả 402. Mô hình không khả dụng trả 404, giới hạn tốc độ trả 429 và tạo nội dung thất bại trả 5xx. Không tự động gửi lại yêu cầu có trạng thái hoàn tất chưa rõ.

Xem Mã lỗi và khắc phục để biết mã lỗi, lỗi truyền luồng và ranh giới thử lại.