> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/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 제공
- 비동기 처리 후 task_id로 결과 조회
- 텍스트 이미지 생성 및 최대 16장의 참조 이미지 편집 지원
- 15개 화면 비율, 정확한 픽셀 크기, 1K / 2K / 4K 지원
- low / medium / high / xhigh / max 품질 단계 

<Info>
  **모델 선택:** `gpt-image-2.5-flare`는 더 빠르며 일상적인 고품질 이미지, 일괄 생성, 빠른 프로토타입에 적합합니다. `gpt-image-2.5-sunburst`는 편집 정확도를 우선하여 완성도 높은 상품 이미지, 광고 소재, 세밀한 다단계 편집에 적합합니다. 두 모델의 요금은 같습니다.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2.5-flare",
      "prompt": "비 오는 창가의 아늑한 독서 공간, 따뜻한 램프 조명",
      "size": "1:1",
      "resolution": "1k",
      "quality": "medium",
      "n": 1
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [{
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "잘못된 요청 매개변수",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "인증에 실패했습니다. API 키를 확인하세요.",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "계정 잔액이 부족합니다",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## 인증

<ParamField header="Authorization" type="string" required>
  모든 엔드포인트는 Bearer Token 인증을 사용합니다. [API 키 페이지](https://apimart.ai/keys)에서 키를 발급받으세요.

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 모델 선택

| 모델                       | 특징        | 권장 용도                               |
| ------------------------ | --------- | ----------------------------------- |
| `gpt-image-2.5-flare`    | 빠른 기본 모델  | 소셜 콘텐츠, 상품 이미지, 시각 검색, 프로토타입, 일괄 생성 |
| `gpt-image-2.5-sunburst` | 편집 정확도 우선 | 완성형 상품 이미지, 광고 소재, 세밀한 다단계 편집       |

동일한 매개변수에서는 두 모델의 토큰 사용량과 가격이 같습니다. `gpt-image-2`보다 `xhigh`와 `max`가 추가되었으며, `medium`과 `high`의 출력 토큰은 이전 세대의 같은 이름 단계보다 약 4배 적습니다.

## 요청 매개변수

<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="size" type="string" default="auto">
  출력 화면 비율 또는 정확한 픽셀 크기입니다.

  * `auto`: 프롬프트 또는 참조 이미지를 기준으로 자동 선택
  * 비율: `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`
  * 정확한 크기(예: `1600x1200`)

  <Tip>
    이미지 편집에서는 `size`를 생략하면 입력 이미지 비율과 `resolution`을 바탕으로 출력 크기를 계산합니다.
  </Tip>
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  해상도 단계: `1k`, `2k`, `4k`. 정확한 픽셀 크기를 사용할 때는 무시됩니다.
</ParamField>

<ParamField body="quality" type="string" default="auto">
  품질: `low`, `medium`, `high`, `xhigh`, `max`, `auto`.

  <Warning>
    `xhigh`와 `max`는 GPT-Image-2.5 전용입니다. `gpt-image-2`에 전송하면 자동 하향 없이 HTTP 400을 반환합니다.
  </Warning>
</ParamField>

<ParamField body="n" type="integer" default="1">
  생성 이미지 수: `1`\~`4`. 문자열이 아닌 숫자로 전송하세요.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  출력 형식: `png`, `jpeg`, `webp`.
</ParamField>

<ParamField body="output_compression" type="integer">
  `0`\~`100`의 압축 수준이며 `jpeg`와 `webp`에만 적용됩니다.
</ParamField>

<ParamField body="background" type="string">
  배경: `transparent`, `opaque`, `auto`.

  <Warning>
    `transparent`는 `png` 또는 `webp`와 함께 사용해야 합니다. JPEG는 알파 채널을 지원하지 않습니다.
  </Warning>
</ParamField>

<ParamField body="moderation" type="string" default="low">
  콘텐츠 검토 수준: `auto` 또는 `low`. 생략하면 APIMart가 `low`를 명시적으로 전송하고, 명시한 `auto`는 그대로 전달합니다.
</ParamField>

<ParamField body="image_urls" type="string[]">
  이미지 생성 또는 편집용 참조 이미지 URL로 최대 `16`장입니다. 이 필드를 전달하면 편집 모드가 활성화됩니다.

  공개 접근 가능한 HTTP(S) URL만 사용할 수 있습니다. 로컬 이미지는 `POST /v1/uploads/images`로 업로드한 뒤 반환된 `url`을 사용하세요.
</ParamField>

## 크기 규칙

* 너비와 높이는 모두 `16`의 배수
* 어느 한 변도 `3840`픽셀을 초과할 수 없음
* 긴 변과 짧은 변 비율은 `3:1` 이하
* 전체 픽셀 수는 `655,360`\~`8,294,400`

<Warning>
  2560×1440을 초과하는 해상도는 실험적이며 일반 해상도보다 안정성이 낮을 수 있습니다.
</Warning>

### 비율 및 해상도 매핑

| `size` | `1k`      | `2k`      | `4k`      |
| ------ | --------- | --------- | --------- |
| `1:1`  | 1024×1024 | 2048×2048 | 2880×2880 |
| `3:2`  | 1536×1024 | 2048×1360 | 3520×2336 |
| `2:3`  | 1024×1536 | 1360×2048 | 2336×3520 |
| `4:3`  | 1024×768  | 2048×1536 | 3312×2480 |
| `3:4`  | 768×1024  | 1536×2048 | 2480×3312 |
| `5:4`  | 1280×1024 | 2560×2048 | 3216×2576 |
| `4:5`  | 1024×1280 | 2048×2560 | 2576×3216 |
| `16:9` | 1536×864  | 2048×1152 | 3840×2160 |
| `9:16` | 864×1536  | 1152×2048 | 2160×3840 |
| `2:1`  | 2048×1024 | 2688×1344 | 3840×1920 |
| `1:2`  | 1024×2048 | 1344×2688 | 1920×3840 |
| `21:9` | 2016×864  | 2688×1152 | 3840×1648 |
| `9:21` | 864×2016  | 1152×2688 | 1648×3840 |
| `3:1`  | 1536×512  | 3072×1024 | 3840×1280 |
| `1:3`  | 512×1536  | 1024×3072 | 1280×3840 |

모든 크기 규칙을 충족한다면 표에 없는 정확한 크기도 사용할 수 있습니다.

## 편집 예시

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "상품과 패키지 문구를 유지하고 배경을 부드러운 미색 스튜디오로 교체한 뒤 자연스러운 그림자를 추가",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

## 제출 및 작업 조회

제출 성공 시 작업 ID는 `data[0].task_id`에 있습니다. [작업 상태 API](/ko/api-reference/tasks/status)를 2\~5초마다 호출하여 `completed` 또는 `failed`가 될 때까지 확인하세요. 여러 작업은 `POST /v1/tasks/batch`로 조회할 수 있습니다.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "result": {
      "images": [{
        "url": ["https://upload.apimart.ai/f/image/example.png"],
        "expires_at": 1789000000
      }]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}
```

이미지 URL은 `data.result.images[].url[]`에 있습니다. 즉시 다운로드하여 별도로 저장하세요.

| 상태           | 의미                               |
| ------------ | -------------------------------- |
| `submitted`  | 제출됨                              |
| `processing` | 생성 중                             |
| `completed`  | 성공, `result.images` 사용 가능        |
| `failed`     | 실패, `error.message` 확인, 예약 금액 환불 |

## 과금

GPT-Image-2.5는 실제 토큰 사용량에 따라 과금됩니다. [요금 페이지](https://apimart.ai/pricing) 또는 `/api/pricing`에서 계정의 현재 요금을 확인하세요.

| 항목        | 100만 토큰당 가격 |
| --------- | ----------- |
| 이미지 출력    | \$30.00     |
| 이미지 입력    | \$8.00      |
| 캐시 이미지 입력 | \$2.00      |
| 텍스트 입력    | \$5.00      |
| 캐시 텍스트 입력 | \$1.25      |

| 1024×1024 `quality` | 출력 토큰 | 공식 출력 비용  |
| ------------------- | ----- | --------- |
| `low`               | 196   | \$0.00588 |
| `medium`            | 439   | \$0.01317 |
| `high`              | 1756  | \$0.05268 |
| `xhigh`             | 3122  | \$0.09366 |
| `max`               | 7024  | \$0.21072 |

<Warning>
  `quality: "auto"`에서는 선택한 크기의 `max` 금액을 먼저 예약하고, 완료 후 실제 사용량으로 정산하여 차액을 반환합니다.
</Warning>

`n > 1`이면 예약 금액이 이미지 수에 비례해 증가합니다. 실패한 작업은 자동 환불됩니다.

## 제한 및 자주 발생하는 오류

| 항목          | 제한 또는 해결 방법                       |
| ----------- | --------------------------------- |
| 요청당 이미지     | 1\~4                              |
| 참조 이미지      | 최대 16장                            |
| 출력 형식       | PNG / JPEG / WebP                 |
| 투명 배경       | PNG / WebP만 지원                    |
| 부분 이미지 스트리밍 | 미지원                               |
| 잘못된 품질      | `xhigh` / `max`는 GPT-Image-2.5 필요 |
| 잘못된 크기      | 픽셀 및 비율 범위 내에서 16의 배수 사용          |

## Response

<ResponseField name="code" type="integer">
  응답 코드이며 제출 성공 시 200입니다.
</ResponseField>

<ResponseField name="data" type="array">
  제출 응답 데이터입니다.

  <Expandable title="배열 항목">
    <ResponseField name="status" type="string">
      초기 상태는 `submitted`입니다.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      상태와 결과 조회에 사용하는 고유 작업 ID입니다.
    </ResponseField>
  </Expandable>
</ResponseField>