> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT-Image-2.5 이미지 생성

> gpt-image-2.5-flare 와 gpt-image-2.5-sunburst 일반 버전 연동 가이드로, 비동기 작업, 참조 이미지, 고정 high 품질과 해상도별 과금을 다룹니다

일반 버전은 `POST /v1/images/generations` 로 이미지 작업을 생성하고 작업 ID를 반환합니다. 작업이 완료되면 조회 API로 이미지 URL을 가져옵니다. 두 모델은 동일한 요청 형식을 사용합니다:

| 모델       | 요청의 model                |
| -------- | ------------------------ |
| Flare    | `gpt-image-2.5-flare`    |
| Sunburst | `gpt-image-2.5-sunburst` |

`gpt-image-2.5` 는 시리즈 이름입니다. 호출할 때는 표에 있는 전체 모델명을 입력하세요.

<Note>
  이 문서는 일반 버전을 설명합니다. 실제 token 으로 과금하려면 별도의 [GPT-Image-2.5 VIP 문서](../gpt-image-2.5-vip/generation) 를 사용하세요. 두 버전 모두 비동기 작업이며, 주요 차이는 size 형식과 과금 방식입니다.
</Note>

<Note>
  **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.
</Note>

API Key 는 [콘솔](https://toapis.com/dashboard) 에서 생성할 수 있습니다.

## 빠른 시작

ToAPIs API Key 를 환경 변수 `TOAPIS_API_KEY` 로 설정한 뒤 작업을 제출하세요:

```bash theme={null}
curl --fail-with-body --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Children's picture book style, a veterinarian listening to a baby otter's heartbeat with a stethoscope",
    "quality": "high",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'
```

제출 응답 예시:

```json theme={null}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.5-flare",
  "status": "pending",
  "progress": 0,
  "created_at": 1788951900,
  "metadata": {}
}
```

반환된 `id` 를 저장하고 아래의 `TASK_ID` 를 해당 값으로 바꾼 뒤 조회하세요:

```bash theme={null}
curl --fail-with-body \
  --url https://toapis.com/v1/images/generations/TASK_ID \
  --header "Authorization: Bearer $TOAPIS_API_KEY"
```

작업은 `pending`, `queued`, `in_progress` 를 거쳐 최종적으로 `completed` 또는 `failed` 가 됩니다. `completed` 이면 `result.data` 에서 이미지 URL을 읽고, `failed` 이면 `error` 를 읽습니다. 몇 초마다 한 번씩 조회하는 것을 권장합니다. 전체 필드는 [이미지 작업 상태 조회](../../tasks/image-status) 를 참고하세요.

제출 성공은 작업이 생성되었음을 의미합니다. `completed` 가 된 뒤에 이미지를 다운로드하고, 대기하는 동안에는 같은 작업 ID를 계속 조회하세요.

## Body

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_TOAPIS_API_KEY` 로 인증합니다.
</ParamField>

<ParamField body="model" type="string" required>
  `gpt-image-2.5-flare` 또는 `gpt-image-2.5-sunburst`.
</ParamField>

<ParamField body="prompt" type="string" required>
  이미지 설명입니다. 참조 이미지를 사용할 때는 유지할 대상과 수정할 내용을 설명에 담아야 합니다.
</ParamField>

<ParamField body="quality" type="string" default="high">
  현재 일반 버전의 W8X 채널은 `high` 로 고정되어 있어 이 파라미터를 생략할 수 있습니다. 다른 문자열 값을 전달하면 무시되고 `high` 가 사용됩니다. Playground 는 품질 옵션을 표시하지 않습니다.

  현재 일반 버전은 resolution 을 기준으로 요금이 책정됩니다.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  화면 비율입니다. 예: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `21:9`.

  비율을 사용하고 resolution 을 명시적으로 입력하는 것을 권장합니다. 서버는 두 값을 기준으로 출력 픽셀 크기를 계산합니다. 일반 버전의 비율 표기 방식은 VIP 버전의 픽셀 크기 표기 방식과 다릅니다.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  해상도 등급으로 `1K`, `2K`, `4K` 를 지원하고 소문자 형식도 허용합니다. 이 필드가 일반 버전의 과금 등급을 결정합니다.
</ParamField>

<ParamField body="background" type="string">
  선택적 배경 매개변수입니다. `"transparent"`를 지정하면 투명 배경 이미지를 생성합니다. 생략하면 일반 이미지를 생성합니다.

  텍스트 기반 생성과 `reference_images`가 포함된 요청 모두에 사용할 수 있습니다.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  요청당 `1` 을 사용해 이미지 한 장을 생성합니다.
</ParamField>

<ParamField body="reference_images" type="string[]">
  선택 사항인 참조 이미지 URL 목록입니다. 이미지 주소는 서버에서 접근할 수 있어야 합니다. 로컬 이미지는 먼저 [Upload 이미지 API](../../uploads/images) 로 업로드해 URL 을 받으세요.

  `image_urls` 도 호환됩니다. 둘 중 하나의 필드만 사용하세요. 이 문서의 예시는 URL 참조 이미지를 사용합니다. 로컬 파일을 직접 업로드해 편집해야 할 때는 [VIP 이미지 편집](../gpt-image-2.5-vip/generation) 을 참고하세요.
</ParamField>

## 비율과 해상도 예시

| size   | 1K          | 2K          | 4K          |
| ------ | ----------- | ----------- | ----------- |
| `1:1`  | `1024x1024` | `2048x2048` | `2880x2880` |
| `3:2`  | `1536x1024` | `2048x1360` | `3520x2336` |
| `2:3`  | `1024x1536` | `1360x2048` | `2336x3520` |
| `16:9` | `1536x864`  | `2048x1152` | `3840x2160` |
| `9:16` | `864x1536`  | `1152x2048` | `2160x3840` |

`4K` 는 해상도 등급을 의미하고 실제 가로와 세로는 화면 비율에 따라 달라집니다. 예를 들어 정사각형 4K 출력은 `2880x2880` 입니다.

## 참조 이미지 생성

동일한 생성 API 를 사용하고 `reference_images` 를 추가합니다. 아래 예시는 Sunburst 를 사용하며 반환값은 여전히 비동기 작업입니다:

```bash theme={null}
curl --fail-with-body --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Keep the baby otter and the veterinarian from the reference image, and add a yellow scarf to the baby otter",
    "reference_images": ["https://example.com/otter.png"],
    "quality": "high",
    "size": "1:1",
    "resolution": "2K",
    "n": 1
  }'
```

`https://example.com/otter.png` 를 자신의 참조 이미지 URL 로 바꾼 뒤 반환된 작업 ID로 결과를 조회하세요.

## 가격

아래는 2026-09-09 기준으로 확인한 표준 가격이며 생성 1회당 이미지 한 장 기준입니다. 두 일반 버전 모델의 가격은 동일합니다:

| resolution | USD/장 |
| ---------- | ----: |
| 1K         | 0.015 |
| 2K         | 0.020 |
| 4K         | 0.025 |

세 가격 모두 `low`, `medium`, `high`, `xhigh`, `max` 에 적용됩니다. 현재 참조 이미지 입력에는 별도의 장당 요금이 없습니다. 계정별 전용 가격이나 할인은 다를 수 있으며 최신 가격은 [모델 가격 페이지](https://toapis.com/pricing) 와 계정 실제 설정을 기준으로 하세요.

## VIP 버전과의 차이

| 항목         | 일반 버전                      | VIP 버전                     |
| ---------- | -------------------------- | -------------------------- |
| 모델명        | `-vip` 없음                  | `-vip` 포함                  |
| 작업 방식      | 비동기 작업이며 작업 ID로 이미지 URL 조회 | 비동기 작업이며 작업 ID로 이미지 URL 조회 |
| size       | `16:9` 처럼 비율 권장            | `1536x1024` 처럼 픽셀 크기       |
| resolution | `1K`, `2K`, `4K`           | 생략하고 size 로 크기 표현          |
| 과금         | resolution 에 해당하는 장당 가격    | 실제 텍스트와 이미지 token 기준       |
| 참조 이미지     | 생성 API 에 참조 이미지 URL 입력     | 편집 API 에 이미지 파일 업로드        |

VIP 로 전환할 때는 모델명과 파라미터를 함께 조정하세요. 자세한 내용은 [GPT-Image-2.5 VIP](../gpt-image-2.5-vip/generation) 를 참고하세요.