> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI 이미지 편집 API 신청 및 사용 > OpenAI generation API guide - Ace Data Cloud OpenAI 이미지 편집 서비스는 임의의 여러 장의 이미지와 지시를 입력하면 수정된 이미지를 출력합니다. 현재 인터페이스는 `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 콘솔](https://platform.acedata.cloud/console/applications)에서 API 토큰을 받아야 하며, 이를 백업용으로 보관합니다. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. **하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 한도가 제공되어 무료로 체험할 수 있으며, 한도가 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다. > 📘 전체 문서: [OpenAI 이미지 편집 API →](https://platform.acedata.cloud/documents/openai-images-edits) ## 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. | 비율 | 1K 추천 | 2K 추천 | 4K 추천 | | ---- | ----------- | ----------- | ----------- | | 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`를 전달하거나 생략하면 모델이 스스로 선택합니다. 세 가지 모두 요금은 동일합니다. > **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`로 생성된 과학 도감입니다:

우리는 이를 "야간 모드" 색상으로 변경하고 싶습니다. 이렇게 호출할 수 있습니다: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "이 인포그래픽을 다크 모드로 변환하세요: 어두운 네이비 배경, 밝은 크림색 텍스트, 부드러운 그림자가 있는 깊은 회색 둥근 모듈 카드. 모든 레이아웃, 구조 및 모듈 배치를 동일하게 유지하세요 — 색상만 반전하세요.", "size": "1024x1536" }' ``` 또는 파이썬을 사용하여: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "이 인포그래픽을 다크 모드로 변환하세요: 어두운 네이비 배경, 밝은 크림색 텍스트, 부드러운 그림자가 있는 깊은 회색 둥근 모듈 카드. 모든 레이아웃, 구조 및 모듈 배치를 동일하게 유지하세요 — 색상만 반전하세요.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 반환 결과는 다음과 같습니다: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "이 인포그래픽을 다크 모드로 변환하세요: 어두운 네이비 배경, 밝은 크림색 텍스트, 부드러운 그림자가 있는 깊은 회색 둥근 모듈 카드. 모든 레이아웃, 구조 및 모듈 배치를 동일하게 유지하세요 — 색상만 반전하세요.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 편집된 이미지는 다음과 같습니다:

모듈 구조, 정보 구역, 글꼴 배치가 엄격하게 유지되었으며, 색상만 어두운 테마로 반전되었습니다. > **팁**: `image` 필드는 배열을 전달하는 것도 지원합니다. 예를 들어, `"image": ["url1", "url2", "url3"]`와 같이 최대 16개의 참조 이미지를 동시에 전달하여 모델이 여러 이미지를 종합적으로 참고하여 편집할 수 있습니다. > **base64 직접 전송**: `image`(및 배열의 각 항목)는 URL 외에도 base64로도 가능하며, `data:image/png;base64,...` 또는 순수 base64 모두 가능합니다. 이는 로컬 이미지를 먼저 업로드하고 싶지 않은 경우에 적합합니다. 예를 들어: > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "이 인포그래픽을 다크 모드로 변환하세요.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### 호출 방법 2: JSON + 여러 참조 이미지 `gpt-image-2`는 최종 결과를 생성하기 위해 여러 이미지를 동시에 참조할 수 있습니다. 예를 들어 여러 제품 사진을 하나의 선물 바구니에 합성하는 경우: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "위의 모든 항목을 깨끗한 흰색 배경에 'Relax & Unwind' 선물 바구니로 결합하세요, 포토리얼리스틱, 부드러운 자연 조명.", "size": "1024x1024" } ``` ### 시나리오 예시: 스타일 변경 + 구조 유지 다음은 나무 책장을 현대적인 플로팅 선반으로 교체하되, 각 층의 책 수와 배열을 엄격하게 유지하는 또 다른 예입니다. 원본 이미지( `gpt-image-2`로 생성된 나무 책장):

호출: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "나무 책장을 파스텔 블루 벽에 장착된 세련된 현대적인 흰색 플로팅 선반으로 교체하세요. 책의 정확한 배열(위에 1권, 중간에 3권, 아래에 7권)을 유지하세요. 위 선반에 책 옆에 작은 화분의 다육 식물을 추가하세요. 왼쪽에서 밝고 통풍이 잘 되는 자연광.", "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`로 변경하면 됩니다: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="레이아웃을 유지하면서 이 이미지를 다크 모드로 변환하세요." ) 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.acedata.cloud/openai`로, `OPENAI_API_KEY`를 신청한 토큰으로 설정하세요: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## Nano Banana 시리즈 모델 `nano-banana` 시리즈는 편집 시나리오에서도 `/openai/images/edits`에 접속할 수 있으며, `model`을 아래 표의 임의의 것으로 변경하면 됩니다. | 모델 | 요금 (크레딧 / 회) | 적합한 상황 | | -------------------- | ------------ | -------------------------------------- | | `nano-banana` | 0.14 | 일반 이미지 편집, 가장 빠르고 비용이 가장 낮음 | | `nano-banana-2-lite` | 0.14 | Gemini 3.1 경량 이미지 모델, 1K만 지원, 낮은 지연 편집 | | `nano-banana-2` | 0.28 | 품질과 세부 사항이 명확히 향상됨 | | `nano-banana-pro` | 0.35 | 시리즈의 플래그십, 구조, 텍스트, 스타일 보존이 최상 | > **중요: 매개변수 지원 범위** > Nano Banana는 적응 계층을 통해 OpenAI 프로토콜에 접속하며, 다음 매개변수만 지원합니다: `model`、`prompt`、`image`。 > > * `image`는 `multipart/form-data`를 통해 파일을 업로드할 수 있으며(워커 내부에서 `data:;base64,...`로 변환하여 상위로 전달), 폼 필드를 통해 이미지 URL 문자열을 직접 전달할 수도 있습니다. > * `mask`、`n`、`size`、`response_format` 등의 매개변수는 지원하지 않으며, 입력해도 무시됩니다. > * 반환 구조는 OpenAI 형식을 따르며(`data[].url`), `created`는 고정으로 `0`이며, `b64_json`은 반환되지 않고, `revised_prompt`는 항상 원래 `prompt`와 같습니다. ### 폼 + 이미지 URL 호출 ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=사과 위에 초록색 잎을 추가하세요" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` 반환 결과는 다음과 같습니다: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "사과 위에 초록색 잎을 추가하세요" } ] } ``` 편집된 이미지:

### 폼 + 로컬 파일 호출 ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "사과 위에 초록색 잎을 추가하세요" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### 비동기 콜백 `callback_url` 비동기 콜백 메커니즘은 nano-banana에도 동일하게 유효하며, 호출 프로세스는 다른 모델과 완전히 일치합니다. 자세한 내용은 아래 [비동기 콜백](#비동기-콜백) 섹션을 참조하십시오. ## 기본 사용 이제 코드를 사용하여 호출할 수 있습니다. 아래는 CURL을 사용한 호출 예입니다: ```curl theme={null} 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.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=이 아이템들이 들어간 사랑스러운 선물 바구니를 만들어주세요' ``` 이 인터페이스를 처음 사용할 때, 최소한 네 가지 내용을 입력해야 합니다. 하나는 `authorization`으로, 드롭다운 목록에서 직접 선택할 수 있습니다. 또 다른 매개변수는 `model`이며, `model`은 OpenAI 공식 모델 카테고리를 선택하는 것입니다. 여기서는 주로 1종의 모델이 있으며, 자세한 내용은 제공된 모델을 참조하십시오. 마지막 매개변수는 `prompt`이며, `prompt`는 생성할 이미지에 대한 힌트입니다. 마지막 매개변수는 `image`로, 편집할 이미지 경로가 필요합니다. 편집할 이미지는 아래 그림과 같습니다:

동일한 호출 효과의 Python 샘플 호출 코드: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ 흰색 배경에 'Relax & Unwind'라는 라벨이 붙은 선물 바구니의 포토리얼리스틱 이미지를 생성하세요. 리본과 손글씨 같은 글꼴로, 참조 사진에 있는 모든 아이템을 포함합니다. """ 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.acedata.cloud/openai`로 설정할 수 있습니다. 또 다른 것은 사용 인증 변수 `OPENAI_API_KEY`로, 이 값은 `authorization`에서 가져온 것입니다. Mac OS에서는 다음 명령어로 환경 변수를 설정할 수 있습니다: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/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 모델](#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/를](https://webhook.site/를) 사용하며, 해당 사이트를 열면 Webhook URL을 얻을 수 있습니다. 이 URL을 복사하면 Webhook으로 사용할 수 있습니다. 여기의 샘플은 `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`입니다. 다음으로, 필드 `callback_url`을 위의 Webhook URL로 설정하고, 아래 코드와 같이 해당 매개변수를 입력할 수 있습니다: ```shell theme={null} curl -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` 호출 후, 즉시 결과를 얻을 수 있습니다. 결과는 다음과 같습니다: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` 잠시 후, Webhook URL에서 이미지 편집 결과를 확인할 수 있습니다. 내용은 다음과 같습니다: ```json theme={null} { "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`: 내부 서버 오류, 서버에서 문제가 발생했습니다. ### 오류 응답 예시 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 결론 이 문서를 통해 OpenAI Images Edits API를 사용하여 공식 OpenAI의 이미지 편집 기능을 쉽게 사용할 수 있는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.