> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # 이미지 생성 > 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` 값을 노출합니다. **픽셀 기반 크기 예시:** ```bash theme={"system"} 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" } ``` **종횡비 크기 예시:** ```bash theme={"system"} 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" } ``` **해상도 등급 크기 예시:** ```bash theme={"system"} 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" } ``` 다른 해상도 등급 모델에도 같은 패턴이 적용됩니다: ```json theme={"system"} { "model": "nano-banana-pro", "prompt": "A serene canal in Venice at sunset", "aspect_ratio": "16:9", "resolution": "2K" } ``` 각 모델이 어떤 크기 필드를 받는지는 [이미지 모델](/models/image) 또는 [Models API](/api-reference/endpoint/models/list)에서 확인하세요. **응답(200):** ```json theme={"system"} { "id": "generate-image-1234567890", "images": [ "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..." ], "timing": { "inferenceDuration": 1840, "inferencePreprocessingTime": 22, "inferenceQueueTime": 31, "total": 1893 } } ``` `images` 배열에는 base64로 인코딩된 이미지 데이터가 들어 있습니다. 첫 항목을 디코딩해 저장하거나 표시하세요. `timing.total`은 전체 요청 소요 시간(밀리초)입니다. ## 2단계: 이미지 디코딩 및 저장 ```python Python theme={"system"} 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']}") ``` ```javascript Node.js theme={"system"} 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 디코딩 없이 이미지를 바로 스트리밍하거나 저장하고 싶을 때 유용합니다. ```bash theme={"system"} 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`에서 사용 가능한 스타일을 가져오세요: ```bash theme={"system"} curl https://api.venice.ai/api/v1/image/styles \ -H "Authorization: Bearer $VENICE_API_KEY" ``` **응답(200):** ```json theme={"system"} [ "3D Model", "Analog Film", "Anime", "Cinematic", "Digital Art" ] ``` 그런 다음 그 값 중 하나를 생성 요청에 전달하세요: ```json theme={"system"} { "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](/api-reference/endpoint/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/image)과 [Models API](/api-reference/endpoint/models/list)를 확인하세요. *** ## 모델별 옵션 ### 고해상도 생성 일부 이미지 모델은 선택 가능한 `resolution` 등급 없이 `aspect_ratio`를 지원합니다. 예를 들어 `qwen-image-2`는 종횡비를 받아 모델별 출력 크기에 매핑합니다: ```json theme={"system"} { "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`를 지원합니다: ```json theme={"system"} { "model": "gpt-image-2", "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting", "aspect_ratio": "16:9", "resolution": "4K" } ``` ```json theme={"system"} { "model": "nano-banana-2", "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting", "aspect_ratio": "16:9", "resolution": "2K" } ``` 어떤 모델이 더 높은 해상도를 지원하는지, 그리고 가격은 어떻게 되는지는 [이미지 모델](/models/image)에서 확인하세요. ### 스타일 프리셋 선택한 모델이 지원한다면 `style_preset`을 사용해 전체 prompt를 다시 쓰지 않고도 출력을 유도할 수 있습니다. 유효한 프리셋 이름은 [Image Styles](/api-reference/endpoint/image/styles)에서 가져올 수 있습니다: ```json theme={"system"} { "model": "qwen-image-2", "prompt": "A futuristic Venice skyline at sunrise", "style_preset": "3D Model" } ``` 현재 스타일 목록은 [Image Styles](/api-reference/endpoint/image/styles)를 참고하세요. *** ## OpenAI 호환 endpoint OpenAI 이미지 SDK나 기존 DALL-E 통합을 이미 사용하고 있다면, Venice는 `POST /images/generations`도 지원합니다. 더 단순한 요청 포맷을 제공하지만, Venice 네이티브 endpoint보다 기능이 적습니다. **요청:** ```json theme={"system"} { "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](https://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` 같은 응답 헤더를 확인하세요. *** ## 사용 가능한 모델 현재 모델 목록, 가격, 기능 지원은 [이미지 모델](/models/image)을 참고하세요.