제품 사진을 편집하거나, UI 목업 (UI mockups)을 재생성하거나, 에셋을 새로운 시각적 스타일로 변환하는 앱을 구축하고 있다면, 어려운 점은 대개 프롬프트 (prompt)가 아닙니다. 그것은 반복 가능한 API 워크플로 (workflow)에 신뢰할 수 있는 입출력을 가져오는 것입니다.

이 가이드는 Ace Data Cloud의 OpenAI 호환 Images Edits API를 통해 gpt-image-2를 사용하는 실무적인 이미지 편집 파이프라인 (pipeline)을 안내합니다. 목표는 간단합니다. 하나 이상의 참조 이미지를 보내고, 편집 내용을 설명한 뒤, 앱이 저장하거나 보여주거나 다음 단계로 전달할 수 있는 생성된 이미지 URL을 받는 것입니다.

할 수 있는 작업

Images Edits 엔드포인트 (endpoint)는 기존 이미지와 지침 (instruction)을 수락합니다. gpt-image-2의 경우, 문서는 프로덕션 워크플로 (production workflows)를 위한 몇 가지 유용한 동작을 강조합니다:

• 색상, 배경 또는 스타일을 변경하면서도 원래의 레이아웃 (layout)과 구도 (composition)를 더 안정적으로 유지합니다.
• 포스터, 메뉴, 인포그래픽 (infographics)과 같은 에셋에서 텍스트를 더 정확하게 보존합니다.
• JSON에 이미지 URL을 직접 전달하여, 서버가 모든 입력을 먼저 다운로드하고 다시 업로드할 필요가 없도록 합니다.
• 편집 전에 로컬 이미지를 호스팅하고 싶지 않은 경우 base64 이미지 데이터를 전달합니다.
• auto 또는 1024x1536과 같은 WIDTHxHEIGHT 문자열을 사용하여 출력 크기를 요청합니다.

핵심 엔드포인트 (endpoint)는 다음과 같습니다:

Base URL: https://api.acedata.cloud/openai
Endpoint: POST /openai/images/edits
Authorization: Bearer {token}
...

가장 중요한 필드는 model, image, prompt, 그리고 선택 사항인 size입니다. gpt-image-2의 경우, image는 URL 문자열, 이미지 URL 배열, 또는 base64 이미지 데이터가 될 수 있습니다.

작동 방식

최소한의 JSON 요청은 다음과 같습니다:

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
...

성공적인 응답은 작업 식별자 (task identifier), 추적 식별자 (trace identifier), 그리고 출력 이미지 URL을 반환합니다:

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
...

실제 애플리케이션에서는 보통 task_id, trace_id, 원본 요청 페이로드(request payload), 그리고 data[0].url을 저장합니다. 이렇게 하면 나중에 편집 내용을 디버깅하기가 훨씬 쉬워지며, 특히 사용자가 특정 이미지가 왜 그런 방식으로 변경되었는지 물을 때 매우 유용합니다.

유스케이스 1: 기존 에셋을 다시 만들지 않고 스타일 변경하기 (restyle)

일반적인 빌더 워크플로우는 작동 중인 에셋을 가져와 그 주변의 시각적 시스템을 변경하는 것입니다. 예를 들어, 이미 내용이 정확한 인포그래픽이 있지만, 대시보드, 랜딩 페이지 또는 블로그 포스트를 위해 다크 모드(dark-mode) 버전이 필요한 경우가 있습니다.

프롬프트는 무엇이 고정되어야 하는지에 대해 명확해야 합니다:

{
  "model": "gpt-image-2",
  "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
...

중요한 세부 사항은 단순히 "어둡게 만들어줘"가 아닙니다. 핵심은 제약 조건(constraint)입니다: 레이아웃, 구조, 그리고 모듈 배치를 동일하게 유지하라는 것입니다. 프로덕션 에셋을 편집할 때는 스타일 관련 단어보다 제약 조건이 더 중요한 경우가 많습니다.

유스케이스 2: 여러 개의 참조 이미지 결합하기

gpt-image-2는 image 필드에 배열(array)을 전달함으로써 여러 개의 참조 이미지를 지원합니다. 문서에 따르면 한 번에 최대 16개의 참조 이미지를 전달할 수 있습니다.

payload = {
    "model": "gpt-image-2",
    "image": [
...

이 패턴은 이커머스 번들, 소셜 크리에이티브, 캠페인 목업(mockup), 또는 사용자가 별도의 참조 이미지들을 업로드하고 하나의 합성된 결과물을 기대하는 모든 기능에 유용합니다.

유스케이스 3: OpenAI Python SDK를 통해 편집 실행하기

이미 코드에서 OpenAI Python SDK를 사용하고 있다면, Ace Data Cloud의 OpenAI 호환 베이스 URL(base URL)을 지정하면 됩니다:

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

그런 다음 gpt-image-2 모델로 images.edit를 호출합니다:

import base64
from openai import OpenAI

...

이는 이미 로컬 파일(local files)을 보유하고 있으며 기존 OpenAI 예제와 유사한 호출 스타일을 유지하고 싶을 때 적합합니다. 이미 공개된 URL이나 서명된 이미지 URL(signed image URLs)을 사용하는 서버 측 파이프라인(server-side pipelines)의 경우에는 JSON URL 방식이 종종 더 깔끔합니다.

배포 전 주의사항

설계 시 고려해야 할 몇 가지 제약 사항이 있습니다:

• gpt-image-2의 경우 size는 auto, 빈 값, 또는 WIDTHxHEIGHT 형식의 문자열이어야 합니다.
• 사용자 정의 크기(Custom sizes)는 너비와 높이가 16의 배수여야 하며, 긴 쪽은 3840을 초과할 수 없고 총 픽셀 수는 8,294,400을 초과할 수 없습니다.
• 기본 gpt-image-2 편집 경로(editing route)는 요청당 하나의 이미지를 반환합니다. 여러 후보를 원한다면 여러 요청을 동시에(concurrently) 실행하십시오.
• API는 401 invalid_token, 429 too_many_requests, 또는 500 api_error와 같은 오류를 반환할 수 있으므로 로그에 trace_id를 남겨두십시오.
• 더 긴 편집 작업의 경우, callback_url을 전달하여 작업이 완료되었을 때 비동기(asynchronously)로 결과를 처리할 수 있습니다.

간단한 빌더 체크리스트

프로덕션 기능(production feature)을 위해서는 다음과 같은 흐름으로 시작하는 것이 좋습니다:

1. 사용자의 원본 이미지 URL 또는 base64 입력을 저장합니다.
2. 원하는 변경 사항과 보존 제약 조건(preservation constraints)을 분리하는 프롬프트(prompt)를 작성합니다.
3. model, image, prompt, size를 POST /openai/images/edits로 전송합니다.
4. task_id, trace_id, 요청 페이로드(request payload), 그리고 출력된 data[0].url을 저장합니다.
5. 속도가 느린 작업에 대해 재시도(retries) 또는 비동기 콜백(async callbacks)을 추가합니다.

이 정도면 이미지 편집을 일회성 프롬프트 실험에서 사용자의 제품이 실제로 실행할 수 있는 기능으로 전환하기에 충분합니다. 전체 API 레퍼런스와 예제는 OpenAI Images Edits API Integration Guide에서 확인할 수 있습니다.