GPT Image 2.6 Sunburst · 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", "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"
}

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",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-sunburst"}
}

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",
    "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.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만 가능하며, 여러 장이 필요하면 작업을 동시에 여러 개 제출하세요. 그 밖의 파라미터(response_format, style 등)는 가격에 영향을 주지 않으며 적용도 보장되지 않습니다. 결과는 url로 반환됩니다.

가격

장당 과금이며 가격은 등급으로만 정해집니다. 비율이나 텍스트-투-이미지 / 이미지-투-이미지 여부와는 관계없습니다. 제출할 때 등급 가격만큼 예약되고, 작업이 실패하면 전액 환불됩니다. 1크레딧 = $0.005.

비율, 해상도와 출력 크기

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

• 표의 7가지 비율만 사용할 수 있으며, 그 밖의 비율은 제출 시 400으로 거절되고 요금이 부과되지 않습니다. 1K의 16:9와 9:16은 모델의 최소 화소 수보다 작아서 1088×608과 608×1088로 출력됩니다.
• size에는 픽셀 크기(예: 1536x1024)도 쓸 수 있으며, 비율은 표의 7가지 중 하나여야 합니다. 가로·세로는 16의 배수로 내림하고, 해당 단계의 상한을 넘으면 비율대로 줄이며, 너무 작으면 모델의 최소 화소 수(약 65.5만)까지 비율대로 키웁니다. 단계는 resolution으로 정하며, 없으면 긴 변으로 판단합니다(1536 이하는 1K, 2048 이하는 2K, 그보다 크면 4K). 긴 변 허용 범위는 1K 512–1536, 2K 2048–2304, 4K 2049–4096이며, 벗어나면 제출 시 400으로 거절되고 요금이 부과되지 않습니다.

화질과 네이티브 해상도

• quality를 보내지 않으면 medium으로 생성합니다. low, medium, high는 1K / 2K / 4K 모두에서, 텍스트-투-이미지와 이미지-투-이미지 모두에 적용되며 가격은 해상도 단계로만 정해집니다. auto는 medium으로 처리합니다. xhigh와 max는 아직 제공하지 않으며, 지정하면 제출 시 400으로 거절되고 요금이 부과되지 않습니다.
• quality에 1K, 2K, 4K를 넣고 resolution을 보내지 않으면 해상도 등급으로 처리합니다(크기와 가격 모두 그 등급을 따릅니다).
• 네이티브로 생성하는 등급은 항상 네이티브로 생성합니다. 붐비면 작업이 대기열에서 기다리고, 그래도 생성하지 못하면 실패 처리하고 전액 환불합니다. 1K 이미지를 확대해 대신 내주지 않습니다.

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

• image(한 장) 또는 images(여러 장, 최대 5장)를 보내면 이미지-투-이미지로 실행됩니다. 무엇을 어떻게 바꿀지 prompt에 적어 주세요. 5장을 넘으면 제출 시 400으로 거절되고 요금이 부과되지 않습니다. POST /v1/images/edits도 같은 파라미터를 받습니다.
• 두 엔드포인트 모두 JSON 본문만 받고 multipart 파일 업로드는 받지 않습니다. 그래서 OpenAI SDK의 images.edit()은 그대로 쓸 수 없으니, 아래 예시처럼 링크나 base64를 보내세요.
• 각 참조 이미지는 공개 이미지 URL(http / https), data: URI 또는 순수 base64일 수 있으며 장당 16MB 이하, 형식은 PNG 또는 JPEG만 가능합니다. 다른 형식의 참조 이미지가 있으면 작업이 실패하고 전액 환불됩니다.
• 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", "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", "prompt": "해 질 녘 항구를 그린 유화, 뚜렷한 붓 자국, 따뜻한 색감", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'