> ## 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.6 이미지 생성

> Flare와 Sunburst로 이미지를 비동기 생성·편집하고, 마크업 편집, GIF 애니메이션, SVG 출력을 사용하세요.

텍스트 기반 생성, 이미지 편집, GIF, SVG 모두 `POST /v1/images/generations`를 사용합니다. 제출 응답에서 `data[0].task_id`를 읽고 작업을 조회해 파일 URL을 받습니다.

```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.6-flare",
  "prompt": "A cozy reading nook by a rainy window, warm lamp light",
  "size": "1:1",
  "resolution": "1k",
  "quality": "medium",
  "n": 1
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "A cozy reading nook by a rainy window, warm lamp light",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1
    },
)
response.raise_for_status()
print(response.json()["data"][0]["task_id"])
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-image-2.6-flare",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result.data[0].task_id);
```

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

## 인증

**Authorization** `string` *required*

Bearer Token 인증을 사용합니다. [API 키 관리 페이지](https://apimart.ai/keys)에서 키를 발급받으세요.

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## 모델 선택

| 모델 | 용도 |
| - | - |
| `gpt-image-2.6-flare` | 속도를 우선하는 빠른 반복 작업에 적합하며 기본 선택으로 권장합니다. |
| `gpt-image-2.6-sunburst` | 세부 묘사와 편집 일관성을 우선하며, 특히 `medium` / `high` 품질의 반복 편집에 적합합니다. |

두 모델은 동일한 설정에서 토큰 단가와 사용량이 같습니다. 속도와 세부 묘사 요구에 따라 선택하세요.

## 요청 매개변수

**model** `string` *required*

모델 이름: `gpt-image-2.6-flare` 또는 `gpt-image-2.6-sunburst`.

**prompt** `string` *required*

생성 또는 편집 지침으로 최대 32,000자입니다. 대상, 구도, 변경하거나 유지할 내용을 설명하세요.

**size** `string` (default: auto)

정지 이미지와 SVG는 15가지 비율, `1600x1200` 같은 픽셀 크기, `auto`를 지원합니다. 명시적 `auto`는 업스트림이 결정합니다. 편집 시 생략하면 첫 입력 이미지의 비율과 `resolution`으로 크기를 선택합니다. GIF는 아래 별도 규칙을 따릅니다.

**resolution** `string` (default: 1k)

소문자 `1k` / `2k` / `4k`. 비율 형식의 `size`와 함께 픽셀 크기를 결정하며, 정확한 픽셀 크기 지정 시 무시됩니다.

**quality** `string` (default: auto)

`low` / `medium` / `high` / `xhigh` / `max` / `auto`. 다른 값은 제출 시 HTTP 400을 반환합니다. 생략하거나 `auto`로 지정하면 모델이 품질 단계를 자동으로 선택합니다. 선택된 단계는 달라질 수 있으며 `low`로 고정되지 않습니다. 고정된 단계가 필요하면 명시적으로 지정하세요.

생략하거나 `auto`로 지정하면 `max` 단계 기준으로 비용을 사전 확보하고, 실제 선택된 품질 단계에 따라 최종 정산합니다.

**n** `integer` (default: 1)

`1`–`4` 사이의 정수. GIF에서는 애니메이션 수를 뜻합니다. SVG는 `1`만 지원합니다. 명시적인 `0`, 음수 또는 `4`보다 큰 값은 기본값으로 대체되지 않고 HTTP 400을 반환합니다.

**output\_format** `string` (default: png)

`png` / `jpeg` / `webp` / `gif` / `svg`. GIF와 SVG는 텍스트 기반 생성만 지원합니다. 다른 값은 제출 시 HTTP 400을 반환합니다.

**output\_compression** `integer`

`0`–`100` 사이의 정수이며 `jpeg` / `webp`만 지원합니다. 범위를 벗어나거나 `png` / `gif` / `svg`와 함께 사용하면 제출 시 HTTP 400을 반환합니다.

**background** `string`

`transparent` / `opaque` / `auto`. 생략하면 업스트림 기본값을 사용합니다. 명시적인 `transparent`는 `png` / `webp`만 지원합니다. SVG는 기본 배경이 투명하므로 이 필드를 생략하세요.

**moderation** `string` (default: low)

콘텐츠 검토 수준: `auto` / `low`. 다른 값은 제출 시 HTTP 400을 반환합니다.

**image\_urls** `string[]`

최대 16장의 참조 이미지이며 지정하면 편집 모드가 됩니다. 공개 접근 가능한 HTTP(S) 이미지 URL을 사용하세요. 로컬 파일은 [이미지 업로드 API](https://docs.apimart.ai/ko/api-reference/uploads/images.md)에 먼저 업로드한 뒤 반환된 `url`을 전달합니다.

**mask\_url** `string`

부분 편집 마스크이며 `image_urls`가 필요합니다. 첫 이미지와 크기가 같은 알파 채널 PNG를 사용하며 완전히 투명한 영역이 편집 대상입니다. 이미지 URL 또는 PNG Data URL을 지원합니다. 마크업과 함께 사용할 수 없으며 마스크 밖 픽셀의 완전한 보존은 보장하지 않습니다.

**complexity** `string`

계획 강도: `low` / `medium` / `high`. 업스트림 기본값은 `high`이며 렌더링 `quality`와 독립적입니다. 국소 수정에는 `low`, 많은 텍스트·복잡한 배치·객체 관계에는 `high`가 적합하지만 느려지거나 추가 변경이 생길 수 있습니다. 별도 요금은 없으며 2.6만 지원합니다.

**safety\_identifier** `string`

선택 사항인 안정적인 최종 사용자 식별자, 최대 128자. 사용자명이나 이메일의 해시를 권장합니다. APIMart는 기본적으로 업스트림에 전달하지 않으며 채널이 허용할 때만 전달합니다. 생략해도 사용에 영향이 없습니다.

## 정지 이미지 및 SVG 크기

정확한 픽셀 크기는 가로·세로 모두 16의 배수, 각 변 최대 3840, 긴 변과 짧은 변의 비율 최대 3:1, 전체 픽셀 655,360–8,294,400이어야 합니다. 2560×1440을 초과하는 해상도는 실험적입니다. 아래 매핑은 GPT-Image-2.5와 같으며 이 정지 이미지 제한을 GIF 개별 프레임에 직접 적용하지 마세요.

| `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 |

## 이미지 편집과 마스크

다음 요청은 첫 이미지를 부분 편집합니다. `mask_url`을 생략하면 프롬프트에 따라 전체 이미지를 편집하고, `size`를 생략하면 첫 이미지 비율과 `resolution`으로 출력 크기를 선택합니다. 예제 URL은 접근 가능한 실제 이미지로 교체하세요.

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Replace the fully transparent masked area with a gold ribbon. Preserve the product and the rest of the background.",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "resolution": "2k",
  "quality": "high",
  "complexity": "low"
}
```

## 마크업 기반 편집

`markup_url`에 HTTPS 또는 Base64 Data URL을 전달합니다. 별칭 `markup`은 문자열이나 `{"image_url":"..."}` 객체를 받습니다. `file_id`는 지원하지 않습니다.

* `image_urls`가 필수입니다. 마크업은 첫 이미지에 적용되고 나머지는 참조로 사용됩니다.
* 첫 이미지와 정확히 같은 크기의 별도 투명 PNG 레이어를 사용하세요. 원본에 표시를 합성하지 마세요.
* 첫 이미지와 레이어는 각각 최대 16,777,216픽셀이며 레이어 파일은 최대 50 MB입니다.
* `mask_url`과 함께 사용할 수 없습니다. 레이어에는 이미지 토큰이 부과되지 않지만 추가 텍스트 토큰이 발생할 수 있습니다.

```json theme={null}
{
  "model": "gpt-image-2.6-flare",
  "prompt": "Recolor the striped vase inside the red circle to solid cobalt blue ceramic. Keep everything else unchanged. Remove the red circle.",
  "image_urls": [
    "https://example.com/kitchen.webp"
  ],
  "markup_url": "https://example.com/vase-circle-overlay.png",
  "quality": "medium"
}
```

## GIF 애니메이션

`output_format: "gif"`로 설정합니다. 텍스트 기반 생성만 지원하므로 `image_urls`, `mask_url`, `markup_url`, `markup`, `output_compression`을 전달하지 마세요.

| 매개변수 | 기본값 | 설명 |
| - | - | - |
| `frame_count` | `9` | 정수 **2–16**. APIMart의 현재 상한은 16이며 업스트림 가이드의 64프레임 제한은 적용되지 않습니다. |
| `frame_duration_ms` | `200` | 프레임별 표시 시간, 정수 밀리초. 최소 20이며 10 ms 단위로 반올림됩니다. |
| `size` | `auto` | **각 프레임**의 픽셀 크기이며 가로·세로는 16의 배수입니다. 생략 또는 `auto`는 현재 512×512입니다. `1:1` 같은 비율 이름은 지원하지 않습니다. |

업스트림은 프레임을 시트에 배치합니다. 2–8프레임은 4×2, 9프레임은 3×3, 10–12프레임은 4×3, 13–16프레임은 4×4입니다. 정사각형에 가깝게 행과 열을 바꿀 수 있습니다. 전체 시트의 각 변은 최대 3840, 총 픽셀은 최대 8,294,400, 긴 변과 짧은 변의 비율은 최대 3:1이어야 하며 초과 시 제출 단계에서 400을 반환합니다.

> [!WARNING]
>
> `512x512`는 2–16프레임 모두, `768x768`는 최대 12프레임을 지원합니다. `1024x1024`는 2프레임만으로도 시트 변 길이 상한을 초과합니다. 각 애니메이션의 전체 시트를 기준으로 과금하며 `n > 1`이면 여러 애니메이션을 생성하고 각각 과금합니다.

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A paper lantern swaying gently in the night breeze, seamless loop",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "quality": "low"
}
```

## SVG 출력

**svg** `object`

`output_format: "svg"`로 설정합니다. 이미지 모델이 참조 이미지를 생성한 다음 `svg.model`의 텍스트 모델이 SVG를 작성합니다.

**svg**

**model** `string` *required*

필수. `gpt-5.4-mini`, `gpt-5.6-sol` 등 플랫폼에 텍스트 토큰 요금이 있는 모델을 선택하세요.

**reasoning** `object`

**reasoning**

**effort** `string`

선택 사항: `none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`. 지원 값은 텍스트 모델마다 다릅니다. 생략해 모델 기본값을 사용하는 것을 권장합니다.

* 텍스트 기반 생성만 지원하며 `n`은 1이어야 합니다. 참조 이미지, 마스크, 마크업, `output_compression`은 사용할 수 없습니다.
* `quality`와 `complexity`는 중간 참조 이미지에 적용됩니다. 결과는 스크립트, 외부 리소스, 내장 비트맵이 없는 정적 `.svg`입니다.
* 이미지 생성 비용 외에 `svg.model`의 텍스트 사용량이 추가 과금됩니다. 이미지당 고정 요금 계약 계정은 현재 SVG를 지원하지 않아 제출 시 400을 반환합니다.

```json theme={null}
{
  "model": "gpt-image-2.6-flare",
  "prompt": "A minimalist bakery logo with a wheat stalk, flat colors",
  "output_format": "svg",
  "svg": {
    "model": "gpt-5.4-mini"
  },
  "size": "1:1",
  "quality": "low",
  "n": 1
}
```

## 작업 결과 조회

[작업 조회 API](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 2–5초마다 호출해 `completed` 또는 `failed`까지 확인하세요. 대기 중 생성 요청을 반복 제출하지 마세요.

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

완료되면 `data.result.images[].url[]`에서 파일 URL을 읽어 바로 저장하세요. 아래 예시는 주요 필드만 표시합니다. `failed`일 때는 `data.error.message`를 확인하세요. 여러 작업은 `POST /v1/tasks/batch`로 일괄 조회할 수 있습니다.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.png"
          ]
        }
      ]
    }
  }
}
```

### SVG 사용량과 응답 예제

작업 조회 응답의 `data.usage.svg_usage`는 SVG를 작성하는 텍스트 모델의 사용량입니다. `data.usage`의 나머지 토큰 필드는 참조 이미지를 생성하는 이미지 모델의 사용량입니다. 각 부분을 해당 모델의 과금 규칙에 따라 별도로 집계하세요.

| 필드 | 유형 | 설명 |
| - | - | - |
| `model` | string | SVG 작성에 실제 사용된 텍스트 모델. |
| `input_tokens` | integer | 텍스트 모델의 입력 토큰 수. |
| `output_tokens` | integer | 텍스트 모델의 출력 토큰 수로, 추론 토큰이 포함됩니다. |
| `reasoning_tokens` | integer | 출력 토큰 중 추론에 사용된 부분입니다. `output_tokens`에 다시 더하지 마세요. |

다음은 SVG 작업 응답의 주요 필드입니다. 토큰 수는 필드 관계를 설명하기 위한 예시이며 고정 사용량을 뜻하지 않습니다.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.svg"
          ]
        }
      ]
    },
    "usage": {
      "input_tokens": 40,
      "output_tokens": 1800,
      "total_tokens": 1840,
      "svg_usage": {
        "model": "gpt-5.4-mini",
        "input_tokens": 1200,
        "output_tokens": 800,
        "reasoning_tokens": 200
      }
    }
  }
}
```

## 자주 발생하는 매개변수 오류

다음 매개변수 검증 오류는 제출 시 동기적으로 HTTP 400을 반환합니다. 작업이 생성되지 않고 요금도 부과되지 않습니다. 매개변수를 수정한 뒤 다시 제출하세요.

| 오류 | 해결 방법 |
| - | - |
| `quality "ultra" is not supported by gpt-image-2.6-flare` | `low` / `medium` / `high` / `xhigh` / `max` / `auto`를 사용하세요. `ultra` 같은 다른 값은 지원하지 않습니다. |
| `` `n` must be an integer from 1 to 4 `` | `n`을 1–4 사이의 정수로 지정하세요. `0`, 음수, 4보다 큰 값은 유효하지 않습니다. |
| `output_compression must be an integer from 0 to 100` | `output_compression`을 0–100 사이의 정수로 지정하세요. |
| `output_compression is only supported with output_format jpeg or webp` | 압축은 JPEG / WebP에서만 사용하세요. PNG / GIF / SVG 요청에서는 이 매개변수를 제거하세요. |
| `moderation "xxx" is not supported` | `moderation`을 `low` 또는 `auto`로 설정하세요. |
| `markup requires image_urls` | `image_urls`를 추가하고 레이어를 첫 이미지에 맞추세요. |
| `markup cannot be combined with mask` | 마크업 또는 마스크 중 하나만 사용하세요. |
| `frame_count must be an integer from 2 to 16` | `frame_count`를 2–16 사이의 정수로 설정하세요. |
| `no supported sheet fits N GIF frames at size WxH` | 프레임 크기나 개수를 줄이세요. 비율 이름은 사용할 수 없습니다. |
| `output_format=svg requires svg.model` | 지원하는 텍스트 모델을 지정한 `svg` 객체를 추가하세요. |
| `output_format=svg requires n=1` | SVG는 `n: 1`로 설정하세요. |
| `background=transparent requires an alpha-capable output_format` | 명시적인 투명 배경은 PNG / WebP만 지원합니다. SVG에서는 생략하세요. |

## 미지원 매개변수와 과금

`stream`, `partial_images`, `input_fidelity`, `prompt_rewriter`, `response_format`을 전달하지 마세요. 이 API는 비동기 작업과 CDN URL을 반환하며 부분 이미지 스트리밍이나 Base64 이미지 응답은 제공하지 않습니다. `frame_count` / `frame_duration_ms`는 GIF 전용, `svg` 설정은 SVG 전용입니다.

Flare와 Sunburst의 과금 기준은 같습니다. 2.6의 `low` / `medium`은 2.5보다 토큰을 많이 사용하므로 기존 비용 추정을 그대로 적용하지 마세요. 최신 요금은 [APIMart 가격 페이지](https://apimart.ai/pricing) 또는 `/api/pricing`을 참고하세요. 이 페이지에는 고정 가격을 기재하지 않습니다.

업스트림 기능 설명은 [OpenAI 이미지 생성 가이드](https://developers.openai.com/api/docs/guides/image-generation)를 참고하세요. APIMart 호출 시 엔드포인트, 비동기 응답, 매개변수 제한은 이 페이지를 따릅니다.


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