GPT Image 2.5 | 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.

빠른 이미지 생성에는 gpt-image-2.5-flare를, 정밀한 편집에는 gpt-image-2.5-sunburst를 사용하세요. GET https://api.apihop.ai/v1/models로 키의 사용 가능 여부를 확인하세요.

요청

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
}

매개변수	값
`model`	필수: `gpt-image-2.5-flare` 또는 `gpt-image-2.5-sunburst`
`prompt`	이미지 또는 편집 내용을 설명하는 필수 텍스트
`n`	1~4의 정수, 기본값 1
`size`	`auto`, 가로세로 비율 또는 `1600x1200` 같은 픽셀 크기
`resolution`	`1k`(기본값), `2k`, `4k`; 정확한 픽셀 크기를 지정하면 무시됨
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto`(기본값)
`image_urls`	공개적으로 접근 가능한 HTTP(S) 이미지 URL 최대 16개
`output_format`	`png`(기본값), `jpeg`, `webp`
`output_compression`	JPEG 또는 WebP에 적용할 0~100의 정수
`background`	`auto`, `opaque`, `transparent`; 투명도에는 PNG 또는 WebP 필요
`moderation`	`low`(기본값), `auto`
`stream`	JSON은 `false`(기본값), SSE 완료 이벤트는 `true`

지원 비율: 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. 정확한 픽셀 크기는 16의 배수여야 하며, 어느 변도 3840픽셀을 넘을 수 없고, 비율은 최대 3:1, 총 픽셀 수는 655,360~8,294,400이어야 합니다. 예를 들어 정사각형 4k 출력은 4096x4096이 아닌 2880x2880입니다.

참조 이미지

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"
}

참조 이미지는 동일한 JSON 생성 엔드포인트를 사용합니다. 로컬 이미지는 먼저 자체 저장소에 업로드하세요. Base64 데이터 URI, multipart 업로드, 마스크 및 별도의 /images/edits 엔드포인트는 이 모델의 공개 계약에 포함되지 않습니다.

응답

HTTP 연결은 완료될 때까지 기다리며 클라이언트는 상위 공급자 작업을 폴링하지 않습니다. JSON 응답에는 최종 이미지 URL과 사용 가능한 토큰 사용량이 포함됩니다:

json

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

stream: true이면 동일한 연결에서 image_generation.completed와 [DONE]을 기다리세요. 부분 이미지 미리보기는 보장되지 않습니다.

요금

요금은 실제 텍스트 입력, 캐시된 텍스트 입력, 이미지 입력, 캐시된 이미지 입력 및 이미지 출력 토큰을 기준으로 계산합니다. 두 변형은 같은 토큰 가격을 사용합니다. 모델 카탈로그는 현재 적용 가격과 별도의 OpenAI 참고 가격을 표시합니다. 이미지 한 장은 고정 가격 단위가 아닙니다. 프롬프트 길이, 참조 이미지, 크기, 품질 및 개수가 합계에 영향을 줍니다. 임시 예약 금액은 완료 후 정산됩니다. 품질을 명시하면 예상 사용량이 더 명확해집니다.

잘못된 매개변수는 400, 인증 실패는 401, 잔액 부족은 402를 반환합니다. 모델을 사용할 수 없으면 404, 속도 제한은 429, 생성 실패는 5xx를 반환합니다. 완료 여부가 불명확한 요청을 자동으로 다시 제출하지 마세요.

오류 코드, 스트리밍 실패 및 재시도 범위는 오류 코드 및 문제 해결을 참조하세요.