venice-image-generate

Venice 画像生成

テキストから画像を生成するエンドポイントが 2 つあります。

1. POST /api/v1/image/generate — Venice ネイティブで、細かな制御が可能です（ネガティブプロンプト、CFG、シード、スタイルプリセット／参照、品質、最大 4 種類のバリエーション）。
2. POST /api/v1/images/generations — OpenAI 互換です。設定項目は少ないものの、OpenAI SDK にそのまま組み込めます。

そのほか、以下も利用できます。

• GET /api/v1/image/styles — style_preset のスタイルプリセット名の一覧です。認証は不要です。

編集／アップスケーリング／複数画像／背景除去については、venice-image-edit を参照してください。

使用する場面

• テキストプロンプトから画像を生成したい場合。
• 1 回の呼び出しで複数のバリエーションを生成したい場合。
• OpenAI の images.generate から移行し、SDK を変更せずに切り替えたい場合。
• スタイルプリセットを事前に確認してから選びたい場合。
• 生成する画像を既存の画像の雰囲気に合わせたい場合（style_references）。

/image/generate — Venice ネイティブ

リクエスト

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A beautiful sunset over a mountain range",
    "width": 1024,
    "height": 1024,
    "cfg_scale": 7.5,
    "seed": 123456789,
    "variants": 1,
    "format": "webp",
    "style_preset": "3D Model",
    "safe_mode": true
  }'

リクエストスキーマは厳密です。不明なフィールドは 400 エラーで拒否されます。

フィールド

フィールド	型	デフォルト	備考
model	string	—	必須。 GET /models?type=image で取得できる画像モデル ID です。不明な ID を指定すると候補を示す 404 が返ります。廃止済みの ID を指定すると、置き換え先がある場合はその ID を示す 404 が返ります。
prompt	string	—	必須。 空白のみの値は指定できません。モデルの constraints.promptCharacterLimit 以下（現在は 1,500～32,768 文字）で指定します。
negative_prompt	string	—	表示しない内容を指定します。文字数上限は prompt と同じです。現在は一部のモデル（例：venice-sd35、lustify-*、wai-Illustrious、qwen-image-2、qwen-image-2-pro、qwen-image-3、qwen-image-3-pro、wan-2-7-*）のみで使用されます。それ以外のモデルでは、z-image-turbo や chroma を含め、警告なく無視されます。
width, height	int	1024, 1024	それぞれ 1280 以下です。ピクセルサイズを使うモデル（constraints.aspectRatios がないモデル）のみで使用されます。アスペクト比を使うモデルでは無視されます。また、qwen-image、qwen-image-3、qwen-image-3-pro はこれらを指定すると 400 を返すため、aspect_ratio を使用してください。
aspect_ratio	string	モデルのデフォルト	例："1:1"、"16:9"、"4:3"。モデルの constraints.aspectRatios に含まれる値のみ指定してください。/image/generate はこのフィールドを検証しません。ほとんどのモデルは defaultAspectRatio にフォールバックしますが、一部のモデルはそのまま上流に渡すため失敗します。
resolution	string	モデルのデフォルト	"1K"、"2K"、"4K"。モデルの constraints.resolutions に含まれる値を指定してください（それ以外は 400）。resolutions がないモデルでは警告なく無視されます。
quality	"low"/"medium"/"high"	モデルのデフォルト	constraints.qualities があるモデル（GPT Image 2 / 2.5、Ideogram V4.5、Grok Imagine 2.0）のみで使用されます。このリストにない値を指定すると 400 が返り、それ以外のモデルでは無視されます。料金が変わります。pricing.quality を参照してください。
cfg_scale	number	モデルのデフォルト	0 < x ≤ 20。値を大きくすると、プロンプトへの準拠度が高まります。
steps	int	min(steps.max, 20)	steps を使用するモデル（現在は venice-sd35、lustify-*、wai-Illustrious）のみで使用されます。これらのモデルでは 1..constraints.steps.max の範囲で指定し、最大値を超えると 400 が返ります。z-image-turbo や chroma を含むその他すべてのモデルでは、任意の整数を受け付けますが無視されます。
seed	int	ランダム	-999999999..999999999。ランダムなシードを使う場合は省略してください（0 は「ランダム」ではなく、文字どおりのシードです）。一部のモデル（例：GPT Image、Muse、Luma、Recraft、ImagineArt、Seedream V5 Pro、Nano Banana Pro、Grok Imagine）では無視されます。
variants	int	1	1～4。return_binary: false の場合のみ使用できます。指定した seed が使われるのは最初の画像のみで、残りにはランダムなシードが使われます。各バリエーションは 1 枚の画像として課金され、レート制限の対象になります。
style_preset	string	—	GET /image/styles で取得できる値をそのまま指定します。それ以外の値では 400 が返ります。
style_references	array	—	美的表現の指針となる参照画像です。各項目は { "image": <raw base64、データ URI、または http(s) URL。8 MB 未満。SVG は不可>, "strength": 0.1–1（デフォルトは 0.5） } です。supportsStyleReferences: true のモデルのみで使用でき、項目数は constraints.maxStyleReferences 以下にする必要があります。それ以外のモデルでは 400 が返ります。constraints.supportsStyleReferenceStrength が false の場合、strength は無視されます。
lora_strength	int	—	0～100。LoRA を使用するモデルにのみ適用されます。
enhance_prompt	bool	false	生成前にプロンプトを書き換え、視覚的な詳細を追加します。書き換えが行われると最大約 30 秒かかり、$0.04 が課金されます（書き換えに失敗した場合は元のプロンプトが使われます）。最終的なプロンプトは、レスポンスヘッダー x-venice-enhanced-prompt で URL エンコードされた状態で返されます。
disable_prompt_optimization_thinking	bool	モデルのデフォルト	速度を優先し、モデルのプロンプト最適化の思考ステップをスキップします。supportsOptimizePromptThinking: true のモデル（例：seedream-v5-pro、qwen-image-3）のみで有効です。
enable_web_search	bool	false	supportsWebSearch: true のモデル（現在は nano-banana-2、nano-banana-pro）のみで使用できます。それ以外のモデルでは無視されます。仕様では検索に追加料金がかかる場合があるとされていますが、現在は検索の有無による画像あたりの料金差はありません。
format	"webp"/"png"/"jpeg"	webp	出力画像の形式です。
return_binary	bool	false	true の場合は画像の生バイト列、false の場合は base64 を含む JSON を返します。
embed_exif_metadata	bool	false	EXIF にプロンプト情報を埋め込みます。
hide_watermark	bool	false	Venice の定額料金モデル（z-image-turbo、venice-sd35、chroma、lustify-*、wai-Illustrious）でのみ意味があります。それ以外のモデルには、透かしは付きません。アダルトコンテンツと判定された画像、および非常に小さい画像にも透かしは付きません。
safe_mode	bool	true	アダルトコンテンツと判定された画像をぼかします。
anon_user_id	string	—	上流側でのアトリビューションに使用する、任意のエンドユーザー識別子です（印字可能な ASCII 文字、128 文字以下、|| を含まないもの）。
inpaint	—	—	削除済み（2025 年 5 月 19 日に無効化）。指定すると 400 が返ります。/image/edit を使用してください。

応答（JSON、return_binary: false）

{
  "id": "...",
  "images": ["<base64>", "<base64>"],
  "timing": { "inferenceDuration": 0, "inferencePreprocessingTime": 0, "inferenceQueueTime": 0, "total": 0 },
  "request": { "success": true, "data": { "...": "the parsed request with defaults filled in (style_references omitted)" } }
}

JSON を圧縮するには、Accept-Encoding: gzip, br を送信してください。

return_binary: true の場合、本文は画像の生データです。Content-Type はバイト列から検出されます（image/webp、image/png、または image/jpeg）。

応答ヘッダー

ヘッダー	意味
x-venice-is-content-violation	画像がブロックされた場合は "true" です。この呼び出しは引き続き 200 を返します。JSON 形式の画像は黒く塗りつぶされ、バイナリ形式では PNG のプレースホルダーが返されます。料金は発生しません。
x-venice-is-blurred	safe_mode によって出力がぼかされた場合は "true" です。
x-venice-enhanced-prompt	URL エンコードされた書き換え後のプロンプトです（enhance_prompt によって生成された場合のみ）。
x-venice-model-deprecation-warning、x-venice-model-deprecation-date、x-venice-deprecated、x-venice-deprecated-replacement	モデルの非推奨化が予定されている、またはすでに非推奨化されている場合に存在します。
x-ratelimit-{limit,remaining,reset}-*、x-venice-balance-usd、x-venice-balance-diem	レート制限と残高の状態です。画像の生成前に設定されます。
X-Balance-Remaining	x402 の呼び出し元向けに仕様書に記載されていますが、現在サーバーでは設定されていません。代わりに GET /x402/balance/{walletAddress} をポーリングしてください。

/images/generations — OpenAI 互換

すでに OpenAI SDK を利用している場合に使用してください。フィールド名は openai.images.generate() と一致します。

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})

const res = await client.images.generate({
  model: 'z-image-turbo',
  prompt: 'A beautiful sunset over mountain ranges',
  size: '1024x1024',
  response_format: 'b64_json',
})

const b64 = res.data[0].b64_json

マッピングされるフィールド

フィールド	値	備考
model	string	実際には必須です。省略するか "" を送信すると、仕様書ではデフォルトが "default" と記載されているにもかかわらず、400 "model is required" が返されます。不明な ID（例：dall-e-3）は、Venice のデフォルト画像モデル（z-image-turbo）にサイレントにフォールバックします。
prompt	string、1～1500 文字	必須です。モデルに関係なく、このエンドポイントでは上限が 1500 文字です。
size	auto（デフォルト → 1024×1024）、256x256、512x512、1024x1024、1536x1024、1024x1536、1792x1024、1024x1792	幅と高さにマッピングされるため、ピクセルサイズ指定のモデルにのみ影響します。アスペクト比モデルではデフォルトのアスペクト比が使用されます。
output_format	jpeg / png / webp	デフォルトは png です。
response_format	b64_json（デフォルト）/ url	url は data: URL（ホストされた URL ではありません）を返します。
moderation	auto（デフォルト、安全モード有効）/ low（安全モード無効）	—
n	1	1 回の呼び出しにつき画像は 1 枚のみです。
anon_user_id	string	/image/generate と同じです。
quality、style、background、output_compression、user	—	OpenAI との互換性のために受け付けられますが、無視されます。ただし、値は有効である必要があります（quality：auto/high/medium/low/hd/standard、style：vivid/natural、background：transparent/opaque/auto、output_compression：0～100）。user は推論に使用されず、anon_user_id の別名でもありませんが、値ごとにエラーバジェットを分割します（venice-errors を参照）。

応答：{ "created": <unix>, "data": [{ "b64_json": "..." }] }（または [{ "url": "data:image/png;base64,..." }]）。このエンドポイントの画像にはウォーターマークが入りません。不明なフィールドは 400 で拒否されます。

variants、seed、negative_prompt、cfg_scale、aspect_ratio、resolution、quality、style_preset、または style_references が必要な場合は、/image/generate に切り替えてください。

/image/styles — プリセットの一覧表示

curl https://api.venice.ai/api/v1/image/styles

API キーは不要です。文字列の一覧が返されます。

{ "object": "list", "data": ["3D Model", "Analog Film", "Anime", "Cinematic", "Comic Book", "..."] }

data[] の任意のエントリをそのまま style_preset として渡してください（大文字と小文字は区別されます）。キャッシュしてください。一覧が変更されることはほとんどありません。

モデルの選択

curl "https://api.venice.ai/api/v1/models?type=image"

各モデルの model_spec を確認してください。

• constraints.promptCharacterLimit — プロンプトの最大長です（negative_prompt にも適用されます）。
• constraints.aspectRatios[] + defaultAspectRatio — アスペクト比主導のモデルにあります。width／height の代わりに aspect_ratio を使用してください。
• constraints.resolutions[] + defaultResolution — モデルが resolution を受け付ける場合にあります。
• constraints.qualities[] + defaultQuality — モデルが quality を受け付ける場合にあります。
• constraints.steps.{default,max} — ステップ数の範囲です。すべてのモデルに記載されていますが、steps を使用するモデルは一部だけです（フィールドの表を参照）。
• constraints.widthHeightDivisor — ピクセルサイズを指定するモデルでは、width／height をこの値（8 または 16）の倍数にすると最適に動作します。API はこの値を検証しません。
• supportsStyleReferences、constraints.maxStyleReferences、constraints.supportsStyleReferenceStrength — スタイル参照のサポート状況です。
• supportsWebSearch、supportsOptimizePromptThinking — これらのリクエストフラグが機能するかどうかです。
• privacy（private／anonymized）と uncensored — プライバシーレベルとコンテンツに関する方針です。
• 料金：pricing.generation.usd（画像ごとの固定料金）、または解像度別料金モデルの pricing.resolutions[tier].usd に加え、品質別料金モデルの pricing.quality[tier][level].usd です。

代表的な ID（一覧は頻繁に変わるため、GET /models?type=image で確認してください）：

サイズ指定方式	例
width／height	z-image-turbo（デフォルトモデル）、venice-sd35、chroma、lustify-v8
aspect_ratio のみ	flux-2-pro、seedream-v5-lite、muse-image、qwen-image-2、krea-v2-large
aspect_ratio + resolution	nano-banana-2、nano-banana-pro、seedream-v5-pro、qwen-image-3
aspect_ratio + resolution + quality	gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst、ideogram-v4-5（1K／2K）、grok-imagine-image-2-0（low／medium のみ）

bria-bg-remover も type=image に含まれていますが、これは背景除去モデルです。/image/generate ではなく、/image/background-remove から使用してください。

共通パターン

固定シードによる再現性

{"model": "z-image-turbo", "prompt": "...", "seed": 42}

seed を尊重するモデル（例：z-image-turbo、seedream-v4、nano-banana-2）では、同じモデル、プロンプト、シード、設定を使用すると同じ画像を再現できるはずですが、サードパーティ製モデルではビット単位で完全に一致する出力は保証されません。variants > 1 の場合、seed が使われるのは最初の画像のみで、残りはランダムになります。各画像の再現性が必要な場合は、シードを変えて個別に呼び出してください。

アスペクト比 + 解像度を指定するモデル（Nano Banana、Seedream V5 Pro）

{"model": "nano-banana-2", "prompt": "...", "aspect_ratio": "16:9", "resolution": "2K"}

{"model": "seedream-v5-pro", "prompt": "...", "aspect_ratio": "4:3", "resolution": "2K"}

品質ティア（GPT Image 2／2.5、Ideogram V4.5）

{"model": "gpt-image-2-5-flare", "prompt": "...", "aspect_ratio": "3:2", "resolution": "2K", "quality": "medium"}

quality を省略すると、defaultQuality が使われます（GPT Image と Ideogram V4.5 の各モデルでは high です）。料金は解像度と品質の両方によって変わります。

スタイルプリセット + ネガティブプロンプト

negative_prompt を尊重するモデルを使用してください（フィールドの表を参照）。z-image-turbo はこれを無視して破棄します。

{
  "model": "venice-sd35",
  "prompt": "a red sports car in a parking lot",
  "negative_prompt": "blurry, people, clouds",
  "style_preset": "3D Model"
}

スタイル参照（既存画像の見た目に合わせる）

{
  "model": "krea-v2-large",
  "prompt": "a lighthouse on a rocky coast at dusk",
  "style_references": [
    { "image": "https://example.com/ref-1.png", "strength": 0.8 },
    { "image": "data:image/png;base64,....", "strength": 0.4 }
  ]
}

プロンプトでは被写体を説明し、参照画像にはスタイルを担わせてください。現在、対応しているモデルは krea-v2-large／krea-v2-medium（参照画像は最大3点、強度を反映）と luma-uni-1／luma-uni-1-max（参照画像は最大3点、強度は無視）です。4つとも anonymized モデルです。GET /models?type=image で supportsStyleReferences を再確認してください。Krea V2 の各モデルでは参照画像を使用すると、リクエストごとに少額の追加料金が発生します。この料金は /models の料金情報には個別に記載されていません。

バイナリデータをディスクにストリーム出力する（Node）

const res = 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: 'z-image-turbo', prompt: '...', return_binary: true }),
})
if (!res.ok) throw new Error(await res.text())
if (res.headers.get('x-venice-is-content-violation') === 'true') throw new Error('Content violation')
const ext = (res.headers.get('content-type') ?? 'image/webp').split('/')[1]
const buf = Buffer.from(await res.arrayBuffer())
await fs.writeFile(`out.${ext}`, buf)

エラー

コード	意味
400	パラメーターが不正です。model が指定されていない、スキーマ違反、不明なフィールド、プロンプトが長すぎる、steps が上限を超えている（steps を使用するモデルの場合）、style_preset が無効、モデルでサポートされていない resolution／quality、qwen-image／qwen-image-3／qwen-image-3-pro に width／height を送信している、return_binary: true と variants を併用している、サポート対象外のモデルまたは上限を超える style_references、参照画像に到達できない、または参照画像が破損している場合です。
401	認証に失敗しました。
402	認証情報がまったくない（x402 の支払い要件を示す本文と PAYMENT-REQUIRED ヘッダー）、残高不足（Bearer の場合は "Insufficient USD or Diem balance…"、x402 ウォレットの場合は PAYMENT_REQUIRED の本文とヘッダー）、または API キーの USD／DIEM 利用上限に達した場合です。
403	API キーの modelPrivacy 設定によりこのモデルがブロックされている（例：PRIVATE_ONLY キーで anonymized モデルを呼び出している）、またはモデルが利用地域で提供されていないか、アカウントで制限されている場合です。
404	モデルが見つからないか、提供終了しています（代替モデルがある場合は、メッセージにその名前が示されます）。/images/generations では、不明な ID は代わりにデフォルトモデルにフォールバックします。
422	参照画像のピクセル数が大きすぎます（7680×4320 を超過）。
429	レート制限に達したか、上流プロバイダーが過負荷状態です（Retry-After が設定されます）。
500	推論に失敗しました。
503	モデルが処理能力の上限に達しているか、オフラインです。ジッターを加えて再試行してください。

これらのエンドポイントでは、コンテンツポリシー違反はエラーではありません。x-venice-is-content-violation: true を含む 200 が返され、画像はブロックされ、課金されません。本文の形式と再試行方法については、venice-errors を参照してください。

注意点

• 各モデルは、width／height または aspect_ratio（＋ resolution）のいずれか一方のサイズ指定方式を使用します。まず constraints を確認してください。アスペクト比を使用するモデルに width／height を送信しても、通常は無視されます。ただし、qwen-image、qwen-image-3、qwen-image-3-pro では 400 エラーになります。
• /image/generate では aspect_ratio は検証されないため、モデルに記載されていない値を指定しても、通常はエラーにならずデフォルト値にフォールバックします。モデルに記載されていない resolution または quality を指定すると 400 になります。
• variants > 1 を指定するには、return_binary: false が必要です。
• Grok Imagine モデルは、ぼかし処理が行われない場合、プロバイダーのバイト列を変更せずに返すため、出力形式が format と一致しないことがあり、EXIF も埋め込まれません。Content-Type を信頼するか、バイト列を判別してください。
• 必ず x-venice-is-content-violation を確認してください。ブロックされた画像でも 200 が返されます。
• supportsStyleReferences: true に対応していないモデルで style_references を指定すると、何も起きないのではなく 400 になります。
• enhance_prompt は書き換えが行われるたびに $0.04 が課金されます。コストやレイテンシーを重視する呼び出しでは無効にしてください。
• OpenAI 互換の場合、response_format: "url" が返すのはホストされた URL ではなくデータ URLです。ストレージに保存する場合は、その点を考慮してください。