GPT Image 2.6 Sunburst · Token · API

빠른 시작

세 단계면 됩니다: 작업 제출 → 결과 조회 → 이미지 링크 받기. 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-sunburst-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-sunburst-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-sunburst-token",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-sunburst-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-sunburst-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-sunburst-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

콘솔에서 API 키를 만들면 시작할 수 있습니다.

요청 파라미터

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

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

토큰 과금

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

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

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

비율, 해상도와 출력 크기

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

• 표의 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-sunburst-token", "prompt": "인물은 그대로 두고 배경을 따뜻한 줄조명이 걸린 밤 해변으로 바꾸기", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

작업 상태와 응답 필드

GET /v1/images/jobs/{id}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 2~3초마다 조회하거나 웹훅을 쓰세요.

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

생성 시간

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

오류와 환불

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

제출할 때 돌아오는 오류

작업 실패(status가 failed)

조회 대신 웹훅으로 받기

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

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-sunburst-token", "prompt": "해 질 녘 항구를 그린 유화, 뚜렷한 붓 자국, 따뜻한 색감", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'