dall-e-2, 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-2는 JSON 방식으로 이미지 URL을 추가로 지원하여 이미지를 먼저 로컬에 다운로드할 필요가 없어 서버 측 파이프라인 통합에 매우 적합합니다. - base64 직접 전송 지원: 공식과 일치하게,
image필드에 base64를 직접 전달할 수 있습니다(data:image/png;base64,...또는 순수 base64), 로컬 이미지를 먼저 이미지 호스팅에 업로드할 필요 없이 편집할 수 있습니다. - 고해상도 재구성 지원: 1K 원본 이미지를 입력하여
size매개변수를 통해 2K / 4K 출력을 요청할 수 있으며, 모델은 편집 과정에서 동시에 확대를 완료합니다.
공식 중계 / 역변형(:official / :reverse)
gpt-image-2는 기본적으로 역변형 경로를 따릅니다. 모델 이름 접미사를 통해 경로를 명시적으로 선택할 수 있습니다:
gpt-image-2:official: 공식 중계 경로.n > 1(한 번에 여러 장 반환) 및 실제 2K / 4K를 지원하며, 각 이미지당 요금이 부과되며, 단가는 기본gpt-image-2의 2배입니다. 현재 openai-hk 채널에서만 제공되며, 경로가 사용 불가능할 경우 직접 오류를 반환하고 역변형 경로로 하향 조정되지 않습니다.gpt-image-2:reverse: 기본gpt-image-2와 완전히 동등합니다(역변형 경로), 가격은 변하지 않습니다.
아래 “n 매개변수에 대한 제한”은 기본 / 역변형 경로에만 적용됩니다;gpt-image-2:official은n > 1을 지원하며 장당 요금이 부과됩니다.
지원되는 size 값
편집 인터페이스의 size 제약은 생성 인터페이스와 완전히 일치합니다 — gpt-image-2는 size가 auto, 비어 있거나 WIDTHxHEIGHT 형식에 맞기만 하면 됩니다. 다른 형태는 400을 반환합니다. 모든 크기(1K / 2K / 4K / 사용자 정의)는 단일 장당 통일된 요금이 부과되며, 원본 이미지 해상도 및 size 요청 값과는 무관합니다.
상위에서 사용자 정의 크기에 대한 하드 제약도 동일하게 적용됩니다: 너비와 높이는 모두 16의 배수, 긴 변 ≤ 3840, 총 픽셀 수 ≤ 8,294,400.
예를 들어: 원본 이미지가1024x1024이고,size에2048x2048을 전달하면 모델은 편집 지침에 따라 재구성하고 2K 이미지를 출력합니다;size에3840x2160을 전달하면 4K 가로형 이미지를 출력합니다;auto를 전달하거나 생략하면 모델이 스스로 선택합니다. 세 가지 모두 요금은 동일합니다.
n 매개변수에 대한 설명아래는 두 가지 다른 방향의 실제 예제를 통해gpt-image-2편집 인터페이스는 현재n > 1을 지원하지 않습니다: 이 매개변수는 조용히 무시되며,n=1을 전달하든n=10을 전달하든 단일 요청은 항상 1장의 이미지만 반환하며, 1장에 대해서만 요금이 부과됩니다. 여러 장의 후보 편집 결과를 한 번에 얻으려면 자신이 여러 번 요청을 병렬로 발송해야 합니다. 이 제한은gpt-image-1/gpt-image-1.5, 그리고nano-banana/nano-banana-2-lite/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로 생성된 과학 도감입니다:


팁: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):

호출 방법 3: multipart/form-data (OpenAI SDK 호환)
공식 OpenAI Python SDK를 이미 사용 중이라면, 기존의multipart/form-data 업로드 방식도 동일하게 적용할 수 있으며, model만 gpt-image-2로 변경하면 됩니다:
OPENAI_BASE_URL을 https://api.acedata.cloud/openai로, OPENAI_API_KEY를 신청한 토큰으로 설정하세요:
Nano Banana 시리즈 모델
nano-banana 시리즈는 편집 시나리오에서도 /openai/images/edits에 접속할 수 있으며, model을 아래 표의 임의의 것으로 변경하면 됩니다.
중요: 매개변수 지원 범위 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 호출

폼 + 로컬 파일 호출
비동기 콜백
callback_url 비동기 콜백 메커니즘은 nano-banana에도 동일하게 유효하며, 호출 프로세스는 다른 모델과 완전히 일치합니다. 자세한 내용은 아래 비동기 콜백 섹션을 참조하십시오.
기본 사용
이제 코드를 사용하여 호출할 수 있습니다. 아래는 CURL을 사용한 호출 예입니다:authorization으로, 드롭다운 목록에서 직접 선택할 수 있습니다. 또 다른 매개변수는 model이며, model은 OpenAI 공식 모델 카테고리를 선택하는 것입니다. 여기서는 주로 1종의 모델이 있으며, 자세한 내용은 제공된 모델을 참조하십시오. 마지막 매개변수는 prompt이며, prompt는 생성할 이미지에 대한 힌트입니다. 마지막 매개변수는 image로, 편집할 이미지 경로가 필요합니다. 편집할 이미지는 아래 그림과 같습니다:

OPENAI_BASE_URL로, https://api.acedata.cloud/openai로 설정할 수 있습니다. 또 다른 것은 사용 인증 변수 OPENAI_API_KEY로, 이 값은 authorization에서 가져온 것입니다. Mac OS에서는 다음 명령어로 환경 변수를 설정할 수 있습니다:
gift-basket.png라는 이미지가 생성된 것을 확인할 수 있으며, 구체적인 결과는 다음과 같습니다:

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 요청을 시작한 후, API는 즉시 결과를 반환하며, 현재 작업 ID를 나타내는 task_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로 설정하고, 아래 코드와 같이 해당 매개변수를 입력할 수 있습니다:
task_id 필드가 있으며, data 필드는 동기 호출과 동일한 이미지 편집 결과를 포함하고 있습니다. task_id 필드를 통해 작업의 연관성을 구현할 수 있습니다.
오류 처리
API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:400 token_mismatched: 잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.400 api_not_implemented: 잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.401 invalid_token: 권한 없음, 잘못되었거나 누락된 인증 토큰입니다.429 too_many_requests: 너무 많은 요청, 비율 제한을 초과했습니다.500 api_error: 내부 서버 오류, 서버에서 문제가 발생했습니다.

