> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-mintlify-86b9f77a.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 이미지 생성 > Venice 네이티브 이미지 API 또는 OpenAI 호환 images 엔드포인트를 사용해 텍스트 프롬프트로 이미지를 생성하고, 스타일 제어와 바이너리(binary)·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={null} 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={null} 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={null} 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={null} { "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={null} { "id": "generate-image-1234567890", "images": [ "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..." ], "timing": { "inferenceDuration": 1840, "inferencePreprocessingTime": 22, "inferenceQueueTime": 31, "total": 1893 } } ``` `images` 배열에는 base64로 인코딩된 이미지 데이터가 들어 있습니다. 첫 항목을 디코딩해 저장하거나 표시하세요. `timing.total`은 전체 요청 소요 시간(밀리초)입니다. ## 2단계: 이미지 디코딩 및 저장 ```python Python theme={null} 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={null} 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={null} 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={null} curl https://api.venice.ai/api/v1/image/styles \ -H "Authorization: Bearer $VENICE_API_KEY" ``` **응답(200):** ```json theme={null} [ "3D Model", "Analog Film", "Anime", "Cinematic", "Digital Art" ] ``` 그런 다음 그 값 중 하나를 생성 요청에 전달하세요: ```json theme={null} { "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={null} { "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={null} { "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={null} { "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)에서 확인하세요. ### 성인 콘텐츠 및 safe mode `safe_mode`는 생성 output의 성인 콘텐츠를 블러 처리할지 여부를 제어합니다. 기본값은 `true`입니다. 사용 사례에서 성인 콘텐츠가 허용되고 원본 output을 원한다면 `false`로 설정하세요: ```json theme={null} { "model": "lustify-v8", "prompt": "…", "safe_mode": false } ``` 일부 이미지 모델은 성인 / 무검열 생성을 위해 특별히 설계되어 `safe_mode: false`와 잘 어울립니다. 가격 페이지의 예시로는 `lustify-sdxl`, `lustify-v7`, `lustify-v8`이 있습니다. 현재 목록과 모델별 비용은 [이미지 모델](/models/image)과 [가격](/overview/pricing)을 참고하세요. 기존 이미지 편집의 경우, 기본 편집 모델 `qwen-edit`는 노골적인 성적 이미지를 차단합니다. 무검열 편집이 필요하다면 [이미지 편집](/guides/media/image-editing)을 통해 `qwen-edit-uncensored`를 사용하세요. `safe_mode`가 활성화되어 있고 모델이 블러 처리되거나 조정된 output을 반환할 때, 프로그래밍 방식으로 이를 감지해야 한다면 `x-venice-is-blurred`와 `x-venice-is-content-violation` 응답 헤더를 확인하세요. ### 스타일 프리셋 선택한 모델이 지원한다면 `style_preset`을 사용해 전체 prompt를 다시 쓰지 않고도 출력을 유도할 수 있습니다. 유효한 프리셋 이름은 [Image Styles](/api-reference/endpoint/image/styles)에서 가져올 수 있습니다: ```json theme={null} { "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={null} { "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을 반환합니다 | ```json theme={null} { "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](https://venice.ai/settings/api?utm_source=venice-api-documentation)에서 크레딧 추가 | | `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)을 참고하세요.