Image Generation | Venice API Docs

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 값을 노출합니다.

qwen-image, qwen-image-3, qwen-image-3-pro, qwen-image-2-1-turbo, qwen-image-2-1-pro는 더 이상 width나 height를 받지 않습니다. 둘 중 하나를 보내면 400과 함께 *“width and height are no longer supported for this model. Use aspect_ratio instead.”*가 반환됩니다. 크기 필드를 선택하기 전에 GET /models?type=image의 model_spec.constraints를 확인하세요.

픽셀 기반 크기 예시:

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단계: 이미지 디코딩 및 저장

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']}")

import fs from "fs";

const response = await fetch("https://api.venice.ai/api/v1/image/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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",
  }),
});

const data = await response.json();
const imageBuffer = Buffer.from(data.images[0], "base64");
fs.writeFileSync("output.webp", imageBuffer);

console.log(`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

이 endpoint는 공개되어 있으며 API 키가 필요하지 않습니다. 응답(200):

{
  "object": "list",
  "data": [
    "3D Model",
    "Analog Film",
    "Anime",
    "Cinematic",
    "Digital Art"
  ]
}

스타일 이름은 최상위 레벨이 아니라 data 안에 있습니다 — 응답 객체를 직접 순회하지 말고 response.data를 읽으세요. 그런 다음 그 값 중 하나를 생성 요청에 전달하세요:

{
  "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`일 때만. 공급자의 명시적인 콘텐츠 정책 거부로 일부 variant가 누락될 수 있음. 부분 variant 결과 참조
`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의 프리셋 스타일 적용
`style_references`	array	아니오	-	출력의 미적 스타일을 유도하는 스타일 참조 이미지. 각 항목은 `{ "image": <url or base64>, "strength": <0.1-1> }` 형식. 지원 모델에서만 사용 가능. 스타일 참조 참조
`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`	지원 모델이 최신 웹 정보를 사용하게 함. 추가 비용 발생
`transparent_background`	boolean	아니오	`false`	실제 알파 채널이 포함된 PNG 또는 WebP 반환. `supportsTransparentBackground: true`인 모델과 `png` 또는 `webp` `format`이 필요. 투명 배경 이미지 참조

검증은 모델별입니다. 여러 모델에 걸쳐 파라미터를 사용하기 전에 이미지 모델과 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(integer, 0~100)는 LoRA를 얼마나 강하게 적용할지 설정하며, LoRA를 사용하는 모델에만 영향을 줍니다. API는 사용자 지정 LoRA 파일을 받지 않으며, 모델이 사용하는 LoRA를 나열하는 엔드포인트도 없습니다. lora_strength가 유일한 LoRA 제어 수단입니다.

성인 콘텐츠 및 safe mode

safe_mode는 생성 output의 성인 콘텐츠를 블러 처리할지 여부를 제어합니다. 기본값은 true이므로, safe_mode: false를 보내지 않으면 성인 콘텐츠로 분류된 이미지는 블러 처리되어 반환됩니다:

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

블러 처리되지 않은 성인(NSFW) 이미지는 모든 API 사용자가 이용할 수 있습니다. Pro 구독이 필요하지 않으며, Venice 앱의 성인 콘텐츠 필터 설정은 API를 통한 이미지 요청에 영향을 주지 않습니다. 일부 이미지 모델은 성인 / 무검열 생성을 위해 특별히 설계되어 safe_mode: false와 잘 어울립니다. 가격 페이지의 예시로는 lustify-sdxl, lustify-v7, lustify-v8이 있습니다. 현재 목록과 모델별 비용은 이미지 모델과 가격을 참고하세요. 기존 이미지 편집의 경우, 기본 편집 모델은 firered-image-edit입니다. 콘텐츠 정책은 편집 모델에 따라 다르며, 무검열 편집이 필요하다면 이미지 편집을 통해 qwen-edit-uncensored를 사용하세요. safe_mode가 활성화되어 있고 모델이 블러 처리되거나 조정된 output을 반환할 때, 프로그래밍 방식으로 이를 감지해야 한다면 x-venice-is-blurred와 x-venice-is-content-violation 응답 헤더를 확인하세요.

서드파티 앱을 사용 중인가요? 앱이 safe_mode: false를 보내거나 OpenAI 호환 엔드포인트에서 moderation: "low"를 보내지 않는 한 성인 이미지는 블러 처리된 상태로 유지됩니다(아래 참고).

스타일 프리셋

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

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

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

스타일 참조

style_references는 style_preset보다 한 단계 더 나아갑니다. 이름이 정해진 프리셋 대신 하나 이상의 참조 이미지를 기반으로 생성을 조정합니다. 각 항목에는 image와 선택 사항인 strength가 있습니다:

{
  "model": "krea-v2-large",
  "prompt": "A quiet Venetian courtyard at golden hour",
  "style_references": [
    {
      "image": "https://example.com/reference-painting.png",
      "strength": 0.5
    }
  ]
}

Field	Type	Required	Description
`image`	string	예	`http://` 또는 `https://` URL, base64 문자열, 또는 base64 data URI 형식의 참조 이미지. 래스터 이미지(JPEG, PNG, WebP, HEIF, HEIC, AVIF)여야 하며, SVG는 사용할 수 없고 8 MB 미만이어야 함
`strength`	number	아니오	참조가 출력에 영향을 주는 정도. `0.1`부터 `1`까지이며 기본값은 `0.5`. `supportsStyleReferenceStrength`가 `false`인 모델에서는 무시됨

지원 여부는 모델마다 다릅니다. GET /models?type=image를 확인하세요:

model_spec.supportsStyleReferences는 이 필드를 허용하는 모델에서만 true입니다.
model_spec.constraints.maxStyleReferences는 모델이 허용하는 항목 수입니다.
model_spec.constraints.supportsStyleReferenceStrength는 strength가 실제로 효과가 있는지 알려줍니다.

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.supportsStyleReferences == true) | "\(.id) max=\(.model_spec.constraints.maxStyleReferences)"'

지원하지 않는 모델에 style_references를 보내면 400이 반환되며, 모델의 최대 개수를 초과하거나 손상되었거나 접근할 수 없거나 크기가 너무 큰 참조를 보낸 경우에도 마찬가지입니다. 일부 모델은 기본 이미지 가격에 더해 반환된 이미지마다 스타일 참조 요금을 부과합니다. 예를 들어 Krea v2 Large와 Krea v2 Medium이 해당됩니다. 이 요금은 실제로 반환된 이미지에 대해서만 청구됩니다. 이미지당 기본 가격은 이미지 모델을 참고하세요.

부분 variant 결과

variants가 1보다 크면, 일부 variant는 공급자의 콘텐츠 정책에 의해 거부되고 나머지는 성공할 수 있습니다. 이 경우 endpoint는 여전히 200을 반환하지만, 요청한 것보다 적은 수의 이미지가 포함됩니다:

하나 이상의 variant가 누락되면, JSON 본문에 누락된 variant 수인 content_policy_violation_count가 포함됩니다.
x-venice-content-violation-count 응답 헤더에도 같은 수가 담깁니다.
x-venice-is-content-violation과 x-venice-is-blurred는 반환된 이미지에 대한 정보를 나타냅니다.

요청한 모든 variant가 거부되면 이미지가 반환되지 않고, 대신 요청이 422로 실패합니다. len(images) == variants라고 가정하지 마세요. 배열 길이를 variants와 비교하고, content_policy_violation_count가 있다면 함께 확인하세요.

OpenAI 호환 endpoint

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

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

size는 픽셀 크기 모델, 즉 GET /models?type=image의 model_spec.constraints에서 widthHeightDivisor가 1보다 큰 모델에만 적용됩니다. qwen-image-2를 포함한 대부분의 모델은 대신 종횡비와 해상도로 출력 크기를 정하며 size를 무시합니다. 일부 OpenAI 파라미터는 SDK 호환성을 위해 허용되지만 무시됩니다(n은 1로 제한됨):

Parameter	Behavior on `/images/generations`
`quality`	허용되지만 무시됨. 과금은 모델의 기본 quality 등급 기준
`style`	허용되지만 무시됨
`output_compression`	허용되지만 무시됨
`user`	허용되지만 버려지며, `anon_user_id`의 별칭이 아님
`n`	`1`만 지원되며, 다른 값은 유효성 검사에서 거부됨

이 라우트에는 등급 제어 기능이 없습니다. resolution이나 aspect_ratio 필드가 없으며, quality로 요금을 올리거나 낮출 수 없습니다. 등급이 있는 GPT Image 모델에서 quality, resolution, aspect_ratio를 선택해야 한다면 네이티브 /image/generate endpoint를 사용하세요. 빠른 마이그레이션에는 OpenAI 호환 라우트를 사용하세요. cfg_scale, style_preset, style_references, 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_mode: true`와 마찬가지로 성인 콘텐츠를 블러 처리합니다
`low`	`safe_mode: false`와 마찬가지로 블러 처리되지 않은 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에서만 동작합니다. 투명도에도 같은 구분이 적용됩니다. /image/generate는 transparent_background: true를 사용하고, /images/generations는 OpenAI 스타일의 background: "transparent"를 사용합니다. 둘 다 png 또는 webp 출력 포맷과 supportsTransparentBackground: true인 모델이 필요합니다. 투명 배경 이미지를 참조하세요.

Prompt 작성 팁

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

에러

Status	Meaning	Action
`400`	잘못된 요청 파라미터	필드 이름, 타입, 모델별 제약 확인
`401`	인증 실패 또는 모델이 더 높은 접근 등급 요구	API 키와 모델 접근 권한 확인
`402`	잔액 부족	venice.ai/settings/api에서 크레딧 추가
`404`	알 수 없는 모델	`GET /models?type=image`에서 모델 ID 확인
`415`	잘못된 content type	`Content-Type: application/json`으로 JSON 전송
`422`	콘텐츠 정책 위반	공급자가 prompt 또는 이미지를 명시적으로 거부함. prompt를 수정하거나 모델 변경. 본문에는 `error`와 boolean 값 `retryable`이 포함되며, `suggested_prompt`와 `recommended_model`이 포함될 수도 있음
`429`	Rate limit 초과 또는 모델 과부하	백오프와 함께 재시도, `Retry-After` 헤더 확인
`500`	추론 처리 실패	요청 재시도
`503`	모델 용량 초과	잠시 후 재시도

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

사용 가능한 모델

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

문서

시작하기

텍스트 및 채팅

이미지

비디오

오디오

검색 및 RAG

에이전트 및 통합

코딩 도구

에이전트 도구

SDK 및 프레임워크

이미지 생성

Endpoint

1단계: 생성 요청 보내기

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

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

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

요청 파라미터

모델별 옵션

고해상도 생성

LoRA 강도

성인 콘텐츠 및 safe mode

스타일 프리셋

스타일 참조

부분 variant 결과

OpenAI 호환 endpoint

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

Prompt 작성 팁

에러

사용 가능한 모델

​Endpoint

​1단계: 생성 요청 보내기

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

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

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

​요청 파라미터

​모델별 옵션

​고해상도 생성

​LoRA 강도

​성인 콘텐츠 및 safe mode

​스타일 프리셋

​스타일 참조

​부분 variant 결과

​OpenAI 호환 endpoint

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

​Prompt 작성 팁

​에러

​사용 가능한 모델

Endpoint

1단계: 생성 요청 보내기

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

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

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

요청 파라미터

모델별 옵션

고해상도 생성

LoRA 강도

성인 콘텐츠 및 safe mode

스타일 프리셋

스타일 참조

부분 variant 결과

OpenAI 호환 endpoint

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

Prompt 작성 팁

에러

사용 가능한 모델