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

# GPT-Image-2.5 · 이미지-이미지

> GPT-Image-2.5 Flare / Sunburst · POST /v1/images/edits

## 소개

GPT-Image-2.5 **Flare**와 **Sunburst**는 참조 이미지와 텍스트 지시를 바탕으로 편집합니다. `POST /v1/images/edits`는 배경 교체, 색상 변경, 스타일 전환, 부분 리터치 및 다중 참조에 적합합니다.

prompt에 변경 및 유지할 부분을 명확히 작성하고 JSON 이미지 참조 또는 multipart 파일을 전달하세요. 국소 편집은 mask 또는 투명 markup 중 하나만 사용합니다. 빠른 반복에는 Flare, 세부 표현과 편집 정확도에는 Sunburst가 적합합니다.

### 모델 선택

| 모델 ID | 권장 용도 |
| - | - |
| `gpt-image-2.5-flare` | 빠른 반복 작업과 대화형 생성 |
| `gpt-image-2.5-sunburst` | 세부 묘사, 복잡한 레이아웃 및 정밀 편집 |

두 모델은 이 페이지의 엔드포인트, 매개변수 및 응답 구조를 공유합니다. 예시는 Flare를 사용하며 model만 바꾸면 Sunburst로 전환할 수 있습니다. 나머지 필드는 작업에 맞게 설정하세요.

## 인증

**Authorization** `string` *required*

Bearer \$GRAVITEX\_API\_KEY

**Content-Type** `string` *required*

application/json / multipart/form-data

## 요청 매개변수

| 매개변수 | 유형 | 설명 |
| - | - | - |
| `model` | string | 필수: gpt-image-2.5-flare 또는 gpt-image-2.5-sunburst |
| `prompt` | string | 필수 생성 설명 또는 편집 지시, 최대 32,000자 |
| `quality` | string | auto / low / medium / high / xhigh / max; 기본 auto |
| `size` | string | auto 또는 WxH, 너비와 높이는 16의 배수. 모델 크기와 픽셀 제한 적용 |
| `n` | integer | 1–10; 기본 1 |
| `background` | string | auto / opaque / transparent; 투명 래스터 출력은 png 또는 webp |
| `output_format` | string | png / jpeg / webp; 기본 png |
| `output_compression` | integer | 0–100, 기본 100; JPEG / WebP 전용 |
| `moderation` | string | auto / low; 기본 auto |
| `safety_identifier` | string | 안정적인 해시 사용자 식별자, 최대 128자; user 대체 |
| `stream` | boolean | 기본 false. true이면 단일 JSON 대신 SSE 이벤트를 읽습니다 |
| `partial_images` | integer | 래스터 스트리밍 전용, 0–3, 기본 0. 요청한 미리보기 수보다 적게 반환될 수 있습니다 |
| `images` / `image[]` | array / file | JSON 필수: `images: [{"image_url": "HTTPS URL 또는 base64 data URI"}]`로 하나 이상의 참조 이미지 전달. multipart는 image\[] 파일 사용 |
| `markup` | object / file | 첫 번째 참조 이미지용 투명 PNG 오버레이. mask와 동시 사용 불가 |
| `mask` | object / file | 첫 번째 참조 이미지와 크기가 같고 alpha 채널이 있는 PNG 마스크. 완전히 투명한 영역이 편집 대상입니다. 첫 이미지에만 적용되며 markup와 함께 사용 불가 |

### images / markup / mask

JSON은 `images: [{"image_url": "https://..."}]` 또는 base64 data URI를 사용합니다. multipart는 image\[]로 파일을 업로드합니다. 플랫폼 연동 설명에 따르면 JSON 편집은 multipart로 변환되며 OpenAI file\_id 참조는 지원하지 않습니다.

첫 번째 입력 이미지의 방향 보정 후 크기와 일치하는 투명 PNG 마크업 레이어를 사용합니다. 투명 픽셀을 포함해야 합니다. JSON은 markup.image\_url, multipart는 markup 파일을 사용합니다. mask와 함께 사용할 수 없습니다.

편집 영역은 mask 또는 markup 중 하나로 지정합니다. JSON은 image\_url, multipart는 파일을 사용합니다.

## 요청 예시

예시는 터미널 환경 변수 GRAVITEX\_API\_KEY에서 플랫폼 토큰을 읽습니다. 업로드 시 curl -F가 Content-Type과 boundary를 자동 생성하므로 multipart/form-data 헤더를 직접 고정하지 마세요.

> [!NOTE]
>
> 접근 가능한 HTTPS URL 또는 base64 data URI를 사용하세요. multipart 예시는 공식 이미지를 먼저 다운로드합니다. 플랫폼 연동 설명은 OpenAI file\_id 참조를 지원하지 않습니다. 2.6의 과거 상태 코드를 2.5의 보장으로 간주하지 마세요.

### JSON

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

### multipart/form-data

```bash theme={null}
curl --fail --location "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp" -o kitchen.webp

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change the vase to blue. Keep everything else unchanged." \
  -F "image[]=@kitchen.webp"
```

### 마크업 편집

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ],
  "markup": {
    "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/markup-vase-overlay-gpt-image-2-6.png"
  }
}'
```

user는 호환성용이며 더 이상 권장되지 않습니다. safety\_identifier가 비어 있지 않으면 우선 사용하고 없거나 비어 있으면 user로 대체합니다.

### 마스크 부분 편집

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Add a pink flamingo float in the masked pool area. Keep the rest of the room unchanged.",
  "images": [
    {
      "image_url": "https://cdn.openai.com/API/docs/images/sunlit_lounge.png"
    }
  ],
  "mask": {
    "image_url": "https://cdn.openai.com/API/docs/images/mask.png"
  },
  "quality": "medium"
}'
```

### 스트리밍

```bash theme={null}
curl --no-buffer https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "stream": true,
  "partial_images": 1,
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

## 제한 및 참고 사항

size 기본값은 auto입니다. WxH의 각 변은 16의 배수이며 비율은 1:3–3:1 범위입니다. image-2 가이드는 최대 변 3840px, 총 픽셀 655,360–8,294,400을 명시하고 2.5 API 참조도 모델별 제한을 요구합니다. 특히 GIF를 포함한 2.6 예산은 기존 모델 상한을 그대로 적용하지 말고 확인하세요.

공식 Images API JSON 편집은 PNG, JPEG, WebP 참조 **1–16장**, 각 **50MB 미만**을 허용합니다. mask는 첫 참조와 크기가 같은 alpha 채널 PNG입니다. 투명 영역은 편집을 유도하지만 픽셀 단위 경계를 보장하지는 않습니다. 게이트웨이가 검증하지 않아도 상위 서비스 제한은 적용됩니다.

이 페이지는 공식 문서에서 명시한 GPT-Image-2.5 사용법을 다룹니다. 2.6의 complexity, GIF, SVG 설명을 2.5에 그대로 적용하지 않습니다. 공통 API schema에 필드가 있다고 모든 모델과 채널이 지원하는 것은 아닙니다.

## 응답 예시

다음은 비스트리밍 응답 구조 예시입니다. 이미지 데이터와 토큰 수는 실제 생성 결과가 아닙니다. b64\_json을 디코딩하여 해당 형식으로 저장하고 Base64 텍스트를 이미지 파일로 직접 저장하지 마세요.

```json theme={null}
{
  "created": 1794268800,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>"
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 824,
    "total_tokens": 924
  }
}
```

stream=true는 SSE 이벤트로 미리보기와 최종 이미지를 읽습니다. 전체 응답을 단일 JSON 객체로 파싱하지 마세요.

## 응답 및 과금

비스트리밍 예시는 b64\_json으로 이미지를 반환합니다. response\_format=url로 이미지 링크를 기대하지 마세요. 같은 토큰 단가가 이미지당 같은 비용을 뜻하지 않으므로 실제 usage를 확인하세요.

data\[].b64\_json과 usage를 반환합니다. 이미지는 Base64 디코딩 후 저장하세요. 아래는 OpenAI 표준 요금이며 GravitexAI 견적이 아닙니다.

캐시 요금은 공식 참고 가격입니다. 가이드에 따르면 GPT Image 2 / 2.5 캐시 입력 할인은 Responses 이미지 도구에만 적용되며 직접 Images API 호출(edits 포함)에는 적용되지 않습니다. 플랫폼 결제는 콘솔 기준입니다.

| 유형 | USD / 1M tokens |
| - | - |
| 텍스트 입력 | \$5.00 |
| 캐시 텍스트 입력 | \$1.25 |
| 이미지 입력 | \$8.00 |
| 캐시 이미지 입력 | \$2.00 |
| 이미지 출력 | \$30.00 |

## 공식 참고 문서

* [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
* [API Reference](https://developers.openai.com/api/reference/resources/images/methods/edit)
* [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)
* [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst)
* [Pricing](https://developers.openai.com/api/docs/pricing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.