이미지 편집

Venice API의 /image/edit, multi-edit 레이어, 마스크, safe mode 제어를 사용해 이미지를 편집·인페인팅하고 배경을 제거하세요.

Venice의 이미지 편집은 동기 방식입니다. 원본 이미지를 /image/edit 또는 /image/multi-edit로 보내면 편집된 결과가 같은 응답에 raw 이미지 파일로 돌아옵니다. 누끼 작업에는 /image/background-remove가 투명한 PNG를 반환합니다.

이미지 편집 endpoint는 실험적이며 모델별 동작은 시간이 지남에 따라 변경될 수 있습니다.

​

Endpoint

Endpoint	Purpose	Best for
POST /image/edit	prompt로 단일 이미지 편집	일반 편집과 prompt 기반 inpainting
POST /image/multi-edit	1-3장의 레이어드 이미지로 편집	마스크나 오버레이가 있는 더 제어된 편집
POST /image/background-remove	이미지에서 배경 제거	제품, 인물, 자산을 위한 투명 컷아웃

Venice는 OpenAI 호환 /images/edits endpoint를 제공하지 않습니다. 유일한 OpenAI 호환 이미지 경로는 생성을 위한 POST /images/generations입니다. 편집에는 네이티브 POST /image/edit endpoint를 사용하세요.

​

어떤 endpoint를 언제 사용하나요

• 원본 이미지가 하나이고 prompt로 일부를 변경, 제거, 재스타일링하고 싶다면 /image/edit를 사용하세요.
• 마스크, 오버레이, 참조 레이어를 통한 추가 제어가 필요하면 /image/multi-edit를 사용하세요.
• 깔끔한 전경 피사체와 투명도만 원한다면 /image/background-remove를 사용하세요.

Inpainting에는 /image/edit 또는 /image/multi-edit를 사용하세요. /image/generate의 기존 inpaint 파라미터는 deprecated입니다.

편집 endpoint에서 enhance_prompt: true로 설정하면, 비전 인식 enhancer가 입력 이미지 하나 또는 여러 개를 분석해 편집 전에 지시를 다시 작성합니다. 동작 방식, 가격, 응답 헤더 관련 세부 정보는 Prompt Enhancement를 참조하세요.

​

1단계: 단일 이미지 편집

단일 이미지 편집은 가장 단순한 inpainting 흐름입니다. 이미지 한 장과 “remove the sign”, “change the sky to sunrise”, “replace the background with a studio backdrop” 같은 짧은 prompt를 함께 보내세요.

요청:

POST https://api.venice.ai/api/v1/image/edit
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-edit",
  "prompt": "Replace the cloudy sky with a warm sunrise while preserving the buildings and canal",
  "image": "https://example.com/venice-canal.jpg"
}

응답(200): 응답 본문은 raw 이미지 바이너리 데이터입니다. 그대로 파일에 저장하세요. output_format이 파일 타입을 제어하는 방법은 응답 포맷을 참조하세요.

Python

import base64
import os
import requests

with open("input.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.venice.ai/api/v1/image/edit",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-edit",
        "prompt": "Remove the tourist crowd from the square and keep the architecture intact",
        "image": image_base64,
    },
)

with open("edited.png", "wb") as f:
    f.write(response.content)

​

2단계: 마스크나 레이어드 inpainting에는 multi-edit 사용

/image/multi-edit는 최대 세 장의 이미지를 받습니다. 첫 번째 이미지가 base 이미지입니다. 나머지 이미지는 편집 레이어나 마스크로 취급되어, prompt만으로 편집하는 것보다 더 많은 제어권을 줍니다.

다음과 같은 경우에 더 나은 선택입니다:

• 특정 영역을 마스크로 타겟팅하고 싶을 때
• 기존 구도에 오버레이를 결합하고 싶을 때
• 단일 이미지 prompt가 할 수 있는 것보다 더 엄격하게 편집을 제약하고 싶을 때

JSON 요청:

{
  "modelId": "qwen-edit",
  "prompt": "Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective",
  "images": [
    "https://example.com/street-scene.png",
    "https://example.com/billboard-mask.png"
  ]
}

Multipart 요청:

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=qwen-edit" \
  -F "prompt=Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective" \
  -F "images=@street-scene.png" \
  -F "images=@billboard-mask.png" \
  -o multi-edited.png

/image/edit와 마찬가지로 응답 본문은 raw 이미지 데이터입니다.

/image/multi-edit는 현재 요청 스키마에서 model이 아닌 modelId 필드를 사용합니다.

---

​

Inpainting 팁

Prompt 기반 inpainting은 지시가 짧고 국소적일 때 가장 잘 동작합니다:

• remove the tree
• change the sky to sunset
• replace the logo with a blank sign
• restore the torn corner of the photo

더 넓은 장면 변경의 경우, 유지되어야 할 부분을 함께 설명하세요:

Replace the background with a modern photo studio backdrop while preserving the subject pose, facial features, and clothing.

편집이 계속 잘못된 영역에 영향을 준다면 /image/edit에서 /image/multi-edit로 전환해 마스크나 오버레이 레이어를 제공하세요.

---

​

3단계: 배경 제거

전경 피사체를 투명 배경에 격리하고 싶다면 /image/background-remove를 사용하세요. 이 endpoint는 알파 투명도가 있는 PNG를 반환합니다.

이미지 URL 사용:

curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o cutout.png \
  -d '{
    "image_url": "https://example.com/product-photo.jpg"
  }'

로컬 파일 업로드 사용:

curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "image=@product-photo.jpg" \
  -o cutout.png

배경 제거의 활용처:

• 이커머스 제품 사진
• 프로필 사진 및 인물 사진
• 새 배경 위에 배치할 자산

---

​

응답 포맷

/image/edit와 /image/multi-edit는 편집된 이미지를 항상 raw 바이너리 데이터(image/png, image/jpeg, 또는 image/webp)로 반환합니다. 편집 endpoint는 response_format 파라미터를 받지 않습니다. /images/generations처럼 b64_json이나 url 옵션도 없습니다. 결과가 JSON 안에 필요하다면 바이너리 응답을 직접 코드에서 base64로 인코딩하세요.

output_format으로 파일 타입을 제어하세요:

• output_format은 jpeg, jpg, png, 또는 webp를 받습니다.
• 생략하면 resolution에서 포맷이 추론됩니다: 1K 편집은 PNG, 2K와 4K 편집은 JPEG입니다.

---

​

요청 파라미터

​

/image/edit

Parameter	Type	Required	Default	Description
image	파일, base64 문자열, 또는 URL	예	-	편집할 원본 이미지
prompt	string	예	-	편집을 위한 텍스트 지시
model	string	아니오	qwen-edit	편집 모델 ID
aspect_ratio	string	아니오	모델 기본값	지원 모델의 출력 비율
resolution	string	아니오	1K	출력 이미지의 해상도 등급(1K, 2K, 4K). 지원 값은 모델별로 다름
output_format	string	아니오	resolution에서 추론	출력 파일 타입: jpeg, jpg, png, 또는 webp
enhance_prompt	boolean	아니오	false	입력 이미지를 분석하고 추론 전에 편집 지시를 다시 작성
safe_mode	boolean	아니오	true	편집된 결과에서 성인 콘텐츠를 흐리게 처리합니다. false로 설정하면 흐림이 비활성화됩니다
modelId	string	Deprecated	-	model의 deprecated 별칭

​

/image/multi-edit

Parameter	Type	Required	Default	Description
images	1-3개의 파일, base64 문자열, 또는 URL 배열	예	-	첫 이미지는 base 이미지, 나머지는 편집 레이어나 마스크
prompt	string	예	-	레이어를 결합하거나 편집하는 방법에 대한 텍스트 지시
modelId	string	아니오	qwen-edit	편집 모델 ID
resolution	string	아니오	1K	출력 이미지의 해상도 등급(1K, 2K, 4K). 지원 값은 모델별로 다름
output_format	string	아니오	resolution에서 추론	출력 파일 타입: jpeg, jpg, png, 또는 webp
enhance_prompt	boolean	아니오	false	입력 이미지들을 분석하고 추론 전에 편집 지시를 다시 작성
safe_mode	boolean	아니오	true	편집된 결과에서 성인 콘텐츠를 흐리게 처리합니다. false로 설정하면 흐림이 비활성화됩니다

​

/image/background-remove

Parameter	Type	Required	Description
image	파일 또는 base64 문자열	image나 image_url 중 하나	잘라낼 원본 이미지
image_url	string	image나 image_url 중 하나	잘라낼 공개 이미지 URL

/image/background-remove는 고정된 내부 모델을 사용합니다. model 필드를 받지 않습니다. 필드를 함께 보내면(예: "model": "bria-bg-remover") 400 invalid model id가 반환됩니다.

​

성인 콘텐츠 및 safe mode

/image/edit와 /image/multi-edit 모두 safe_mode를 받습니다(기본값: true). 활성화되면 편집된 output의 성인 콘텐츠가 블러 처리됩니다. 블러 처리되지 않은 output을 받으려면 safe_mode: false로 설정하세요:

{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}

기본 qwen-edit 모델은 safe_mode와 무관하게 여전히 노골적 성적 이미지와 실제 폭력을 차단합니다. 무검열 편집을 원한다면 qwen-edit-uncensored를 사용하세요.

Endpoint 간 모더레이션 이름 차이는 사람들을 헷갈리게 만드는 지점입니다:

Endpoint	Field to disable blur
POST /image/edit, POST /image/multi-edit	safe_mode: false
POST /image/generate (네이티브 생성)	safe_mode: false
POST /images/generations (OpenAI 호환 생성)	moderation: "low"

/images/generations에 safe_mode를 전달하면 Unrecognized key(s) in object: 'safe_mode'와 함께 400이 반환됩니다.

---

​

지원 input 포맷

Endpoint	JSON input	Multipart input	Output
/image/edit	Base64 문자열 또는 URL	파일 업로드	output_format에 따라 image/png, image/jpeg, 또는 image/webp
/image/multi-edit	Base64 문자열 또는 URL	파일 업로드	output_format에 따라 image/png, image/jpeg, 또는 image/webp
/image/background-remove	Base64 문자열 또는 URL	파일 업로드	image/png

편집 endpoint의 경우 이미지 크기는 최소 65536 픽셀, 최대 33177600 픽셀이어야 합니다. 업로드 파일은 25MB 미만이어야 합니다.

---

​

모델 및 가격

기본 편집 모델은 qwen-edit이며 편집당 $0.04** 입니다. 편집 가능한 다른 모델은 가격과 제약이 다를 수 있습니다. Prompt enhancement는 편집 가격에 **적용된 재작성당$0.04를 추가합니다.

참고:

• 이미지 가격
• type=inpaint로 Models API

---

​

에러

Status	Meaning	Action
400	잘못된 요청 파라미터	이미지 수, 필드 이름, 입력 포맷 확인
401	인증 실패	API 키 확인
402	잔액 부족	venice.ai/settings/api에서 크레딧 추가
415	잘못된 content type	JSON 또는 multipart form-data를 올바르게 사용
429	Rate limit 초과 또는 모델 과부하	백오프와 함께 재시도, Retry-After 헤더 확인
500	추론 처리 실패	요청 재시도
503	모델 용량 초과	잠시 후 재시도

일부 편집 모델은 이미지 생성 모델보다 엄격한 콘텐츠 정책을 가집니다. 예를 들어 qwen-edit는 노골적 성적 이미지, 미성년자 성적 묘사, 실제 폭력과 관련된 요청을 차단합니다.

---

​

관련 워크플로

• 기존 이미지가 아닌 텍스트에서 시작한다면 이미지 생성을 사용하세요.
• 비전 인식 편집 재작성이 어떻게 동작하는지 알아보려면 Prompt Enhancement를 사용하세요.
• 생성, 편집, 향상 모델 패밀리를 비교하려면 이미지 모델을 참고하세요.
• 전체 스키마는 Image Edit API, Multi-Edit API, Background Remove API를 참고하세요.