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는 더 이상 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 \
  -H "Authorization: Bearer $VENICE_API_KEY"

응답(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`일 때만
`return_binary`	boolean	아니오	`false`	base64 JSON 대신 raw 이미지 바이트 반환
`safe_mode`	boolean	아니오	`true`	활성화 시 성인 콘텐츠 블러 처리
`seed`	integer	아니오	무작위	더 일관된 반복을 위해 동일 seed 재사용
`cfg_scale`	number	아니오	모델별	값이 높을수록 모델이 prompt를 더 충실히 따름
`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"
}

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

성인 콘텐츠 및 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 작성 팁

피사체로 시작한 다음 매체, 조명, 구도, 분위기를 더하세요.
메인 prompt에 과부하를 주지 말고 피해야 할 세부 사항은 negative_prompt에 넣으세요.
반복 시 seed를 재사용해 구도를 완전히 바꾸지 않고 prompt 변화의 비교가 가능하게 하세요.
크기는 모델을 의식해서 설정하세요. 어떤 모델은 width/height를, 어떤 모델은 aspect_ratio를, 해상도 등급 모델은 aspect_ratio와 resolution을 함께 사용합니다.
탐색 단계에서는 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 같은 응답 헤더를 확인하세요.

사용 가능한 모델

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

문서

시작하기

텍스트 및 채팅

이미지

비디오

오디오

검색 및 RAG

에이전트 및 통합

코딩 도구

에이전트 도구

SDK 및 프레임워크

이미지 생성

Endpoint

1단계: 생성 요청 보내기

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

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

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

요청 파라미터

모델별 옵션

고해상도 생성

성인 콘텐츠 및 safe mode

스타일 프리셋

OpenAI 호환 endpoint

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

Prompt 작성 팁

에러

사용 가능한 모델

​Endpoint

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

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

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

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

​요청 파라미터

​모델별 옵션

​고해상도 생성

​성인 콘텐츠 및 safe mode

​스타일 프리셋

​OpenAI 호환 endpoint

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

​Prompt 작성 팁

​에러

​사용 가능한 모델

Endpoint

1단계: 생성 요청 보내기

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

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

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

요청 파라미터

모델별 옵션

고해상도 생성

성인 콘텐츠 및 safe mode

스타일 프리셋

OpenAI 호환 endpoint

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

Prompt 작성 팁

에러

사용 가능한 모델