이미지 생성

Venice 네이티브 이미지 API 또는 OpenAI 호환 images 엔드포인트로 텍스트 프롬프트에서 이미지를 생성하고, 스타일 제어와 바이너리 또는 base64 출력을 활용하세요.

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

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):

[
  "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를 더 충실히 따름
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"
}

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

​

스타일 프리셋

선택한 모델이 지원한다면 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를 사용하세요.

---

​

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 같은 응답 헤더를 확인하세요.

---

​

사용 가능한 모델

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