이미지 편집 및 합성

이미지를 한 장 이상 업로드하고 프롬프트로 수정하거나 합성합니다.

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

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

시작하기 전에

필요한 것	설명
API 키	OfoxAI 콘솔 에서 생성한 뒤 코드의 `YOUR_OFOX_API_KEY`를 바꿔 넣으십시오
실행 환경	cURL은 이미지 디코딩에 `jq`가 필요합니다. Python은 `pip install openai`가 필요합니다. Node.js는 18 이상이면 되며 의존성이 없습니다
이미지	현재 디렉터리에 `input.png`를 두십시오. 여러 장을 합성하려면 `input2.png`도 추가하십시오. PNG 또는 JPEG, 장당 ≤ 15 MB
타임아웃	클라이언트 타임아웃을 600초로 설정하십시오. 고품질, 큰 크기, 편집은 몇 분이 걸릴 수 있습니다

코드에 사용되는 값

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

모델 IDopenai/gpt-image-2.5-sunburst예시 코드는 flare를 사용합니다. 편집에는 sunburst를 권장합니다

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

Python 의존성pip install openai

이미지 편집

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

cURL

Terminal


curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a wooden table, keep the subject unchanged" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",  # 본인의 키로 바꿔 넣으십시오
    base_url="https://api.ofox.io/v1",
)
 
result = client.images.edit(
    model="openai/gpt-image-2.5-flare",
    image=open("input.png", "rb"),
    prompt="Replace the background with a wooden table, keep the subject unchanged",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print("Saved output.png")

Node.js

edit.mjs


// Node.js 18 이상, 설치할 의존성 없음
import { readFileSync, writeFileSync } from "node:fs";
 
const form = new FormData();
form.append("model", "openai/gpt-image-2.5-flare");
form.append("image", new Blob([readFileSync("input.png")], { type: "image/png" }), "input.png");
form.append("prompt", "Replace the background with a wooden table, keep the subject unchanged");
form.append("quality", "low");
 
const res = await fetch("https://api.ofox.io/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OFOX_API_KEY", // 본인의 키로 바꿔 넣으십시오
  },
  body: form,
});
 
const json = await res.json();
if (!res.ok) throw new Error(JSON.stringify(json));
writeFileSync("output.png", Buffer.from(json.data[0].b64_json, "base64"));
console.log("Saved output.png");

size를 생략하면 모델이 출력 크기를 정하므로 원본과 다를 수 있습니다. 원본 크기를 유지하려면 size=1024x1024처럼 명시적으로 지정하십시오.

프롬프트 작성

무엇을 바꿀지와 무엇을 유지할지 두 가지를 분명히 적으십시오.

용도	프롬프트 예시
이미지 한 장 편집	배경을 나무 테이블로 바꾸고 피사체는 그대로 유지
여러 장 합성	첫 번째 이미지의 피사체를 두 번째 이미지의 배경 위에 배치

여러 장을 사용할 때는 업로드 순서대로 “첫 번째 이미지”, “두 번째 이미지”라고 지칭하십시오. 이미지의 일부분만 바꾸려면 부분 수정(인페인팅)이 더 안정적입니다.

여러 장 합성

여러 장의 참고 이미지를 한 번에 보냅니다. 업로드 순서가 프롬프트의 “첫 번째 이미지”, “두 번째 이미지”에 대응합니다. 현재 디렉터리에 input.png와 input2.png를 두십시오.

cURL

Terminal


# 요청당 최대 16장, 장당 ≤ 15 MB
curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image[]=@input.png" \
  -F "image[]=@input2.png" \
  -F "prompt=Place the subject of the first image onto the background of the second" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

공급자

공급자를 지정할 필요가 없습니다. 세 모델 모두 Azure와 OpenAI가 편집 엔드포인트를 제공하며, 게이트웨이가 요청을 자동으로 라우팅합니다.

콘텐츠 심사와 관련한 요구 사항이 있으면 공급자를 지정할 수 있습니다. 다만 편집 엔드포인트는 X-OfoxAI-Provider-Type 헤더만 받으며, 폼에 넣은 extra_body는 무시됩니다. 공급자를 지정하면 그 공급자를 사용할 수 없을 때 다른 공급자로 전환되지 않습니다. 공급자 지정을 참고하십시오.

파라미터 값

편집 엔드포인트 전용 파라미터입니다. model, n, output_format 등은 텍스트로 이미지 생성과 동일하게 동작합니다. 텍스트로 이미지 생성 · 파라미터 값을 참고하십시오.

필수

image필수fileform

편집할 이미지입니다. 여러 장일 때는 image[] 필드를 반복하고, Python SDK에서는 리스트로 전달합니다.

▸ 자세히

참고 이미지도 토큰으로 청구됩니다. 1024×1024 참고 이미지 1장은 입력 토큰 1,024개로 측정되었으며, 이 때문에 같은 크기라도 편집이 텍스트로 이미지 생성보다 비쌉니다.

▶고급 · 1X-OfoxAI-Provider-TypeExpand

X-OfoxAI-Provider-Typestringheader· 허용 값azure_foundryopenai

일반적으로 필요하지 않으며, 게이트웨이가 자동으로 라우팅합니다. 특정 공급자를 지정할 때만 사용하십시오.

업로드 제한

항목	제한
참고 이미지 1장	≤ 15 MB
요청 전체	≤ 50 MB
이미지 수	게이트웨이 제한은 없으나 16장 이하를 권장합니다
형식	PNG, JPEG

모델은 참고 이미지를 약 1024 px로 축소합니다. 5 MB를 넘는 파일은 업로드만 느려질 뿐 결과가 좋아지지 않습니다.

자주 발생하는 오류

오류	원인	해결 방법
`Invalid image file or mode`	업로드한 이미지가 표준 PNG 또는 JPEG가 아닙니다	PNG 또는 JPEG로 다시 내보내십시오
`Invalid file 'image[0]': unsupported mimetype`	업로드한 파일이 이미지가 아닙니다	PNG, JPEG 또는 WebP 이미지를 업로드하십시오
`does not support the 'input_fidelity' parameter`	`input_fidelity`를 보냈습니다	제거하십시오. 이 시리즈는 참고 이미지를 항상 높은 충실도로 처리합니다
`moderation_blocked`	프롬프트나 참고 이미지가 상위 안전 시스템에 의해 차단되었습니다	프롬프트나 참고 이미지를 바꿔 다시 시도하십시오
`provider_type_unavailable`	직접 지정한 공급자가 이 모델을 제공하지 않습니다	`X-OfoxAI-Provider-Type` 헤더를 제거하십시오
`Invalid size`	지정한 크기가 네 가지 규칙 중 하나를 어겼습니다	크기 참고
`404 model_not_found`	모델 ID의 철자나 대소문자가 잘못되었습니다	이 페이지에서 모델 ID를 복사하십시오

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

공식 문서

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