GPT Image 2 / 2.5 API — Generation and Image Editing

GPT Image 2, Sunburst 및 Flare로 텍스트-이미지 생성에는 generations를, 참조 이미지가 있는 편집에는 multipart edits를 사용합니다. 단일 이미지, 다중 이미지, Python 및 비동기 예제를 포함합니다.

GPT Image 2 / 2.5: 이미지 생성 및 편집

요청을 작성하기 전에 엔드포인트를 선택하세요: 텍스트-이미지는 /images/generations을 사용하고, 이미지-이미지는 업로드된 이미지 파일과 함께 /images/edits을 사용합니다. 프롬프트에 “참조 이미지 1”이라고 언급하는 것만으로는 이미지가 첨부되지 않습니다.

모델 및 엔드포인트

모델 ID	텍스트-이미지	이미지-이미지
`gpt-image-2`	`/images/generations`	`/images/edits` + 이미지 파일
`gpt-image-2.5-sunburst`	`/images/generations`	`/images/edits` + 이미지 파일
`gpt-image-2.5-flare`	`/images/generations`	`/images/edits` + 이미지 파일

이들은 서로 다른 모델 ID입니다. 모델을 전환할 때는 model를 명시적으로 변경하세요. GPT Image 2.5는 GPT Image 2의 별칭이 아닙니다. 현재 가용성과 계정 가격은 마켓플레이스에서 확인하세요.

작업	메서드 및 엔드포인트	요청 형식
텍스트-이미지	`POST https://apimaster.ai/v1/images/generations`	JSON
이미지-이미지 / 편집	`POST https://apimaster.ai/v1/images/edits`	실제 이미지 파일이 포함된 `multipart/form-data`
비동기 이미지 편집	`POST https://apimaster.ai/v1/images/edits/async`	편집과 동일한 multipart 파일; 작업 ID 반환
비동기 텍스트-이미지	`POST https://apimaster.ai/v1/images/generations/async`	JSON; 작업 ID 반환
작업 조회	`GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID`	Bearer 인증

이미지 편집의 작업 응답에는 /images/edits/async를 사용하세요. 동기 편집과 동일한 파일과 필드를 업로드한 다음 /tasks/{task_id}를 조회하세요. 편집 요청을 generations/async로 옮기지 마세요. 이 작업 엔드포인트들은 기존의 비동기 계약을 재사용합니다: 비동기 업스트림은 작업을 즉시 반환할 수 있고, 동기 업스트림은 게이트웨이가 작업 ID를 반환하기 전에 편집을 완료할 수도 있습니다. 이는 즉각적인 백그라운드 실행을 보장하지 않습니다. 이 모델들에는 Chat Completions를 사용하지 마세요.

인증 및 타임아웃

API 키를 생성하고 Authorization: Bearer YOUR_API_KEY를 전송하세요. JSON 생성 요청은 Content-Type: application/json를 사용합니다. 파일 업로드 시에는 cURL 또는 HTTP 라이브러리가 multipart boundary를 생성하도록 하고, Content-Type 헤더를 수동으로 설정하지 마세요.

기본 요청에는 최소 180초, 고해상도에는 300초, 까다로운 편집이나 고품질에는 600초 이상을 허용하세요. 클라이언트 타임아웃이 업스트림 요청이 중단되었음을 증명하지는 않습니다. 즉각적인 중복 제출은 피하세요.

텍스트-이미지: JSON 생성

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Sunburst 또는 Flare의 경우 모델 ID를 gpt-image-2.5-sunburst 또는 gpt-image-2.5-flare로 교체하세요. 이 예제에는 참조 이미지를 추가하지 말고, 아래의 편집 예제를 사용하세요.

이미지-이미지: 단일 참조 업로드

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

reference.png를 실제 로컬 이미지로 교체하세요. @는 cURL에게 파일 바이트를 업로드하도록 지시하고, image=reference.png는 파일명 문자열만 전송합니다. 이 엔드포인트 패턴은 gpt-image-2 및 gpt-image-2.5-sunburst에도 적용됩니다.

이미지-이미지: 다중 참조 업로드

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

프롬프트에 설명된 순서대로 각 파일마다 동일한 image[] 필드를 반복하세요. n는 참조 이미지 수가 아니라 출력 이미지 수입니다. 참조 제한은 선택한 모델과 사용 가능한 라우트에 따라 다르며, 전체적으로 16개 이미지 제한이 있다고 가정하지 마세요. 하나의 참조와 n=1로 시작하고, 필요에 따라 입력을 추가하세요.

Python 편집 예제

requests를 설치하세요. 이 예제는 실제 파일을 업로드하고 URL과 base64 이미지 응답을 모두 처리합니다.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

여러 파일의 경우 반복되는 ("image[]", (filename, file_object, mime_type)) 항목의 리스트를 files에 전달하세요. 요청이 완료될 때까지 각 파일을 열어둔 상태로 유지하세요.

비동기 이미지 편집

애플리케이션이 작업 ID를 소비하는 경우 GPT Image 2, Sunburst 또는 Flare에서 이 엔드포인트를 사용하세요. 파일 업로드 규칙, 참조 순서, 기능 제한 및 인증은 동기 편집과 동일합니다.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

제출은 data[0].task_id를 반환합니다. 동일한 모델 ID로 폴링하세요:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

완료된 추적 작업은 다음 형태를 가지며, 모든 생성된 이미지가 포함됩니다:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

작업은 제출한 계정에 속합니다. 해당 계정의 유효한 API 키로 조회하세요. 실패한 제출은 사용 가능한 작업이 아니라 오류를 반환합니다. 작업 ID가 한 번 반환되면 편집을 다시 제출하는 대신 해당 작업을 계속 폴링하세요. 아래의 폴링 상태 표를 참조하세요.

기존 URL 또는 base64 통합

입력이 URL인 경우, 애플리케이션에서 이미지를 다운로드하고 그 바이트를 /images/edits에 업로드하세요. base64 데이터 URI인 경우, 페이로드를 파일 또는 바이트 버퍼로 디코딩하여 업로드하세요. URL이나 base64 텍스트를 파일 업로드인 것처럼 제출하지 마세요.

일부 GPT Image 2 라우트는 generations에서 image_urls 확장을 지원합니다. 이는 이식 가능한 이미지 편집 계약이 아니며, GPT Image 2.5에서 작동한다고 가정해서는 안 됩니다. 새 통합은 위의 multipart 편집 예제를 사용해야 합니다. image_urls, image 또는 images가 포함된 JSON 요청은 편집 엔드포인트에 파일을 업로드하는 것과 동등하지 않습니다.

파라미터 및 기능 제한

필드	사용법
`model`	필수; 위 표의 정확한 모델 ID 중 하나를 사용
`prompt`	필수; 결과와 참조 순서를 설명
`image` / `image[]`	편집용 실제 업로드 파일; 기본 예제에는 PNG 또는 JPEG 사용
`n`	출력 이미지 수; `1`로 시작; 최대값은 라우트에 따라 다름
`size`	선택; `1024x1024`가 기본 예제; 다른 픽셀 크기나 종횡비는 라우트에 따라 다름
`resolution`	선택; `1k`, `2k`, `4k` 같은 라우트별 확장; 모든 모델/라우트가 모든 티어를 지원하는 것은 아님
`quality`	선택; 허용되는 값과 비용은 라우트에 따라 다름
`background`, `output_format`, `output_compression`	선택; 투명도 및 출력 인코딩은 라우트 지원 필요
`mask`	GPT Image 2 전용, 사용 가능한 편집 라우트가 업로드된 마스크를 지원하는 경우; 현재 GPT Image 2.5 multipart 핸들러는 지원하지 않음

GPT Image 2의 경우, 마스크 지원 여부는 일반 참조 편집과 별도로 확인해야 합니다. 호환되는 PNG 마스크는 입력 크기와 일치하고 알파 채널을 포함해야 합니다. 현재 GPT Image 2.5 multipart 엔드포인트는 업로드된 마스크 파일을 거부합니다. 위의 Sunburst 또는 Flare 예제에 마스크를 추가하지 마세요. 선택한 라우트를 확인하지 않은 채 JSON mask_url 우회 방법이 지원된다고 가정하지 마세요.

필요한 선택적 필드만 전송하세요. 선택적 필드는 적격 라우트와 가격을 변경할 수 있으며, 기본값을 명시적으로 설정하는 것이 생략하는 것과 항상 동등하지는 않습니다. 고정된 픽셀 크기 표나 고급 파라미터 목록이 세 모델 ID 모두에 균일하게 적용되지는 않습니다. 실제 가격과 지원되는 기능은 마켓플레이스와 요청 응답을 따릅니다.

동기 응답

성공적인 생성 또는 편집은 data에 이미지 항목을 반환합니다:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

라우트와 출력 형식에 따라 항목에 b64_json가 포함될 수 있습니다. 이를 이미지 바이트로 디코딩하세요. 임시 결과 URL은 즉시 다운로드하세요. HTTP 200 응답이나 이미지 수만으로는 참조 세부 사항이 보존되었음을 증명하지 않습니다. 결과를 입력과 대조하여 확인하세요.

비동기 작업: 제출 및 폴링

텍스트-이미지의 경우, 참조 이미지 없이 JSON을 generations/async에 제출하세요. 이미지 편집의 경우, 위의 multipart edits/async 예제를 사용하세요. 둘 다 동일한 작업 조회 엔드포인트를 사용합니다:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

제출 응답의 봉투는 일반적으로 submitted를 보고합니다. 업스트림이 이미 완료 상태를 보고할 수도 있습니다. 첫 번째 폴링에서 이미 완료되었을 수 있습니다. 작업 ID는 즉각적인 응답을 보장하지 않습니다: 선택한 업스트림이 동기 방식인 경우, 플랫폼은 작업을 반환하기 전에 생성이 완료되기를 기다립니다. 충분한 제출 타임아웃을 유지하세요.

제출 시 사용한 것과 동일한 모델 ID로 폴링하세요:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

작업 상태	조치
`pending`, `submitted`, `processing`, `in_progress`	대기; 3–5초 후 다시 조회
`succeeded`, `success`, `completed`	`data.result.images`의 모든 항목을 읽기; 추적 작업은 문자열 `url`를 사용하고, 레거시 업스트림 응답은 URL 배열을 사용할 수 있음
`failed`, `error`, `cancelled`	폴링을 중단하고 오류 검토

10분과 같은 유한한 전체 폴링 데드라인을 사용하세요. 데드라인이 만료되면 자동으로 다른 유료 작업을 생성하는 대신 나중에 확인할 수 있도록 작업 ID를 보관하세요. 작업 조회 응답과 동기 이미지 응답은 구조가 다릅니다.

참조 이미지 문제 해결

실제 요청 경로가 /v1/images/edits 또는 /v1/images/edits/async이고, generations나 generations/async가 아닌지 확인하세요.
multipart에 생성된 boundary와 함께 image 또는 반복되는 image[] 아래에 파일 바이트가 포함되어 있는지 확인하세요. 프롬프트 텍스트, 파일명, 참조 수는 파일을 대체하지 못합니다.
정확한 모델 ID를 확인하세요. GPT Image 2의 확장이 Sunburst나 Flare에서 자동으로 지원되지는 않습니다.
작업/로그 세부 사항에 미리보기가 없다고 해서 이미지가 전송되지 않았다고 결론 내리지 마세요: 로그는 base64 데이터와 업로드된 파일 내용을 생략할 수 있습니다. 반대로, 로그에 기록된 참조 수가 업스트림이 이미지를 사용했음을 입증하지 않습니다.
독특한 문자나 모양이 포함된 간단한 참조 이미지로 테스트하고, 그 세부 사항을 설명하지 않고 배경 변경을 요청하세요. 출력을 시각적으로 비교하세요.
지원 요청 시 요청 ID(X-Oneapi-Request-Id), 작업 ID(있는 경우), 모델, 엔드포인트, 타임스탬프, 정리된 요청 필드 및 참조 이미지를 보관하세요. API 키는 절대 공유하지 마세요.

400 응답의 경우 엔드포인트와 파라미터 호환성을 확인하고, 401은 인증 실패를, 429는 속도/할당량 제한을 나타냅니다. 타임아웃이나 업스트림 실패의 경우 요청/작업 ID를 보관하고 재제출하기 전에 기존 작업이나 사용량 기록을 확인하세요.