Skip to main content
OpenAI 이미지 편집 서비스는 이미지를 입력하고 지시를 제공하면 수정된 이미지를 출력합니다. GPT 이미지 시리즈 모델은 최대 16장의 참고 이미지를 동시에 입력할 수 있습니다. 현재 인터페이스는 gpt-image-1, 최신의 gpt-image-2, 그리고 동일한 인터페이스를 통해 접속할 수 있는 nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro 시리즈 모델을 동시에 지원합니다. 이 문서는 OpenAI 이미지 편집 API 작업의 사용 흐름을 주로 설명하며, 이를 통해 공식 OpenAI 이미지 편집 기능을 쉽게 사용할 수 있습니다.

신청 흐름

OpenAI 이미지 편집 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API 토큰을 받아야 하며, 이를 보관해 두어야 합니다. 로그인이나 등록이 되어 있지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 한도가 제공되어 무료로 체험할 수 있으며, 한도가 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.
📘 전체 문서: OpenAI 이미지 편집 API →

GPT-Image-2 모델

gpt-image-2는 이미지 편집 장면에서 gpt-image-1에 비해 매우 뚜렷한 향상을 보입니다:
  • 구조 유지가 더 안정적: 피부색, 색상, 배경을 변경할 때 원본 이미지의 레이아웃과 구성을 거의 손상시키지 않습니다.
  • 텍스트 보존이 더 정확: 정보 그래픽, 포스터, 메뉴 등 텍스트가 포함된 이미지는 편집 후에도 텍스트가 여전히 선명하게 읽을 수 있습니다.
  • URL 직접 전송 지원: 전통적인 multipart/form-data 파일 업로드 외에도, gpt-image-2JSON 방식으로 이미지 URL을 직접 전송하는 것을 추가로 지원하여 이미지를 먼저 로컬에 다운로드할 필요가 없으며, 서버 측 파이프라인 통합에 매우 적합합니다.
  • base64 직접 전송 지원: 공식과 일치하게, image 필드도 base64(예: data:image/png;base64,... 또는 순수 base64)를 직접 전송할 수 있으며, 로컬 이미지를 먼저 이미지 호스팅 사이트에 업로드할 필요 없이 편집할 수 있습니다.
  • 고해상도 재구성 지원: 1K 원본 이미지를 입력하여 size 매개변수를 통해 2K / 4K 출력을 요청할 수 있으며, 모델은 편집 과정에서 동시에 확대를 완료합니다.

경로 변형(:official / :reverse)

gpt-image-2는 기본적으로 표준 경로를 사용합니다. 모델 이름 접미사를 통해 경로를 명시적으로 선택할 수 있습니다:
  • gpt-image-2:official: 공식 경로로, 안정적이고 규정을 준수합니다. 비용은 텍스트 입력 토큰, 편집 시의 이미지 입력 토큰 및 이미지 출력 토큰에 의해 결정되며, 최종적으로 응답의 실제 사용량에 따라 정산됩니다; 페이지에 표시된 품질/크기 가격은 추정용으로만 사용됩니다; 최대 사용량 패키지에 따라 고객 가격은 OpenAI 공식 표준 가격의 약 80%입니다. 서비스는 사용 가능한 경로 간에 자동으로 오류를 처리하며, 능력과 비용은 실제 반환 결과에 따라 다릅니다.
  • gpt-image-2:reverse: 기본 gpt-image-2와 완전히 동등하며, 가성비가 더 높고 가격은 변하지 않습니다.
:official 요금 계산 공식 최종 비용 = 텍스트 입력 토큰 + 이미지 입력 토큰(편집 전용) + 이미지 출력 토큰. 페이지에 표시된 quality × size 가격은 요청 전 추정치이며, 실제 청구는 성공적인 응답의 usage에 따라 결정됩니다. 예를 들어, low, 1024x1024는 일반적으로 약 0.0505 크레딧의 이미지 출력 비용이 발생하며, 소량의 입력 토큰이 추가됩니다; auto를 사용할 경우 모델이 더 높은 품질을 선택할 수 있으며, 사전 승인 한도는 더 높은 등급으로 보수적으로 확인됩니다.

지원되는 size

편집 인터페이스의 size 형식 검증은 생성 인터페이스와 일치합니다 — gpt-image-2sizeauto, 비어 있거나 WIDTHxHEIGHT 형식에 부합해야 하며, 다른 형태는 400 오류를 반환합니다. 기본 gpt-image-2:reverse는 단일 이미지에 대해 동일한 요금이 부과되며; :official은 텍스트 입력, 참고 이미지 입력 및 이미지 출력 토큰을 동시에 계산하며, 원본 이미지, 크기 및 품질이 최종 비용에 영향을 미칠 수 있습니다. 크기 제한: 사용자 정의 크기는 너비와 높이가 모두 16의 배수여야 하며, 긴 변 ≤ 3840, 총 픽셀 수 ≤ 8,294,400을 충족해야 하며, 이를 초과할 경우 4xx 오류가 반환됩니다.
예를 들어: 원본 이미지가 1024x1024이고, size2048x2048을 전달하면 모델은 편집 지침에 따라 2K 이미지를 재구성하고 출력합니다; size3840x2160을 전달하면 4K 가로형 이미지를 출력합니다. 기본 gpt-image-2:reverse의 세 가지 크기 요금은 동일하며; :official은 실제 토큰 사용량에 따라 결정됩니다. size 필드를 생략하는 것과 명시적으로 auto를 전달하는 것은 완전히 동등합니다: gpt-image-2는 먼저 프롬프트의 명확한 크기 의도를 읽으며, 픽셀, 비율, 가로 세로 방향, 해상도 등급(예: 4K / 고해상도) 또는 캔버스 이름을 포함합니다. 크기 의도가 인식되면 계획된 구체적인 크기를 사용하며; 프롬프트에 크기 요구 사항이 없거나 자동 판단이 불가능할 경우 첫 번째 참고 이미지의 크기로 되돌아갑니다. 최종 구체적인 크기는 요청 제출 전에 16의 배수, 긴 변 및 총 픽셀 제한으로 정규화됩니다; 절대적인 제어가 필요할 경우 직접 WIDTHxHEIGHT를 전달하십시오. 생성이 완료된 후 출력 픽셀이 다르더라도 자동으로 재시도하지 않으며, 중복 생성 비용을 방지합니다. n 매개변수에 대한 설명 gpt-image-2 편집 인터페이스는 n > 1을 지원합니다: 한 번의 요청으로 해당 수량의 편집 결과를 반환합니다. 기본적으로 gpt-image-2:reverse는 성공한 장수에 따라 요금이 청구되며, :official은 전체 응답 집계의 실제 토큰 사용량에 따라 정산됩니다(n 값은 1–10). 이는 gpt-image-1 / gpt-image-1.5, 그리고 nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro 시리즈에도 동일하게 적용됩니다. response_format=b64_jsonn=1만 지원하며, n>1일 경우 기본 URL 반환을 사용해야 합니다. 일부 이미지 생성이 실패할 경우, 성공한 부분만 반환되고 요금이 청구됩니다.
아래는 두 가지 다른 방향의 실제 예제를 통해 gpt-image-2의 편집 능력을 체험해 보겠습니다.

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

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

우리는 이를 “야간 모드” 색상으로 변경하고 싶습니다. 다음과 같이 호출할 수 있습니다:
또는 Python을 사용할 수 있습니다:
반환 결과는 다음과 같습니다:
편집된 이미지는 다음과 같습니다:

모듈 구조, 정보 구역, 글꼴 배치가 엄격하게 유지되었으며, 색상만 어두운 테마로 반전되었습니다.
: image 필드는 배열을 전달하는 것도 지원합니다. 예를 들어, "image": ["url1", "url2", "url3"]와 같이 최대 16개의 참조 이미지를 동시에 전달하여 모델이 여러 이미지를 종합적으로 참고하여 편집할 수 있습니다.
base64 직접 전송: image(및 배열의 각 항목)는 URL 외에도 base64로도 가능하며, data:image/png;base64,... 또는 순수 base64 모두 가능합니다. 이는 로컬 이미지를 먼저 업로드하고 싶지 않은 경우에 적합합니다. 예를 들어:

호출 방법 2: JSON + 여러 참조 이미지

gpt-image-2는 최종 결과를 생성하기 위해 여러 이미지를 동시에 참조하는 것을 지원합니다. 예를 들어, 여러 제품 사진을 하나의 선물 바구니로 합성하는 경우:

장면 예시: 스타일 변경 + 구조 유지

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

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

스타일과 환경이 모두 프롬프트에 따라 완전히 교체되었지만, 각 층의 책 수(1 / 3 / 7)는 여전히 엄격하게 유지되었으며, 요구에 따라 작은 다육 식물이 추가되었습니다.

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

이미 공식 OpenAI Python SDK를 사용하고 있다면, 기존의 multipart/form-data 업로드 방식도 동일하게 적용되며, modelgpt-image-2로 변경하기만 하면 됩니다:
SDK를 사용할 때는 먼저 두 개의 환경 변수를 가져와야 하며, OPENAI_BASE_URLhttps://api.acedata.cloud/openai로 설정하고, OPENAI_API_KEY를 신청한 토큰으로 설정해야 합니다:

Nano Banana 시리즈 모델

nano-banana 시리즈는 편집 시나리오에서도 /openai/images/edits에 접속할 수 있으며, model을 아래 표의 임의의 값으로 변경하면 됩니다.
중요: 매개변수 지원 범위 Nano Banana는 적응 계층을 통해 OpenAI 프로토콜에 접속하며, 다음 매개변수만 지원합니다: model, prompt, image, n.
  • imagemultipart/form-data를 통해 파일을 업로드할 수 있으며(로컬 파일은 자동으로 base64로 처리됨), 또한 폼 필드를 통해 이미지 URL 문자열을 직접 전달할 수 있습니다.
  • mask, size, response_format 등의 매개변수는 지원하지 않으며, 입력해도 무시됩니다. n > 1은 지원되며(1–10), 해당 수량에 따라 편집 결과가 반환되고 요금이 부과됩니다.
  • 반환 구조는 OpenAI 형식을 따르며(data[].url), created는 고정적으로 0이며, b64_json은 반환되지 않고, revised_prompt는 항상 원래 prompt와 같습니다.

폼 + 이미지 URL 호출

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

폼 + 로컬 파일 호출

비동기 콜백

callback_url 비동기 콜백 메커니즘은 nano-banana에도 동일하게 유효하며, 호출 프로세스는 다른 모델과 완전히 일치합니다. 자세한 내용은 아래 비동기 콜백 섹션을 참조하십시오.

기본 사용

이제 코드를 사용하여 호출할 수 있으며, 아래는 CURL을 통한 호출 예시입니다:
이 인터페이스를 처음 사용할 때, 최소한 네 가지 내용을 입력해야 합니다. 하나는 authorization이며, 드롭다운 목록에서 직접 선택할 수 있습니다. 또 다른 매개변수는 model이며, model은 OpenAI 공식 모델 카테고리를 선택하는 것입니다. 여기서는 주로 1종의 모델이 있으며, 자세한 내용은 제공된 모델을 참조하십시오. 마지막 매개변수는 prompt이며, prompt는 생성할 이미지에 대한 힌트입니다. 마지막 매개변수는 image이며, 이 매개변수는 편집할 이미지 경로를 필요로 합니다. 편집할 이미지는 아래 그림과 같습니다:
: image[]는 여러 번 반복하여 여러 개의 참조 이미지를 업로드할 수 있습니다. 예를 들어 -F "image[]=@a.png" -F "image[]=@b.png"와 같이 사용할 수 있으며, GPT Image 시리즈 모델은 최대 16장(각각 50MB 이하, 형식은 png/webp/jpg)을 지원합니다. 수량을 초과하면 400 오류가 반환됩니다.

동일한 호출 효과의 Python 샘플 호출 코드는 다음과 같습니다:
Python을 사용하여 호출할 때는 먼저 두 개의 환경 변수를 가져와야 하며, 하나는 OPENAI_BASE_URL으로 https://api.acedata.cloud/openai로 설정하고, 다른 하나는 사용 인증 변수인 OPENAI_API_KEY로, 이 값은 authorization에서 가져온 것입니다. Mac OS에서는 다음 명령어로 환경 변수를 설정할 수 있습니다:
호출 후, 현재 디렉토리에 gift-basket.png라는 이미지가 생성된 것을 확인할 수 있으며, 구체적인 결과는 다음과 같습니다:

这样我们就完成了对图片的编辑操作,目前 Edits 接口共支持 gpt-image-1gpt-image-2 两种模型,其中 gpt-image-2 是当前推荐使用的模型,详见上文 GPT-Image-2 模型 一节。

비동기 콜백

由于 OpenAI Images Edits API 编辑图片的时间可能相对较长,如果 API 长时间无响应,HTTP 请求会一直保持连接,导致额外的系统资源消耗,所以本 API 也提供了 비동기 콜백的支持。 整体流程是:客户端发起请求的时候,额外指定一个 callback_url 字段,客户端发起 API 请求之后,API 会立马返回一个结果,包含一个 task_id 的字段信息,代表当前的任务 ID。当任务完成之后,编辑图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url,其中也包括了 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,同时填入相应的参数,如以下代码所示:
调用之后,可以发现会立即得到一个结果,如下:
稍等片刻,我们可以在 Webhook URL 上观察到编辑图片的结果,内容如下:
可以看到结果中有一个 task_id 字段,data 字段包含了和同步调用一样的图片编辑结果,通过 task_id 字段即可实现任务的关联。

오류 처리

在调用 API 时,如果遇到错误,API 会返回相应的错误代码和信息。例如:
  • 400 token_mismatched:잘못된 요청, 아마도 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
  • 400 api_not_implemented:잘못된 요청, 아마도 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
  • 401 invalid_token:권한 없음, 잘못되었거나 누락된 인증 토큰입니다.
  • 429 too_many_requests:요청이 너무 많습니다, 비율 제한을 초과했습니다.
  • 500 api_error:서버 내부 오류, 서버에서 문제가 발생했습니다.

오류 응답 예시

결론

通过本文档,您已经了解了如何使用 OpenAI Images Edits API 轻松使用官方 OpenAI 的图像编辑功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题,请随时联系我们的技术支持团队。