# GPT Image 2.6 Flare · Token — /images/generations

GPT Image 2.6 Flare(토큰 과금): `gpt-image-2.6-flare`와 같은 모델이며, OpenAI가 보고하는 실제 토큰 사용량으로 과금하고 단가는 공식의 72%입니다. `xhigh`와 `max` 품질을 쓸 수 있고 `moderation: low`가 적용됩니다. 1K / 2K / 4K, 15가지 비율, 생성된 원본 그대로 전달, 실패 시 과금하지 않습니다. GIF는 아직 지원하지 않습니다.

**엔드포인트:** `POST https://kovapi.com/v1/images/generations`

## 빠른 시작

세 단계면 됩니다: 작업 제출 → 결과 조회 → 이미지 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.

**1단계 · 제출(작업 ID를 바로 돌려줍니다, HTTP 202)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "밝은 배경 위 흰색 도자기 머그잔을 담은 미니멀한 제품 사진, 부드러운 측면광", "size": "16:9", "resolution": "2K"}'
```

응답(HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare-token"
}
```

**2단계 · `status`가 `succeeded` 또는 `failed`가 될 때까지 2~3초마다 조회**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

성공했을 때의 응답

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare-token",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-flare-token"}
}
```

**3단계 · `data[0].url`이 이미지(PNG)입니다. 15일 동안 보관되므로 더 오래 쓰려면 내 저장소에 내려받아 두세요.**

**전체 예제(Python: 제출 → 대기 → 로컬에 저장)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 제출
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.6-flare-token",
    "prompt": "밝은 배경 위 흰색 도자기 머그잔을 담은 미니멀한 제품 사진, 부드러운 측면광",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 끝날 때까지 3초마다 조회
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 이미지 내려받기
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.6-flare-token.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## 인증
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 요청 파라미터

`POST /v1/images/generations`의 요청 본문(JSON):

| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| model | string | 예 | 모델 ID: `gpt-image-2.6-flare-token`. |
| prompt | string | 예 | 그릴 내용. 이미지-투-이미지에서는 무엇을 어떻게 바꿀지 적으세요. |
| size | string | 아니오 | 비율. 표의 15가지 중 하나(예: `16:9`). 픽셀 크기나 `auto`(참고 이미지가 있으면 첫 번째 이미지의 비율을 따름)도 쓸 수 있습니다. 지정하지 않으면 1:1입니다. |
| resolution | string | 아니오 | 등급: `1K`(기본값), `2K`, `4K`. |
| quality | string | 아니오 | 품질: `low`, `medium`(기본값), `high`, `xhigh`, `max`, `auto`(모델이 결정). 품질이 높을수록 토큰이 많아지며 같은 크기에서 medium의 약 0.57 / 1 / 1.21 / 2.1 / 4.8배입니다. |
| image / images | string / array | 아니오 | 참고 이미지. 보내면 이미지-투-이미지가 됩니다. `image`는 한 장, `images`는 여러 장(최대 16장). 공개 링크, data: URI, base64를 쓸 수 있습니다. |
| n | integer | 아니오 | 이미지 장수. 넣지 않는 것을 권장합니다. 여러 장이 필요하면 작업 여러 개를 동시에 제출하세요. `n`을 넣으면 n장 분의 크레딧을 미리 예약하고, 실제로 전달된 장수만큼 과금합니다. |
| callback_url | string | 아니오 | 작업이 끝나면 결과를 보낼 주소. 아래 웹훅 부분을 보세요. |
| complexity | string | 아니오 | 구상 정도: `low`, `medium`, `high`. 토큰 과금 버전에서는 아직 적용되지 않으며(보내도 오류는 아님) 가격도 바뀌지 않습니다. |
| moderation | string | 아니오 | 검열 강도: `auto`(기본값) 또는 `low`(조금 완화, OpenAI 콘텐츠 정책 범위 안). |
| output_compression | integer | 아니오 | 압축 정도. 0–100 정수이며 `jpeg` / `webp` 출력에만 적용됩니다. 작을수록 파일이 작아집니다. |
| mask_url | string | 아니오 | 부분 수정용 마스크: 첫 번째 참고 이미지와 같은 크기의 PNG이며 투명한 부분이 바꿀 영역입니다. 참고 이미지가 필요하고 `markup_url`과 함께 쓸 수 없습니다. 모델은 마스크를 참고하지만 투명 영역만 엄격히 바꾼다고 보장하지 않습니다. |
| markup_url | string | 아니오 | 마크업 레이어: 바꿀 위치에 동그라미나 표시를 한 투명 PNG로, 첫 번째 참고 이미지 위에 겹칩니다. 프롬프트에 무엇을 할지 적어 주세요(예: "빨간 원 안의 꽃병을 파란색으로 바꾸고 원은 지워 줘"). 참고 이미지가 필요하고 `mask_url`과 함께 쓸 수 없으며 최대 1677만 픽셀입니다. |

`background`에 `transparent`(투명 배경, PNG 또는 WebP 출력과 함께 사용)를 지정할 수 있습니다. `output_format`은 `png`(기본값), `jpeg`, `webp`. `n`은 1만 가능합니다. 표에 없는 파라미터는 제출 시 400 `unsupported_image_parameter`를 반환하고 과금하지 않습니다. 결과는 `url`로 반환되며 `usage`에 이번 작업의 토큰 수와 과금액이 있습니다.

## 토큰 과금

제출 시 크기·품질·참고 이미지 수로 상한액을 먼저 묶어 두고, 생성 후 OpenAI가 보고한 실제 사용량으로 정산해 남은 금액은 바로 돌려드립니다. 실패 시 전액 환불됩니다. 100만 토큰당 가격:

| 항목 | 당사 가격 | OpenAI 공식 가격 |
| --- | --- | --- |
| 이미지 출력 | $21.6 | $30 |
| 이미지 입력(참고 이미지) | $5.76 | $8 |
| 텍스트 입력 | $3.6 | $5 |

**실측 출력 토큰과 비용(입력 제외)**

| size | quality | output tokens | USD |
| --- | --- | --- | --- |
| 1024x1024 | low | 824 | $0.018 |
| 1024x1024 | medium | 1,449 | $0.031 |
| 1024x1024 | high | 1,758 | $0.038 |
| 1024x1024 | xhigh | 3,122 | $0.067 |
| 1024x1024 | max | 7,024 | $0.152 |
| 2048x2048 | medium | 2,944 | $0.064 |
| 2048x2048 | max | 14,272 | $0.308 |
| 3840x2160 | medium | 2,855 | $0.062 |
| 3840x2160 | max | 13,342 | $0.288 |
| 3840x1280 | medium | 1,096 | $0.024 |

같은 크기와 품질이면 출력 토큰은 프롬프트와 상관없이 매번 같습니다. 참고 이미지는 장당 약 700–1,600 이미지 입력 토큰입니다.

## 비율, 해상도와 출력 크기

`size`에 비율, `resolution`에 단계를 지정합니다. 생성된 원본 이미지를 자르거나 크기를 바꾸지 않고 아래 표의 크기 그대로 전달합니다. 가로·세로는 모두 16의 배수이며, 4K는 한 변 3840px, 총 약 830만 화소 이내입니다.

| 비율 | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:4 | 768x1024 | 1536x2048 | 2480x3312 |
| 4:3 | 1024x768 | 2048x1536 | 3312x2480 |
| 2:3 | 672x1024 | 1360x2048 | 2336x3520 |
| 3:2 | 1024x672 | 2048x1360 | 3520x2336 |
| 9:16 | 608x1088 | 1152x2048 | 2160x3840 |
| 16:9 | 1088x608 | 2048x1152 | 3840x2160 |
| 4:5 | 816x1024 | 1632x2048 | 2576x3216 |
| 5:4 | 1024x816 | 2048x1632 | 3216x2576 |
| 1:2 | 576x1152 | 1024x2048 | 1920x3840 |
| 2:1 | 1152x576 | 2048x1024 | 3840x1920 |
| 9:21 | 544x1264 | 880x2048 | 1648x3840 |
| 21:9 | 1264x544 | 2048x880 | 3840x1648 |
| 1:3 | 480x1440 | 672x2016 | 1280x3840 |
| 3:1 | 1440x480 | 2016x672 | 3840x1280 |

- 표의 15가지 비율을 지원하며, 다른 비율은 제출 시 400을 반환하고 과금하지 않습니다. `size`를 `auto`로 하고 참고 이미지를 보내면 첫 번째 참고 이미지와 가장 가까운 비율로 생성하고, 참고 이미지가 없으면 1:1입니다. 1K의 일부 가늘고 긴 비율은 모델의 최소 픽셀 수보다 작아 표의 확대된 크기로 생성합니다(16:9는 1088×608).

- `size`에 픽셀 크기(예: `1536x1024`)도 쓸 수 있으며 비율은 표의 15가지 중 하나여야 합니다. 너비와 높이는 16의 배수로 내림하고, 단계 상한을 넘으면 비율대로 축소, 너무 작으면 모델의 최소 픽셀 수(약 65.5만)까지 비율대로 확대합니다. 단계는 `resolution`으로 정하며, 없으면 긴 변으로 판단합니다: 1536 이하는 1K, 2048 이하는 2K, 그보다 크면 4K. 긴 변 범위는 1K 512–1536, 2K 2016–2304, 4K 2049–4096이며 벗어나면 제출 시 400을 반환하고 과금하지 않습니다.

## 화질과 네이티브 해상도

- `quality`를 지정하지 않으면 medium으로 생성합니다. 품질은 토큰 수와 가격만 바꾸고 크기는 바꾸지 않습니다. `auto`는 모델이 결정하며 선결제는 `max` 기준으로 잡고 정산은 실제 사용량으로 합니다.

- `quality`에 `1K`, `2K`, `4K`를 넣고 `resolution`을 보내지 않으면 해상도 등급으로 처리합니다(크기와 가격 모두 그 등급을 따릅니다).

- 붐비는 시간에는 작업이 바로 실패하지 않고 대기합니다. 오래 기다려도(약 15분) 이미지가 나오지 않으면 실패 처리하고 전액 환불하며, 그대로 다시 제출할 수 있습니다.

## 이미지-투-이미지와 참조 이미지

- `image`(한 장) 또는 `images`(여러 장, 최대 16장, 초과분은 사용하지 않음)를 보내면 이미지-투-이미지가 됩니다. 프롬프트에 무엇을 바꿀지 적어 주세요. `POST /v1/images/edits`도 같은 파라미터를 받습니다.

- 두 엔드포인트 모두 JSON 본문만 받고 multipart 파일 업로드는 받지 않습니다. 그래서 OpenAI SDK의 `images.edit()`은 그대로 쓸 수 없으니, 아래 예시처럼 링크나 base64를 보내세요.

- 참고 이미지는 각각 공개 링크(http / https), data: URI 또는 일반 base64이며 장당 16MB 이하, PNG·JPEG·WebP만 가능합니다. 다른 형식의 참고 이미지는 작업이 실패하고 전액 환불됩니다.

- URL은 이미지 파일 자체를 내려받을 수 있어야 합니다. 웹 페이지, 로그인이 필요한 주소, 핫링크 방지가 걸린 주소는 안 됩니다. 읽을 수 없는 참조 이미지는 제출할 때 바로 400으로 거절되며, 몇 번째 이미지인지와 이유가 함께 표시됩니다. 작업은 만들어지지 않고 과금되지 않습니다.

- 출력 비율은 참조 이미지가 아니라 `size`로 정해집니다. 원본 비율을 유지하려면 `size`를 원본과 같은 비율로 지정하세요.

- 참조 이미지는 당사가 대신 호스팅하며 7일 동안 보관합니다.

**참조 이미지 2장으로 이미지-투-이미지**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "인물은 그대로 두고 배경을 따뜻한 줄조명이 걸린 밤 해변으로 바꾸기", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## 작업 상태와 응답 필드

`GET /v1/images/jobs/{id}`는 아래 상태를 돌려줍니다. 각 필드의 설명은 [비동기 작업](https://docs.kovapi.com/ko/guide/async-jobs#fields)에 있습니다. 2~3초마다 조회하거나 웹훅을 쓰세요.

| 상태 | 의미 |
| --- | --- |
| queued | 대기 중. `queue_position`(앞에 있는 작업 수)과 `eta_seconds`(예상 대기 시간)가 함께 옵니다. |
| processing | 생성 중. |
| succeeded | 완료. 결과는 `data[0].url`, 과금 내역은 `usage`에 있습니다. |
| failed | 실패. 사유는 `error`에 있고, 예약된 크레딧은 전액 환불됩니다. |

한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 이미지 링크는 15일 동안 보관됩니다.

## 생성 시간

제출부터 결과까지 보통 20–60초입니다. 4K, 여러 참조 이미지를 쓰는 편집, 혼잡한 시간대에는 더 걸리며 가끔 1–2분 걸리는 작업도 있습니다.

## 오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 [오류 코드](https://docs.kovapi.com/ko/guide/errors)에 있습니다.

### 제출할 때 돌아오는 오류

| HTTP | code | 원인 | 조치 |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` 요청에 `prompt`가 없습니다. | `prompt`를 추가하세요. |
| 400 | invalid_request | 참조 이미지를 읽을 수 없거나(링크가 열리지 않음, 이미지가 아님, 16MB 초과 등. `message`에 몇 번째인지와 이유가 적혀 있습니다), `/v1/images/edits`에 참조 이미지가 없거나, 요청 본문이 JSON 객체가 아니거나, `n`이 정수가 아닙니다. | `message`에 적힌 대로 고친 뒤 다시 제출하세요. |
| 400 | model_not_found | 모델 ID의 철자가 틀렸거나, `model`이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우). | `GET /v1/models` 또는 [API 레퍼런스](https://docs.kovapi.com/ko/api)에 있는 모델 ID를 쓰세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 [서비스 상태](https://kovapi.com/ko/status)에서 볼 수 있습니다. |
| 503 | service_unavailable | 참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. `/v1/responses`는 잠시 요청을 처리할 수 없을 때도 `Retry-After`와 함께 503을 돌려줍니다. | 잠시 후 다시 시도하세요. |

### 작업 실패(`status`가 `failed`)

| code | 언제 나오나요 | 조치 |
| --- | --- | --- |
| moderation_blocked | 이미지: 모델 제공사의 안전 시스템이 프롬프트나 참조 이미지를 거부했습니다(코드가 `content_policy_violation`일 수도 있습니다). | 프롬프트를 고쳐 쓰거나 참조 이미지를 바꾸세요. 그대로 다시 제출하면 대개 다시 거부됩니다. |
| upstream_error | 그 밖의 실패: 자동 재시도 후에도 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 `message`에 있습니다. | 다시 제출하면 대개 성공합니다. |

## 조회 대신 웹훅으로 받기

제출할 때 `callback_url`을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. [웹훅 문서 →](https://docs.kovapi.com/ko/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "밝은 배경 위 흰색 도자기 머그잔을 담은 미니멀한 제품 사진, 부드러운 측면광", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```