GPT Image 2.5 Flare · API

빠른 시작

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

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

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

응답(HTTP 202)

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

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

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

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

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

import time
import requests

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

# 1. 제출
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.5-flare",
    "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.5-flare.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):

그 밖의 OpenAI 파라미터(background, output_format, response_format, style 등)는 가격에 영향을 주지 않으며 적용된다는 보장도 없습니다. 결과는 항상 PNG이며 url로 돌려줍니다.

가격

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

비율, 해상도와 출력 크기

비율은 size에, 등급은 resolution에 넣습니다. 이미지는 표의 크기 그대로 전달됩니다. 긴 변은 등급으로 정해지고 다른 변은 비율에 따라 계산됩니다. 표에 없는 비율도 같은 규칙으로 쓸 수 있습니다.

• 1K에서는 모델이 가장 가까운 가로형, 세로형, 정사각형 구도로 그리고, 게이트웨이가 이를 가운데 기준으로 잘라 표의 크기로 맞춥니다. 그래서 비율이 3:2, 2:3, 1:1에서 멀수록 가장자리가 더 많이 잘립니다. 게이트웨이는 피사체가 잘리지 않고 가운데에 오도록 프롬프트 뒤에 비율을 설명하는 문장(영어)을 덧붙입니다. 꼭 남아야 하는 내용은 가장자리에서 떨어진 곳에 두세요.
• 네이티브로 생성하는 등급(아래 「화질과 네이티브 해상도」 참고)은 요청한 비율로 바로 그리므로 가장자리가 잘리지 않습니다.
• size에는 픽셀 크기(예: 1536x1024)도 쓸 수 있으며, 이미지는 그 크기 그대로 전달됩니다(긴 변이 4096을 넘으면 비율을 유지한 채 줄입니다). 이때 등급은 resolution으로 정해지고, resolution이 없으면 긴 변으로 정해집니다: 1536 이하는 1K, 2048 이하는 2K, 그보다 크면 4K. resolution은 등급을 올릴 수만 있고 내릴 수는 없으며, 전달 크기도 바꾸지 않습니다. 그러니 작은 크기와 높은 등급을 함께 쓰지 마세요.

화질과 네이티브 해상도

• quality를 보내지 않으면 OpenAI의 medium 디테일로 생성합니다. 1K에서는 low, medium, high를 고를 수 있으며 텍스트-투-이미지와 이미지-투-이미지 모두 적용됩니다. 2K와 4K는 항상 medium으로 생성합니다. auto, xhigh, max 등 그 밖의 값은 medium으로 처리하며 오류가 나지 않습니다. 가격은 해상도 등급으로만 정해지며 quality와는 관계없습니다.
• quality에 1K, 2K, 4K를 넣고 resolution을 보내지 않으면 해상도 등급으로 처리합니다(크기와 가격 모두 그 등급을 따릅니다).
• 1K는 모델 고유의 화면(약 157만 화소, 정사각형은 1254×1254)으로 생성하고, 게이트웨이가 위 표의 크기로 맞춥니다.
• 2K와 4K는 요청한 비율로 네이티브 생성합니다. 한 변 최대 3840px, 총 약 830만 화소까지입니다. 2K 1:1은 그대로 2048×2048, 4K 16:9는 3840×2160, 4K 1:1은 2880×2880으로 나옵니다. 표의 4K 크기가 이보다 크면 게이트웨이가 그만큼 확대합니다(16:9는 각 변 약 7%, 정사각형에 가까울수록 더 많이). 네이티브 화소를 그대로 받으려면 size에 한도 안의 픽셀 크기(예: 3840x2160)를 넣으세요.
• 네이티브로 생성하는 등급은 네이티브 회선에서만 실행합니다. 회선이 붐비면 작업이 대기열에서 기다리고, 그래도 생성하지 못하면 실패 처리하고 전액 환불합니다. 1K 이미지를 확대해 대신 내주지 않습니다.
• 1K 작업은 가끔 예비 회선에서 마무리되며, 이때는 quality가 적용되지 않을 수 있습니다.

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

• image(한 장) 또는 images(여러 장, 최대 8장이며 8장을 넘는 것은 쓰지 않음)를 보내면 이미지-투-이미지로 실행됩니다. 무엇을 어떻게 바꿀지는 프롬프트에 적으세요. POST /v1/images/edits도 같은 파라미터를 받습니다.
• 두 엔드포인트 모두 JSON 본문만 받고 multipart 파일 업로드는 받지 않습니다. 그래서 OpenAI SDK의 images.edit()은 그대로 쓸 수 없으니, 아래 예시처럼 링크나 base64를 보내세요.
• 참조 이미지는 각각 공개 이미지 URL(http 또는 https), data: URI, 순수 base64 중 하나로 보낼 수 있습니다. 한 장당 16MB 이하이며, JPEG, PNG, WebP 같은 일반적인 형식이면 됩니다.
• URL은 이미지 파일 자체를 내려받을 수 있어야 합니다. 웹 페이지, 로그인이 필요한 주소, 핫링크 방지가 걸린 주소는 안 됩니다. 읽을 수 없는 참조 이미지는 제출할 때 바로 400으로 거절되며, 몇 번째 이미지인지와 이유가 함께 표시됩니다. 작업은 만들어지지 않고 과금되지 않습니다.
• 출력 비율은 참조 이미지가 아니라 size로 정해집니다. 원본 비율을 유지하려면 size를 원본과 같은 비율로 지정하세요.
• 참조 이미지는 당사가 대신 호스팅하며 7일 동안 보관합니다.

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

curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-flare", "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일 동안 보관됩니다.

생성 시간

제출부터 결과까지 1K는 보통 20~60초, 네이티브로 생성하는 2K와 4K는 보통 30~120초 걸립니다. 이미지-투-이미지, 참조 이미지가 여러 장인 경우는 더 오래 걸리며, 게이트웨이가 다른 회선으로 재시도하는 작업은 몇 분이 걸릴 수 있습니다.

최근 7일간 실제 호출 기준: 중앙값 25 초, 90%가 40 초 안에 완료.

오류와 환불

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

제출할 때 돌아오는 오류

작업 실패(status가 failed)

조회 대신 웹훅으로 받기

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

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