Prompt Enhancement

Prompt enhancement는 이미지 생성 또는 편집 전에 prompt를 다시 작성해 명확한 시각적 세부 정보를 추가하며, 짧거나 빈약한 설명을 이미지 모델이 더 안정적으로 따르는 풍부한 prompt로 바꿔줍니다. POST /image/generate, POST /image/edit, 또는 POST /image/multi-edit에서 enhance_prompt: true로 설정하여 활성화할 수 있습니다. 이미지 생성의 경우, 이는 Venice 웹 앱의 “매직 완드”를 구동하는 것과 동일한 향상입니다. 이미지 편집의 경우, 비전 인식 enhancer가 입력 이미지 하나 또는 여러 개를 사용해 편집 지시를 명확히 합니다.

언제 사용하나요

Prompt enhancement는 다음과 같은 경우에 가장 유용합니다:

prompt가 짧고(몇 단어 또는 한 문구) 모델이 구도, 조명, 분위기를 채워주기를 원할 때.
최종 사용자가 캐주얼한 prompt를 입력하고 확장을 통해 이점을 얻을 수 있는 제품을 구축할 때.
이미지를 편집 중이며 그 안에 보이는 콘텐츠를 인식한 상태로 지시가 다시 작성되기를 원할 때.
긴 prompt를 직접 작성하지 않고도 더 일관되고 상세한 출력을 원할 때.

이미 길고 세심하게 다듬은 prompt를 보내고 있다면 enhancement를 꺼두는 편이 보통 더 나은 제어권을 줍니다.

1단계: enhancement가 활성화된 요청 보내기

표준 이미지 생성 요청에 enhance_prompt: true를 추가하세요.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "format": "webp"
  }'

Venice는 "a cabin in the woods"를 더 상세한 prompt로 다시 작성한 뒤, 다시 작성된 텍스트를 생성에 사용합니다. 요청의 나머지 부분은 일반 생성 호출과 정확히 동일하게 동작합니다.

Enhancement는 별도의 모델 호출로 재작성이 생성되기 때문에 생성이 시작되기 전에 최대 ~30초가 추가됩니다. 클라이언트 타임아웃에서 이를 고려하세요.

2단계: 응답 헤더에서 향상된 prompt 읽기

재작성이 적용되면, Venice는 최종 prompt를 x-venice-enhanced-prompt 응답 헤더에 URL 인코딩된 형태로 반환합니다. 이를 디코딩하면 이미지 모델에 실제로 전달된 내용을 확인하거나 로그로 남기거나 표시할 수 있습니다.

import base64
import os
from urllib.parse import unquote

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 cabin in the woods",
        "enhance_prompt": True,
        "format": "webp",
    },
)

data = response.json()

enhanced = response.headers.get("x-venice-enhanced-prompt")
if enhanced:
    print("Enhanced prompt:", unquote(enhanced))
else:
    print("No enhancement was applied; original prompt was used.")

image_bytes = base64.b64decode(data["images"][0])
with open("output.webp", "wb") as f:
    f.write(image_bytes)

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 cabin in the woods",
    enhance_prompt: true,
    format: "webp",
  }),
});

const data = await response.json();

const enhanced = response.headers.get("x-venice-enhanced-prompt");
if (enhanced) {
  console.log("Enhanced prompt:", decodeURIComponent(enhanced));
} else {
  console.log("No enhancement was applied; original prompt was used.");
}

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

x-venice-enhanced-prompt 헤더는 재작성이 실제로 생성되어 적용된 경우에만 존재합니다. Enhancement가 건너뛰어지거나 실패하면 헤더가 없으며 원본 prompt가 사용됩니다.

이미지 편집에 enhancement 사용하기

편집 endpoint는 입력 이미지 하나 또는 여러 개를 분석한 뒤 지시를 다시 작성하는 비전 인식 enhancer를 사용합니다. 이 덕분에 "make it winter" 같은 짧은 요청을 관련 피사체와 구도를 보존하면서 더 구체적인 편집으로 바꿀 수 있습니다. 단일 이미지 편집의 경우, JSON 또는 multipart 요청 어디에서든 enhance_prompt를 포함하세요:

curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "image": "https://example.com/cabin.jpg",
    "prompt": "make it winter",
    "enhance_prompt": true
  }'

Multi-edit의 경우, images 배열과 함께 같은 파라미터를 사용하세요:

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "images": [
      "https://example.com/cabin.jpg",
      "https://example.com/snow-reference.jpg"
    ],
    "prompt": "make the first image match this winter atmosphere",
    "enhance_prompt": true
  }'

두 편집 endpoint 모두 편집된 이미지를 바이너리 데이터로 반환합니다. 생성과 마찬가지로, x-venice-enhanced-prompt를 확인하고 URL 디코딩해 적용된 재작성을 볼 수 있습니다.

동작 방식

Aspect	Behavior
지원 endpoint	`POST /image/generate`, `POST /image/edit`, `POST /image/multi-edit`
기본값	`enhance_prompt`의 기본값은 `false`이며, 명시적으로 활성화하지 않으면 enhancement가 일어나지 않습니다.
Fail-open	재작성이 어떤 이유로든 실패하면 원본 prompt로 생성 또는 편집이 계속됩니다. Enhancement 때문에 요청이 오류로 종료되지 않습니다.
이미지 인식 편집	편집 요청 시, enhancer는 지시를 다시 작성할 때 제공된 이미지 하나 또는 여러 개를 분석합니다.
문자 제한	생성의 경우, 향상된 prompt는 선택한 모델의 `promptCharacterLimit`으로 잘립니다(Models API 참조).
안전 모드	생성 요청 시 enhancement 중에도 `safe_mode`가 준수됩니다. `safe_mode: true`이면 재작성은 SFW로 유지됩니다.
응답 헤더	적용될 경우, 최종 prompt는 `x-venice-enhanced-prompt`에 URL 인코딩되어 반환됩니다.

가격

Prompt enhancement는 일반 이미지 생성 비용에 더해 적용된 재작성당 $0.04의 정액 추가 요금으로 부과됩니다. 과금 규칙:

재작성이 실제로 생성되어 적용된 경우에만 요금이 부과됩니다. Enhancement가 건너뛰어지거나 fail open으로 원본 prompt를 사용하면 추가 요금이 없습니다.
추가 요금은 이미지 성공 경로에서 부과됩니다. 생성이 콘텐츠 위반으로 종료되면 enhancement 요금은 부과되지 않습니다.
variants로 여러 이미지를 요청할 때, 공유되는 재작성은 요청당 최대 한 번만 부과되며 variant 하나당 부과되지 않습니다.

이미지 생성 기본 비용은 가격 정책을 참조하세요.

variants와 함께 enhancement 사용하기

Enhancement는 아이디어를 탐색할 때 variants와 잘 어울립니다: 재작성이 한 번 생성된 뒤 모든 variant에 재사용되므로, $0.04 추가 요금을 한 번만 지불합니다.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "variants": 4
  }'

variants는 return_binary가 false일 때만 지원됩니다. 자세한 내용은 이미지 생성을 참조하세요.

Prompt 작성 팁

입력 prompt는 피사체와 절대 양보할 수 없는 세부 사항에 집중하세요. Enhancement는 그 주변의 스타일, 조명, 구도를 채워줍니다.
개발 중에는 x-venice-enhanced-prompt 헤더를 로그로 남겨 enhancement가 무엇을 추가하는지 학습하고, 언제 prompt를 직접 작성하는 것이 더 나을지 결정하세요.
배치 전체에서 재현 가능한 생성 결과를 얻으려면 enhancement로 한 번 생성한 뒤 헤더에서 향상된 prompt를 캡처하고, enhance_prompt를 꺼둔 채 그 정확한 텍스트를 재사용하세요.
이미지 생성의 경우, 캡처한 prompt를 고정된 seed와 결합하면 재작성 없이 다른 파라미터 변경을 비교할 수 있습니다.

오류

Enhancement 자체는 fail open되며 자체 오류 코드를 노출하지 않습니다. 표준 이미지 생성 오류가 그대로 적용됩니다.

Status	Meaning	Action
`400`	잘못된 요청 파라미터	필드 이름, 타입, 모델별 제약 조건 확인
`401`	인증 실패 또는 모델이 더 높은 액세스 등급 필요	API 키 및 모델 액세스 확인
`402`	잔액 부족	venice.ai/settings/api에서 크레딧 추가
`429`	Rate limit 초과 또는 모델 과부하	백오프와 함께 재시도, `Retry-After` 헤더 확인
`500`	추론 처리 실패	요청 재시도
`503`	모델 용량 초과	잠시 후 재시도

자세한 내용은 전체 오류 코드 레퍼런스를 참조하세요.

문서

시작하기

텍스트 및 채팅

이미지, 비디오 및 오디오

에이전트 및 통합

코딩 도구

에이전트 도구

SDK 및 프레임워크

언제 사용하나요

1단계: enhancement가 활성화된 요청 보내기

2단계: 응답 헤더에서 향상된 prompt 읽기

이미지 편집에 enhancement 사용하기

동작 방식

가격

variants와 함께 enhancement 사용하기

Prompt 작성 팁

오류

관련 문서

​언제 사용하나요

​1단계: enhancement가 활성화된 요청 보내기

​2단계: 응답 헤더에서 향상된 prompt 읽기

​이미지 편집에 enhancement 사용하기

​동작 방식

​가격

​variants와 함께 enhancement 사용하기

​Prompt 작성 팁

​오류

​관련 문서

언제 사용하나요

1단계: enhancement가 활성화된 요청 보내기

2단계: 응답 헤더에서 향상된 prompt 읽기

이미지 편집에 enhancement 사용하기

동작 방식

가격

variants와 함께 enhancement 사용하기

Prompt 작성 팁

오류

관련 문서