메인 콘텐츠로 건너뛰기
OpenAI 이미지 편집 서비스는 임의의 여러 장의 이미지와 지시를 입력하면 수정된 이미지를 출력합니다. 이 문서는 OpenAI 이미지 편집 API 작업의 사용 흐름을 주로 설명하며, 이를 통해 공식 OpenAI 이미지 편집 기능을 쉽게 사용할 수 있습니다.

​
신청 흐름

OpenAI 이미지 편집 API를 사용하려면 먼저 OpenAI 이미지 편집 API 페이지에서 “Acquire” 버튼을 클릭하여 요청에 필요한 자격 증명을 얻습니다: 로그인 또는 등록하지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다. 첫 번째 신청 시 무료 한도가 제공되어 해당 API를 무료로 사용할 수 있습니다.

​
기본 사용

다음으로 코드를 사용하여 호출할 수 있으며, 아래는 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.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 this items in it'
이 인터페이스를 처음 사용할 때는 최소한 네 가지 내용을 입력해야 합니다. 하나는 authorization으로, 드롭다운 목록에서 선택하면 됩니다. 또 다른 매개변수는 model로, model은 OpenAI 공식 모델 카테고리를 선택하는 것입니다. 여기서는 주로 1종의 모델이 있으며, 자세한 내용은 제공된 모델을 참조할 수 있습니다. 마지막 매개변수는 prompt로, 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)

# Save the image to a file
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에서는 다음 명령어로 환경 변수를 설정할 수 있습니다: 
export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}
호출 후, 현재 디렉토리에 gift-basket.png라는 이미지가 생성된 것을 확인할 수 있으며, 구체적인 결과는 다음과 같습니다:

이렇게 우리는 이미지 편집 작업을 완료했습니다. 현재 공식 Edits 작업은 두 가지 모델만 지원하며, 각각 dall-e-2와 gpt-image-1입니다.

​
비동기 콜백

OpenAI 이미지 편집 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로 설정하고, 다음 코드와 같이 해당 매개변수를 입력할 수 있습니다: 
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"
호출 후, 즉시 다음과 같은 결과를 얻을 수 있습니다: 
{
  "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를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 저희 기술 지원 팀에 문의해 주십시오.