OpenAI Images Edits API 신청 및 사용

OpenAI 이미지 편집 서비스는 여러 장의 이미지와 명령어를 입력받아 수정된 이미지를 출력합니다. 현재 인터페이스는 dall-e-2, gpt-image-1, 최신 gpt-image-2 뿐만 아니라 동일한 인터페이스를 통해 접속 가능한 nano-banana / nano-banana-2 / nano-banana-pro 시리즈 모델도 지원합니다. 이 문서는 OpenAI Images Edits API 사용 절차를 주로 소개하며, 이를 통해 공식 OpenAI 이미지 편집 기능을 쉽게 사용할 수 있습니다.

신청 절차

OpenAI Images Edits API를 사용하려면 먼저 OpenAI Images Edits API 페이지에서 「Acquire」 버튼을 클릭하여 요청에 필요한 인증 토큰을 획득하세요:

로그인 또는 회원가입하지 않은 경우 자동으로 로그인 페이지로 이동하며, 로그인 및 회원가입 후 현재 페이지로 자동 복귀합니다. 최초 신청 시 무료 이용 한도가 제공되어 API를 무료로 사용할 수 있습니다.

GPT-Image-2 모델

gpt-image-2는 이미지 편집 시나리오에서 gpt-image-1 대비 다음과 같은 현저한 향상이 있습니다:

구조 유지가 더 안정적임: 스킨 변경, 색상 변경, 배경 변경 시 원본 이미지의 레이아웃과 구도가 거의 파괴되지 않습니다.
문자 보존이 더 정확함: 인포그래픽, 포스터, 메뉴 등 텍스트가 포함된 이미지 편집 후에도 텍스트가 선명하고 읽기 쉽습니다.
URL 직접 전송 지원: 전통적인 multipart/form-data 파일 업로드 외에 gpt-image-2는 JSON 방식으로 이미지 URL을 전달하는 것도 지원하여, 이미지를 로컬에 다운로드하지 않고도 서버 파이프라인에 적합합니다.
고해상도 재그리기 지원: 1K 원본 이미지를 입력하고 size 파라미터로 2K / 4K 출력을 요청하면, 편집 과정에서 확대도 동시에 수행합니다.

지원하는 `size` 값과 과금 구간

편집 인터페이스의 size 제약은 생성 인터페이스와 완전히 동일합니다 — gpt-image-2는 size가 auto, 비어있거나 WIDTHxHEIGHT 형식이어야 하며, 그 외의 형식은 400 에러를 반환합니다. 과금은 두 가지 구간으로 나뉘며, 원본 해상도와 무관하게 size 요청값에 따라 결정됩니다:

1K 표준 가격: 아래 표에 나열된 1K 권장 크기 또는 상위 시스템에서 흔히 사용하는 1K 출력 별칭(1254x1254, 1672x941, 941x1672) 중 하나.
기타 구간(1.5×): 아래 표의 2K / 4K 권장 크기 및 사용자가 임의로 지정한 WIDTHxHEIGHT 모두 포함.

상위 시스템의 커스텀 크기 제약도 동일하게 적용됩니다: 너비와 높이는 모두 16의 배수, 긴 변 ≤ 3840, 총 픽셀 수 ≤ 8,294,400.

비율	1K(표준가)	2K 권장(×1.5)	4K 권장(×1.5)
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

예: 원본 이미지가 1024x1024일 때, size에 2048x2048을 전달하면 모델이 편집 지시에 따라 2K 이미지를 재그리며 “기타” 구간 과금이 적용됩니다. size에 3840x2160을 전달하면 4K 가로 화면 이미지를 출력하며 역시 “기타” 구간 과금이 적용됩니다. auto 또는 생략 시 1K 표준 가격 과금이 적용됩니다.

n 파라미터 관련 gpt-image-2 편집 인터페이스는 현재 n > 1을 지원하지 않습니다. 이 파라미터는 무시되며, n=1 또는 n=10을 전달해도 한 번의 요청에 1장 이미지 결과만 반환되고 1장 분만 과금됩니다. 여러 후보 편집 결과를 한 번에 받으려면 여러 번 동시 요청을 직접 수행해야 합니다. 이 제한은 gpt-image-1 / gpt-image-1.5 및 nano-banana / nano-banana-2 / nano-banana-pro 시리즈에도 동일하게 적용됩니다. dall-e-2만이 현재 n > 1을 네이티브로 지원하는 편집 모델입니다.

아래 두 가지 실제 예시를 통해 gpt-image-2의 편집 능력을 체험해 보겠습니다.

호출 방법 1: JSON + 이미지 URL (추천)

application/json 방식으로 요청을 보내고, image 필드에 이미지 URL을 입력하면 모델이 해당 이미지를 가져와 prompt에 따라 편집합니다. 예를 들어, 아래 원본 이미지는 gpt-image-2로 생성된 과학 정보 도감입니다:

이를 “야간 모드” 색상으로 변경하고 싶다면 다음과 같이 호출합니다:

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

또는 Python으로:

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

반환 결과는 다음과 같습니다:

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

편집된 이미지는 다음과 같습니다:

모듈 구조, 정보 구역, 글꼴 배치가 엄격히 유지되었으며, 색상만 어두운 테마로 반전된 것을 확인할 수 있습니다.

팁: image 필드는 배열로도 전달할 수 있습니다. 예: "image": ["url1", "url2", "url3"] 최대 16장의 참조 이미지를 동시에 전달하여 모델이 여러 이미지를 종합해 편집할 수 있습니다.

호출 방법 2: JSON + 다중 참조 이미지

gpt-image-2는 여러 장의 이미지를 참조하여 최종 결과를 생성할 수 있습니다. 예를 들어 여러 제품 사진을 하나의 선물 바구니에 합성하는 경우:

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

시나리오 예시: 스타일 변경 + 구조 유지

다음은 나무 책장을 현대적인 플로팅 선반으로 교체하되, 각 층의 책 수와 배열은 엄격히 유지하는 예입니다. 원본 이미지 (gpt-image-2로 생성된 나무 책장):

호출 예:

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

편집 결과 (task_id: e9544dba-727e-44a2-81e1-223d49869380):

스타일과 환경이 프롬프트에 따라 완전히 교체되었으며, 각 층의 책 수(1 / 3 / 7)는 엄격히 유지되고 요구대로 작은 다육식물이 추가된 것을 확인할 수 있습니다.

호출 방법 3: multipart/form-data (OpenAI SDK 호환)

공식 OpenAI Python SDK를 이미 사용 중이라면 기존의 multipart/form-data 업로드 방식도 동일하게 적용 가능하며, model만 gpt-image-2로 변경하면 됩니다:

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

SDK 사용 시 두 개의 환경 변수를 먼저 설정해야 합니다. OPENAI_BASE_URL은 https://api.xhuoapi.ai/v1/openai로, OPENAI_API_KEY는 신청한 토큰으로 설정하세요:

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token}

Nano Banana 시리즈 모델

nano-banana 시리즈도 편집 시나리오에서 /openai/images/edits를 통해 접속하며, model을 아래 표 중 하나로 변경하면 됩니다.

모델	과금 (Credits / 회)	적용 시나리오
`nano-banana`	0.14	일반 이미지 편집, 가장 빠르고 비용 저렴
`nano-banana-2`	0.28	품질 및 디테일 현저히 향상
`nano-banana-pro`	0.35	시리즈 최고급, 구조·문자·스타일 보존 최상

중요: 지원 파라미터 범위 Nano Banana는 어댑터 레이어를 통해 OpenAI 프로토콜에 접속하며, 다음 파라미터만 지원합니다: model, prompt, image.

image는 multipart/form-data로 파일 업로드하거나(내부에서 data:<mime>;base64,...로 변환 후 상위 시스템에 전달), 폼 필드에 이미지 URL 문자열로 직접 전달할 수 있습니다.

mask, n, size, response_format 등 파라미터는 지원하지 않으며, 입력해도 무시됩니다.

반환 구조는 OpenAI 형식을 따르나(data[].url), created는 항상 0이고 b64_json을 반환하지 않으며, revised_prompt는 항상 원본 prompt와 동일합니다.

폼 + 이미지 URL 호출 예

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

반환 결과:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

편집된 이미지:

폼 + 로컬 파일 호출 예

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

비동기 콜백

callback_url 비동기 콜백 메커니즘은 nano-banana에도 동일하게 적용되며, 호출 절차는 다른 모델과 완전히 같습니다. 자세한 내용은 아래 비동기 콜백 섹션을 참조하세요.

기본 사용법

이제 코드를 통해 호출할 수 있습니다. 아래는 CURL 호출 예시입니다:

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

처음 이 인터페이스를 사용할 때는 최소 네 가지 항목을 입력해야 합니다. 하나는 authorization으로, 드롭다운 목록에서 선택할 수 있습니다. 또 하나는 model로, OpenAI 공식 모델 종류를 선택하는 파라미터입니다. 여기서는 1종 모델이 있으며, 자세한 내용은 제공된 모델 목록을 참고하세요. 또 하나는 prompt로, 생성할 이미지에 대한 설명을 입력합니다. 마지막으로 image 파라미터는 편집할 이미지 경로이며, 아래 이미지와 같습니다:

동일한 호출 효과를 내는 Python 샘플 코드:

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# 이미지 파일로 저장
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

Python 호출 시 두 개의 환경 변수를 먼저 설정해야 합니다. 하나는 OPENAI_BASE_URL로 https://api.xhuoapi.ai/v1/openai로 설정하고, 다른 하나는 인증 토큰인 OPENAI_API_KEY로 설정합니다. Mac OS에서는 다음 명령어로 환경 변수를 설정할 수 있습니다:

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token} 

호출 후 현재 디렉터리에 gift-basket.png 이미지가 생성됩니다. 결과는 다음과 같습니다:

이로써 이미지 편집 작업이 완료되었습니다. 현재 Edits 인터페이스는 세 가지 모델을 지원합니다: dall-e-2, gpt-image-1, gpt-image-2이며, 그중 gpt-image-2가 현재 권장 모델입니다. 자세한 내용은 위 GPT-Image-2 모델 섹션을 참조하세요.

비동기 콜백

OpenAI Images Edits API는 이미지 편집에 시간이 다소 소요될 수 있어, API가 장시간 응답하지 않으면 HTTP 요청이 계속 연결되어 시스템 자원 낭비가 발생할 수 있습니다. 이를 위해 본 API는 비동기 콜백을 지원합니다. 전체 흐름은 다음과 같습니다: 클라이언트가 요청 시 callback_url 필드를 추가로 지정하면, API는 즉시 task_id가 포함된 결과를 반환합니다. 작업 완료 후 편집 결과가 JSON 형태로 클라이언트가 지정한 callback_url로 POST 전송되며, 이때도 task_id가 포함되어 작업 결과를 ID로 연동할 수 있습니다. 아래 예시로 구체적인 절차를 살펴봅니다. 먼저 Webhook 콜백은 HTTP 요청을 받을 수 있는 서비스여야 하며, 개발자는 직접 구축한 HTTP 서버 URL로 대체해야 합니다. 편의를 위해 공개 Webhook 예시 사이트 https://webhook.site/를 사용합니다. 사이트 접속 시 Webhook URL이 생성되며 다음과 같이 표시됩니다:

이 URL을 복사하여 Webhook으로 사용합니다. 예시는 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab입니다. 다음으로 callback_url 필드를 위 Webhook URL로 설정하고, 다른 파라미터와 함께 요청합니다:

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

호출 후 즉시 다음과 같은 결과를 받습니다:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

잠시 후 Webhook URL에서 편집 결과를 확인할 수 있습니다. 내용은 다음과 같습니다:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

결과에 task_id 필드가 포함되어 있고, data 필드에 동기 호출과 동일한 이미지 편집 결과가 포함되어 있습니다. task_id를 통해 작업을 연동할 수 있습니다.

오류 처리

API 호출 시 오류가 발생하면, API는 해당 오류 코드와 메시지를 반환합니다. 예를 들어:

400 token_mismatched: 잘못된 요청, 파라미터 누락 또는 잘못됨 가능성.
400 api_not_implemented: 잘못된 요청, 파라미터 누락 또는 잘못됨 가능성.
401 invalid_token: 인증 실패, 토큰이 없거나 유효하지 않음.
429 too_many_requests: 요청 과다, 속도 제한 초과.
500 api_error: 서버 내부 오류.

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

이 문서를 통해 OpenAI Images Edits API를 사용하여 공식 OpenAI 이미지 편집 기능을 쉽게 활용하는 방법을 익혔습니다. 본 문서가 API 연동과 사용에 도움이 되길 바라며, 문의 사항이 있으면 언제든지 기술 지원팀에 연락해 주시기 바랍니다.

​신청 절차

​GPT-Image-2 모델

​지원하는 size 값과 과금 구간

​호출 방법 1: JSON + 이미지 URL (추천)

​호출 방법 2: JSON + 다중 참조 이미지

​시나리오 예시: 스타일 변경 + 구조 유지

​호출 방법 3: multipart/form-data (OpenAI SDK 호환)

​Nano Banana 시리즈 모델

​폼 + 이미지 URL 호출 예

​폼 + 로컬 파일 호출 예

​비동기 콜백

​기본 사용법

​비동기 콜백

​오류 처리

​오류 응답 예시

​결론

신청 절차

GPT-Image-2 모델

지원하는 `size` 값과 과금 구간

호출 방법 1: JSON + 이미지 URL (추천)

호출 방법 2: JSON + 다중 참조 이미지

시나리오 예시: 스타일 변경 + 구조 유지

호출 방법 3: multipart/form-data (OpenAI SDK 호환)

Nano Banana 시리즈 모델

폼 + 이미지 URL 호출 예

폼 + 로컬 파일 호출 예

비동기 콜백

기본 사용법

비동기 콜백

오류 처리

오류 응답 예시

결론