부분 수정(인페인팅)

마스크로 영역을 지정하고 그 영역만 다시 그립니다. 나머지 부분은 그대로 유지됩니다.

코드를 작성하지 않으신다면 내 도구에서 이미지 생성을 참고하십시오.

POST/v1/images/edits공통 파라미터

시작하기 전에

필요한 것	설명
API 키	OfoxAI 콘솔 에서 생성한 뒤 코드의 `YOUR_OFOX_API_KEY`를 바꿔 넣으십시오
실행 환경	cURL은 이미지 디코딩에 `jq`가 필요합니다. Python은 `pip install openai`가 필요하며, 마스크를 생성하려면 `pip install pillow`도 필요합니다. Node.js는 18 이상이면 되며 의존성이 없습니다
이미지	현재 디렉터리에 크기가 같은 `input.png`와 `mask.png`를 두십시오. 마스크가 없다면 아래 1단계에서 만드는 방법을 안내합니다
타임아웃	클라이언트 타임아웃을 600초로 설정하십시오. 고품질, 큰 크기, 편집은 몇 분이 걸릴 수 있습니다

코드에 사용되는 값

API 주소https://api.ofox.ai/v1

모델 IDopenai/gpt-image-2.5-flare

API 키코드의 YOUR_OFOX_API_KEY를 본인의 키로 바꿔 넣으십시오

Python 의존성pip install openai pillowpillow는 마스크를 만드는 데 사용합니다

마스크 요구 사항

원본

마스크가운데는 투명, 나머지는 불투명

→

결과투명한 영역만 다시 그림

설명용 그림이며 실제 생성 결과가 아닙니다

알파 채널이 있는 PNG여야 합니다. JPEG와 불투명 PNG는 동작하지 않습니다.
원본 이미지와 크기가 정확히 같아야 합니다.
투명한 픽셀은 다시 그려지고, 불투명한 픽셀은 원본이 유지됩니다.
편집 엔드포인트에서만 동작합니다. 텍스트로 이미지 생성에 보내면 무시됩니다.

단계

마스크 만들기

이미 마스크가 있다면 이 단계를 건너뛰십시오.

이 코드는 현재 디렉터리의 input.png를 읽어 가운데 40% 크기의 사각형을 투명하게 만든 뒤 mask.png로 저장합니다.

make_mask.py


from PIL import Image, ImageDraw
 
src = Image.open("input.png")
mask = Image.new("RGBA", src.size, (0, 0, 0, 255))          # 완전 불투명 = 전부 유지
w, h = src.size
ImageDraw.Draw(mask).rectangle(                              # 투명 영역 = 다시 그릴 부분
    (int(w * 0.3), int(h * 0.3), int(w * 0.7), int(h * 0.7)), fill=(0, 0, 0, 0)
)
mask.save("mask.png")

요청 보내기

아래 예시는 모두 그대로 실행하여 확인했습니다. 결과는 현재 디렉터리에 output.png로 저장됩니다.

cURL

Terminal


# mask.png: input.png와 같은 크기, 알파 채널 포함, 투명 영역 = 다시 그릴 부분
curl -s https://api.ofox.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=An orange cat sitting in the center, background and everything else unchanged" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

프롬프트 작성

추가할 내용만 적지 말고 수정 후 이미지 전체가 어떻게 보여야 하는지를 설명하십시오.

	프롬프트	실측 결과
✅	가운데에 주황색 고양이가 앉아 있고, 배경과 나머지는 그대로	가운데에 고양이가 그려지고 나머지는 변하지 않음
❌	투명한 영역에 고양이를 그려 줘	모델이 “투명”을 내용으로 받아들여 체크무늬 배경을 그림

실측 결과

마스크 바깥 영역은 거의 변하지 않습니다. 원본과의 평균 픽셀 차이는 2/255 미만이었습니다.

비교를 위해 같은 이미지를 마스크 없이 편집했을 때는 같은 영역이 120/255만큼 변했습니다.

문제 해결

증상	원인	해결 방법
`Invalid image file or mode` 오류	마스크가 알파 채널이 있는 PNG가 아닙니다	위 1단계의 코드로 다시 생성하십시오
이미지 전체가 바뀜	마스크가 적용되지 않았습니다. 텍스트로 이미지 생성 엔드포인트로 보냈거나 마스크가 완전히 불투명합니다	`/v1/images/edits`를 호출하는지, 마스크에 투명한 영역이 있는지 확인하십시오
체크무늬 배경이 나타남	프롬프트에 “투명한 영역”을 언급했습니다	프롬프트 작성처럼 이미지 전체를 설명하십시오

그 밖의 오류는 전체 오류 표를 참고하십시오.

공식 문서

OpenAI 문서는 OpenAI를 직접 호출할 때의 동작을 설명합니다. OfoxAI를 통해 호출할 때는 이 시리즈 문서의 실측 결과가 우선합니다. 예를 들어 편집 시 공급자를 지정할 필요가 없습니다.