이미지 생성

Venice API로 텍스트 프롬프트에서 이미지를 생성하는 방법을 모델 크기 옵션, 스타일 프리셋, LoRA 강도, safe mode, 바이너리 출력과 함께 안내합니다.

Venice의 이미지 생성은 동기 방식입니다. /image/generate에 prompt를 보내면 같은 응답에 JSON 내부의 base64로, 또는 return_binary가 true일 때는 raw 바이너리로 이미지가 돌아옵니다.

​

Endpoint

Endpoint	Purpose	When to use
POST /image/generate	Venice 네이티브 이미지 생성 API	전체 기능 지원이 필요할 때 사용
GET /image/styles	사용 가능한 스타일 프리셋 목록	style_preset을 보내기 전에 사용
POST /images/generations	OpenAI 호환 이미지 생성 API	기존 OpenAI 이미지 클라이언트를 마이그레이션할 때 사용

​

1단계: 생성 요청 보내기

크기 지정은 모델별입니다. 일부 모델은 명시적 width와 height를 받습니다. 일부는 aspect_ratio를 노출하고, 해상도 등급 모델은 aspect_ratio와 함께 1K, 2K, 4K 같은 resolution 값을 노출합니다.

픽셀 기반 크기 예시:

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

{
  "model": "venice-sd35",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
  "negative_prompt": "blurry, low quality, distorted anatomy, text, watermark",
  "width": 1024,
  "height": 1024,
  "format": "webp"
}

종횡비 크기 예시:

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

{
  "model": "qwen-image-2",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "format": "webp"
}

해상도 등급 크기 예시:

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

{
  "model": "gpt-image-2",
  "prompt": "A cinematic wide shot of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "format": "png"
}

다른 해상도 등급 모델에도 같은 패턴이 적용됩니다:

{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

각 모델이 어떤 크기 필드를 받는지는 이미지 모델 또는 Models API에서 확인하세요.

응답(200):

{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}

images 배열에는 base64로 인코딩된 이미지 데이터가 들어 있습니다. 첫 항목을 디코딩해 저장하거나 표시하세요. timing.total은 전체 요청 소요 시간(밀리초)입니다.

​

2단계: 이미지 디코딩 및 저장

Python

import base64
import os
import requests

response = requests.post(
    "https://api.venice.ai/api/v1/image/generate",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "venice-sd35",
        "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
        "width": 1024,
        "height": 1024,
        "format": "webp",
    },
)

data = response.json()
image_bytes = base64.b64decode(data["images"][0])

with open("output.webp", "wb") as f:
    f.write(image_bytes)

print(f"Saved image from request {data['id']}")

​

3단계: JSON 대신 바이너리 반환(선택)

응답 본문 자체를 이미지 파일로 받고 싶다면 return_binary: true로 설정하세요. base64 디코딩 없이 이미지를 바로 스트리밍하거나 저장하고 싶을 때 유용합니다.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.png \
  -d '{
    "model": "qwen-image-2",
    "prompt": "Minimalist poster of a moonlit Venetian bridge in deep blue tones",
    "format": "png",
    "return_binary": true
  }'

return_binary가 true이면 응답 본문은 요청한 format에 따라 raw image/jpeg, image/png, 또는 image/webp 데이터입니다.

variants는 return_binary가 false일 때만 지원됩니다.

---

​

4단계: 사용 가능한 이미지 스타일 목록 보기(선택)

style_preset을 사용하려면 먼저 /image/styles에서 사용 가능한 스타일을 가져오세요:

curl https://api.venice.ai/api/v1/image/styles \
  -H "Authorization: Bearer $VENICE_API_KEY"

응답(200):

[
  "3D Model",
  "Analog Film",
  "Anime",
  "Cinematic",
  "Digital Art"
]

그런 다음 그 값 중 하나를 생성 요청에 전달하세요:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}

프리셋 이름을 짐작하지 않고 정확히 알고 싶을 때 styles endpoint를 사용하세요.

---

​

요청 파라미터

Parameter	Type	Required	Default	Description
model	string	예	-	생성에 사용할 모델 ID
prompt	string	예	-	생성할 내용
negative_prompt	string	아니오	-	이미지에서 피할 내용
width	integer	아니오	1024	venice-sd35, qwen-image 같은 픽셀 기반 모델의 출력 너비(픽셀)
height	integer	아니오	1024	venice-sd35, qwen-image 같은 픽셀 기반 모델의 출력 높이(픽셀)
format	string	아니오	webp	출력 포맷: jpeg, png, webp
variants	integer	아니오	1	생성할 이미지 수(1-4). return_binary가 false일 때만
return_binary	boolean	아니오	false	base64 JSON 대신 raw 이미지 바이트 반환
safe_mode	boolean	아니오	true	활성화 시 성인 콘텐츠 블러 처리
seed	integer	아니오	무작위	더 일관된 반복을 위해 동일 seed 재사용
cfg_scale	number	아니오	모델별	값이 높을수록 모델이 prompt를 더 충실히 따름
lora_strength	integer	아니오	-	모델에 내장된 LoRA의 강도(0-100). 추가 LoRA가 없는 모델에서는 무시됨
style_preset	string	아니오	-	Image Styles의 프리셋 스타일 적용
aspect_ratio	string	조건부	-	qwen-image-2, gpt-image-2, nano-banana-2, nano-banana-pro 같은 비율 기반 크기 모델에서 사용
resolution	string	조건부	-	1K, 2K, 4K 같은 해상도 등급을 지원하는 모델에서 사용
enable_web_search	boolean	조건부	false	지원 모델이 최신 웹 정보를 사용하게 함. 추가 비용 발생

검증은 모델별입니다. 여러 모델에 걸쳐 파라미터를 사용하기 전에 이미지 모델과 Models API를 확인하세요.

---

​

모델별 옵션

​

고해상도 생성

일부 이미지 모델은 선택 가능한 resolution 등급 없이 aspect_ratio를 지원합니다. 예를 들어 qwen-image-2는 종횡비를 받아 모델별 출력 크기에 매핑합니다:

{
  "model": "qwen-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9"
}

다른 이미지 모델은 aspect_ratio와 resolution 등급을 함께 지원합니다. 예를 들어 gpt-image-2, nano-banana-2, nano-banana-pro는 1K, 2K, 4K를 지원합니다:

{
  "model": "gpt-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "4K"
}

{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

어떤 모델이 더 높은 해상도를 지원하는지, 그리고 가격은 어떻게 되는지는 이미지 모델에서 확인하세요.

​

LoRA 지원

일부 이미지 모델에는 추가 LoRA가 내장되어 있습니다. lora_strength 파라미터(정수, 0에서 100)는 내장 LoRA가 얼마나 강하게 적용되는지 제어합니다. 추가 LoRA를 사용하는 모델에만 영향을 주며, 다른 모델은 이를 무시합니다.

API는 커스텀 LoRA 파일의 업로드나 로드를 지원하지 않습니다. 모델에 번들된 LoRA를 나열하는 endpoint도 없습니다. LoRA 사용은 LoRA가 포함된 모델에서 lora_strength를 조정하는 것으로 제한됩니다.

​

성인 콘텐츠 및 safe mode

safe_mode는 생성 output의 성인 콘텐츠를 블러 처리할지 여부를 제어합니다. 기본값은 true입니다. 사용 사례에서 성인 콘텐츠가 허용되고 원본 output을 원한다면 false로 설정하세요:

{
  "model": "lustify-v8",
  "prompt": "…",
  "safe_mode": false
}

일부 이미지 모델은 성인 / 무검열 생성을 위해 특별히 설계되어 safe_mode: false와 잘 어울립니다. 가격 페이지의 예시로는 lustify-sdxl, lustify-v7, lustify-v8이 있습니다. 현재 목록과 모델별 비용은 이미지 모델과 가격을 참고하세요.

기존 이미지 편집의 경우, 기본 편집 모델 qwen-edit는 노골적인 성적 이미지를 차단합니다. 무검열 편집이 필요하다면 이미지 편집을 통해 qwen-edit-uncensored를 사용하세요.

safe_mode가 활성화되어 있고 모델이 블러 처리되거나 조정된 output을 반환할 때, 프로그래밍 방식으로 이를 감지해야 한다면 x-venice-is-blurred와 x-venice-is-content-violation 응답 헤더를 확인하세요.

​

스타일 프리셋

선택한 모델이 지원한다면 style_preset을 사용해 전체 prompt를 다시 쓰지 않고도 출력을 유도할 수 있습니다. 유효한 프리셋 이름은 Image Styles에서 가져올 수 있습니다:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}

현재 스타일 목록은 Image Styles를 참고하세요.

---

​

OpenAI 호환 endpoint

OpenAI 이미지 SDK나 기존 DALL-E 통합을 이미 사용하고 있다면, Venice는 POST /images/generations도 지원합니다. 더 단순한 요청 포맷을 제공하지만, Venice 네이티브 endpoint보다 기능이 적습니다.

요청:

{
  "model": "qwen-image-2",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

빠른 마이그레이션에는 OpenAI 호환 라우트를 사용하세요. cfg_scale, style_preset, variants, 바이너리 응답 같은 Venice 전용 옵션이 필요하면 /image/generate를 사용하세요.

​

/images/generations에서 성인 콘텐츠 블러 제어하기

OpenAI 호환 endpoint는 safe_mode를 받지 않습니다. 이를 보내면 Unrecognized key(s) in object: 'safe_mode'와 함께 400이 반환됩니다. 대신 OpenAI 스타일의 moderation 파라미터를 사용하세요:

Value	Behavior
auto (default)	Safe Venice 모드를 활성화하고 성인 콘텐츠를 블러 처리합니다
low	Safe Venice 모드를 비활성화하고, 블러 처리되지 않은 output을 반환합니다

{
  "model": "lustify-v8",
  "prompt": "…",
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "low"
}

safe_mode는 네이티브 POST /image/generate endpoint에서만 동작합니다. moderation은 OpenAI 호환 POST /images/generations endpoint에서만 동작합니다.

---

​

Prompt 작성 팁

1. 피사체로 시작한 다음 매체, 조명, 구도, 분위기를 더하세요.
2. 메인 prompt에 과부하를 주지 말고 피해야 할 세부 사항은 negative_prompt에 넣으세요.
3. 반복 시 seed를 재사용해 구도를 완전히 바꾸지 않고 prompt 변화의 비교가 가능하게 하세요.
4. 크기는 모델을 의식해서 설정하세요. 어떤 모델은 width/height를, 어떤 모델은 aspect_ratio를, 해상도 등급 모델은 aspect_ratio와 resolution을 함께 사용합니다.
5. 탐색 단계에서는 variants를 사용하고, 방향이 정해지면 단일 출력으로 돌아오세요.

---

​

에러

Status	Meaning	Action
400	잘못된 요청 파라미터	필드 이름, 타입, 모델별 제약 확인
401	인증 실패 또는 모델이 더 높은 접근 등급 요구	API 키와 모델 접근 권한 확인
402	잔액 부족	venice.ai/settings/api에서 크레딧 추가
415	잘못된 content type	Content-Type: application/json으로 JSON 전송
429	Rate limit 초과 또는 모델 과부하	백오프와 함께 재시도, Retry-After 헤더 확인
500	추론 처리 실패	요청 재시도
503	모델 용량 초과	잠시 후 재시도

Safe Venice가 활성화된 경우, 프로그래밍 방식으로 모더레이션 결과를 감지하려면 x-venice-is-blurred, x-venice-is-content-violation 같은 응답 헤더를 확인하세요.

---

​

사용 가능한 모델

현재 모델 목록, 가격, 기능 지원은 이미지 모델을 참고하세요.