Image Edits

지원 범위와 운영 방식

현재 이미지 편집은 gpt-image-2를 지원하며 AI 게이트웨이를 사용하는 모든 스페이스에 기본 제공됩니다. 별도 모델 배급 요청이나 OpenAI API 키는 필요하지 않습니다.

기존 AI 게이트웨이 API 키와 OpenAI 호환 클라이언트를 사용합니다. 요청에는 다른 게이트웨이 호출과 같은 인증 및 월 한도가 적용되고, 비용과 사용량도 같은 운영 화면에서 확인합니다. 지원 모델이나 입력 조건이 추가되면 에셋의 현재 정보를 기준으로 선택합니다.

요청 필드

요청 본문은 multipart/form-data로 보냅니다. 파일의 multipart boundary가 포함된 Content-Type은 HTTP 클라이언트가 만들도록 둡니다.

선택 필드와 파일 형식의 세부 지원 범위는 모델에 따라 달라질 수 있습니다. 오류가 반환되면 detail을 확인해 입력 파일이나 옵션을 수정합니다.

응답 (200)

편집된 이미지는 응답의 data[].b64_json에 base64 문자열로 들어옵니다.

{
  "created": 1786723200,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ],
  "estimated_cost": {
    "amount": "0.04000000",
    "currency": "unit",
    "disclaimer": "Estimated based on published pricing. Actual charges may differ."
  }
}

클라이언트는 base64 문자열을 디코딩해 파일이나 객체 저장소에 보관합니다. 응답 문자열 전체를 일반 애플리케이션 로그에 남기지 마세요.

estimated_cost는 이 이미지 편집 호출의 비용입니다. 작업별로 비용을 묶으려면 응답의 amount와 currency를 고객 시스템의 작업 식별자와 함께 저장합니다. 자세한 의미는 요청별 비용을 확인합니다.

요청과 결과 저장 예시

아래 예제는 현재 디렉터리의 input.png를 편집합니다. 셸 또는 서버 환경에 설정된 LETSUR_API_KEY를 사용하며, 키 설정은 첫 API 호출에서 확인합니다.

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  test -f input.png || { echo "input.png 파일이 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/images/edits \
    --header @- \
    -F "model=gpt-image-2" \
    -F "prompt=배경을 푸른 하늘로 바꿔줘" \
    -F "image=@input.png" <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

import base64
import os
from pathlib import Path
 
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["LETSUR_API_KEY"],
    base_url="https://gw.letsur.ai/v1",
)
 
with Path("input.png").open("rb") as image:
    response = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="배경을 푸른 하늘로 바꿔줘",
    )
 
image_base64 = response.data[0].b64_json
if not image_base64:
    raise RuntimeError("이미지 데이터가 없습니다.")
 
Path("edited.png").write_bytes(base64.b64decode(image_base64))

제약과 오류

• 이 엔드포인트는 스트리밍을 지원하지 않습니다. multipart/form-data 요청에 stream=true를 보내지 않습니다.
• invalid_image_file (400)이면 파일 형식, 크기 또는 이미지 개수를 확인합니다.
• image_fetch_error (400)이면 입력 이미지를 읽을 수 있는지 확인한 뒤 다시 보냅니다.
• invalid_model (400)이면 모델은 존재하지만 이 엔드포인트에서 지원하지 않는 모델입니다. gpt-image-2를 사용했는지 확인합니다.
• model_not_found (404)이면 현재 카탈로그에 없는 모델 코드입니다. 에셋에서 코드를 다시 확인합니다.
• 인증, IP 제한, 유닛과 한도 오류는 오류 처리에서 확인합니다.