venice-image-edit

Venice 画像編集

すべて既存の画像を処理する4つのエンドポイントです。

エンドポイント	用途
POST /image/edit	テキストプロンプトを使って1枚の画像を変換します。JSON または multipart/form-data に対応しています。
POST /image/multi-edit	1つのプロンプトを使って複数の画像を合成／レイヤー化します。JSON または multipart/form-data に対応しています。
POST /image/upscale	2～4倍にアップスケールします。JSON または multipart/form-data に対応しています。
POST /image/background-remove	背景を透過した PNG の切り抜きを生成します。JSON または multipart/form-data に対応しています。

テキストから画像を生成する場合は、venice-image-generate を参照してください。

共通ルール

	/image/edit	/image/multi-edit	/image/upscale	/image/background-remove
JSON 入力	image：生の base64、data URI、または http(s):// URL	images[]：生の base64、data URI、または http(s):// URL	image：生の base64 のみ	image（base64／data URI）または image_url
Multipart 入力	image に1つのファイル	繰り返しの images パートにファイル	image に1つのファイル	image に1つのファイル
最小サイズ	合計で 65,536 px 以上、かつ各辺が 64 px 以上	同左	同左	Venice ではチェックされません
最大サイズ	33,177,600 px（7680×4320）以下	同左	出力が 16,777,216 px（4096×4096）以下	Venice ではチェックされません
レスポンス	編集後の画像データ（PNG/JPEG/WebP）	編集後の画像データ	image/png	アルファチャンネル付きの image/png
モデル	model（デフォルトは firered-image-edit）	modelId（デフォルトは firered-image-edit）	固定：upscaler	固定：bria-bg-remover

• 受け付ける入力形式：JPEG、PNG、WebP、HEIF/HEIC、AVIF。SVG は拒否されます。背景削除では形式の事前検証を行わず、画像をそのままモデルに渡します。
• ファイルサイズは 25 MB 未満である必要があります（25 MB を超える multipart ファイルは 413 を返します）。編集と複数画像編集で取得する URL も、25 MB が上限です。35 MB を超える JSON ボディ（たとえば大きな base64 画像）は 413 を返します。
• URL はサーバー側で取得され、一般公開されている必要があります。プライベート、内部、メタデータの各ホストはブロックされます（400）。
• 4つのエンドポイントすべてが画像をバイナリで返し、JSON は返しません。return_binary フィールドはありません（このフラグは /image/generate にのみ存在します）。
• 編集、複数画像編集、背景削除の JSON ボディは厳密です。不明なフィールドがあると 400 を返します。/image/upscale は不明なフィールドを無視します。
• 編集、複数画像編集、背景削除では、上流でのエンドユーザー属性付与に任意の anon_user_id（印字可能な ASCII、128 文字以下、|| を含まない）を指定できます。

編集モデルの選択

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

モデルごとに、model_spec.constraintsを確認してください。

• aspectRatios[] — 使用可能なaspect_ratioの値です。すべてのモデルでautoが指定されているとは限りません（例：gpt-image-2-edit、qwen-image-2-edit）。wan-2-7-pro-editで受け付けられるのはautoのみです。
• resolutions[] + defaultResolution — モデルがresolutionを受け付ける場合に存在します。
• qualities[] + defaultQuality — モデルがqualityを受け付ける場合に存在します（複数画像編集のみ）。
• promptCharacterLimit — モデルごとに適用されます（firered-image-editは1,500文字、Nano Bananaの編集では最大32,768文字）。
• combineImages — falseの場合、モデルが受け付ける入力画像はちょうど1枚です。
• maxInputImages — 複数画像編集での入力画像数の上限です。指定がなく、combineImagesがtrueの場合、上限は3枚です。
• supportsOptimizePromptThinking — disable_prompt_optimization_thinkingが機能するかどうかを示します。

料金：編集1回あたりのpricing.inpaint.usd、段階制のモデルではpricing.resolutions[tier] / pricing.quality[tier][level]、追加の入力画像ごとに課金されるモデルではpricing.inputImages（included + 追加画像1枚あたりのadditional.usd）です。includedが0の場合（例：qwen-image-3-edit、Grok Imagineの編集モデル）、/image/editでの1枚の画像を含むすべての入力画像に追加料金がかかります。

現在の代表的な編集ID（リストは頻繁に変わるため、/modelsから取得してください）：firered-image-edit（デフォルト）、qwen-image-3-edit、qwen-image-3-pro-edit、nano-banana-2-edit、nano-banana-pro-edit、gpt-image-2-5-flare-edit、gpt-image-2-5-sunburst-edit、gpt-image-2-edit、seedream-v5-pro-edit、seedream-v5-lite-edit、muse-image-edit、flux-2-max-edit、grok-imagine-image-2-0-edit、luma-uni-1-edit（画像1枚のみ）。古いqwen-edit IDもエイリアスとして引き続き使用でき、qwen-edit-uncensoredが実行されます。

/image/edit

短く説明的なプロンプトで画像を1枚編集します。

curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3-edit",
    "prompt": "Change the color of the sky to a sunrise",
    "image": "https://example.com/photo.jpg",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "safe_mode": true
  }'

マルチパート形式で送信することもできます。imageをファイルパートとして、その他のフィールドをテキストパートとして送信します（-F [email protected] -F prompt=... -F model=...）。ファイルは1つのみ指定できます。

フィールド	補足
model	デフォルトはfirered-image-editです。GET /models?type=inpaintにあるIDを指定してください（それ以外の場合は400 Invalid model id）。非推奨のエイリアスとしてmodelIdも引き続き受け付けます。両方が送信された場合はmodelが優先されます。
prompt	必須です。モデルのpromptCharacterLimit以下にしてください（上限は32,768文字）。短く具体的なプロンプトが最適です。
image	必須です。受け付け可能な入力形式については、共通ルールを参照してください。
aspect_ratio	任意：auto、1:1、3:2、16:9、21:9、9:16、2:3、3:4、4:3、4:5。モデルのconstraints.aspectRatiosに含まれている必要があります。含まれていない場合は400が返されます。入力画像から推定するには、省略するか（一覧にある場合は）autoを送信してください。
resolution	任意。例："1K"、"2K"、"4K"。モデルのconstraints.resolutionsに含まれている必要があります。解像度に対応していないモデルにこのエンドポイントでresolutionを送信すると、400が返されます。 デフォルトはモデルのdefaultResolutionです。
output_format	任意。jpeg（またはjpg） | png | webp。省略した場合は、1K（または解像度の指定なし）ではPNG、2K/4KではJPEGになります。
enhance_prompt	任意のbool値。デフォルトはfalseです。編集前に入力画像に合わせてプロンプトを書き換えます。書き換えが行われた場合、最大約30秒かかり、$0.04の料金が加算されます。書き換え後のプロンプトは、レスポンスヘッダーx-venice-enhanced-promptにURLエンコードされて返されます。
disable_prompt_optimization_thinking	任意のbool値です。supportsOptimizePromptThinking: trueのモデルでのみ有効になり、それ以外のモデルでは無視されます。
safe_mode	デフォルトはtrueです。成人向けコンテンツをぼかします。

/image/editにqualityフィールドはありません。送信すると400が返され、品質段階制モデルはdefaultQualityで課金されます。品質段階を選ぶ場合（GPT Imageモデル、ideogram-v4-5-edit）は、画像を1枚だけ指定して/image/multi-editを使用してください。

適切なプロンプトの例：「木を取り除く」、「猫にサングラスをかける」、「空を鮮やかなオレンジ色の日の出にする」。

/image/multi-edit

プロンプトを使って複数の画像を1つにまとめます。最初の画像がベースで、残りはレイヤーまたは参照画像です。画像は最低1枚必要です。最大枚数はモデルごとに異なります。constraints.maxInputImages（現在のほとんどのモデルでは6枚）に指定されている値を使用します。このフィールドがない場合は3枚、combineImages が false の場合は1枚です。

フィールド名： /image/multi-edit で受け付けるのは model ではなく modelId です。model を送信すると、400（不明なフィールド）が返されます。

JSON（base64、データ URI、または URL）

{
  "modelId": "nano-banana-2-edit",
  "prompt": "Place the person from image 2 onto the beach in image 1",
  "images": [
    "https://example.com/beach.jpg",
    "data:image/png;base64,iVBOR..."
  ],
  "resolution": "2K",
  "safe_mode": true
}

マルチパート（ファイルのアップロード）

POST /image/multi-edit
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="modelId"

nano-banana-2-edit
--boundary
Content-Disposition: form-data; name="prompt"

Place the person from image 2 onto the beach in image 1
--boundary
Content-Disposition: form-data; name="images"; filename="base.jpg"
Content-Type: image/jpeg

<bytes>
--boundary
Content-Disposition: form-data; name="images"; filename="subject.png"
Content-Type: image/png

<bytes>
--boundary--

マルチパートで images に指定できるのはファイルパーツのみです（URL と base64 は不可）。トランスポート層で受け付けられるファイルは最大10個です。

フィールド	備考
modelId	デフォルトは firered-image-edit です。インペイントモデル ID を指定する必要があります。
prompt	必須です。文字数はモデルの promptCharacterLimit 以下にしてください。
images	必須です。1枚からモデルごとの最大枚数まで指定できます。combineImages: false のモデル（例：luma-uni-1-edit）に複数の画像を指定すると、400 が返されます。
aspect_ratio	省略可能です。/image/edit と同じ列挙値を使用します。モデルの aspectRatios に含まれている必要があります。auto を指定するか省略すると、最初の画像から推測されます。
resolution	省略可能です。モデルに resolutions がある場合、その値のいずれかを指定する必要があります。resolutions のないモデルでは、/image/edit とは異なり、エラーにならず無視されます。デフォルトは defaultResolution です。
quality	constraints.qualities があるモデル（GPT Image 2 / 2.5 edits、ideogram-v4-5-edit）で使用できる、low | medium | high のいずれかを指定する省略可能な項目です。Grok Imagine 2.0 edit では low / medium を指定できます。リストにない値を指定すると 400 が返され、その他のモデルでは無視されます。省略した場合は defaultQuality が使用されます。料金が変わります。
output_format	jpeg/jpg | png | webp を指定する省略可能な項目です。省略した場合、1K では PNG、2K/4K では JPEG が使用されます。
enhance_prompt	デフォルトが false の、省略可能な bool 値です。動作、$0.04 の料金、および x-venice-enhanced-prompt ヘッダーは /image/edit と同じです。
disable_prompt_optimization_thinking	省略可能な bool 値です。
safe_mode	デフォルトは true です。

Edit / multi-edit のレスポンスヘッダー

ヘッダー	意味
Content-Type	出力バイト列から検出されます（image/png、image/jpeg、または image/webp）。
x-venice-model-id, x-venice-model-name	実行されたモデルです。
x-venice-is-blurred	safe_mode によって出力がぼかされた場合は "true" です。
x-venice-is-content-violation	200 の場合、常に "false" です。フラグが付いた編集は代わりに 422 を返します（エラーを参照）。
x-venice-enhanced-prompt	URL エンコードされた書き換え後のプロンプトです（enhance_prompt によって生成された場合のみ）。
x-venice-model-deprecation-warning, x-venice-model-deprecation-date, x-venice-deprecated, x-venice-deprecated-replacement	モデルの非推奨に関する通知です。

/image/upscale

Venice 独自のアップスケーラー（モデル ID upscaler）を使用して、2×～4×にアップスケールします。指定するフィールドは3つです。

curl https://api.venice.ai/api/v1/image/upscale \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgo...",
    "scale": 4,
    "creativity": 0.01
  }'

フィールド	型	デフォルト	備考
image	raw base64 文字列（JSON）またはファイル（マルチパートのフィールド image）	—	必須です。URL は受け付けられません。65,536 px 以上、25 MB 未満である必要があります。
scale	数値、2～4	2	2 または 4 として説明されています。2 未満（以前の scale: 1 を含む）を指定すると、400 が返されます。width × height × scale² が 16,777,216 px を超える場合、スケールは自動的に縮小されます。実際にアップスケールできるサイズがない場合は、400 が返されます。
creativity	数値	0.01	アップスケーラーが追加するディテールとテクスチャの量です。0～0.02 の範囲に制限されるため、0.5 を指定しても 0.02 として扱われます。null は 0 に変換されます。

レスポンス：image/png バイト列です。アップスケールが成功するたびに料金が発生します。

料金（/models の pricing.upscale に基づく）：実効スケールが2以下の場合は $0.02、2を超える場合は $0.08 です。たとえば、scale: 3 は4×の料金で請求されます。

破壊的変更（アップスケーラーの書き換え）： 以前の enhance、enhanceCreativity、enhancePrompt、replication フィールドは機能しなくなりました。エラーにはならず無視されるため、混乱を避けるために削除してください。creativity は enhanceCreativity の名前を変更したものではありません。範囲は0～0.02のみです。そのため、以前の enhanceCreativity: 0.5 を creativity: 0.5 として送信すると、単に最大値の 0.02 として扱われます。

/image/background-remove

bria-bg-remover（anonymizedモデル、/modelsによると1回の呼び出しにつき$0.03）で、背景が透明なPNGの切り抜きを生成します。

# With base64 (raw or data URI)
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "iVBOR..."}'

# With a URL
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg"}'

# With a file
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F [email protected]

• JSON：image（空でないbase64。生のbase64はPNGとして扱われます）またはimage_urlのどちらか一方だけを送信します。両方を送信した場合、どちらも送信しなかった場合、またはimageが空もしくは空白のみの場合は、400になります。
• マルチパート：imageに空でないファイルを1つ指定します。マルチパートではimage_urlは受け付けられません。
• レスポンス：アルファチャンネル付きのimage/pngと、x-venice-model-id／x-venice-model-nameヘッダーが返されます。

エラーの動作（4つすべてのエンドポイント）

コード	原因
400	パラメーター不正：スキーマ違反または不明なフィールド、無効または破損した画像、小さすぎる画像、8Kを超える複数画像編集、未知のモデルまたは編集非対応モデル（Invalid model id）、モデルの上限を超えるプロンプト、モデルが対応していないaspect_ratio／resolution／quality、入力画像が多すぎる、ブロックされたURL、未対応のContent-Type（編集、アップスケール、背景除去）。
401	認証に失敗しました。
402	認証情報がまったくない（x402の支払い要件を示す本文とPAYMENT-REQUIREDヘッダー）、残高不足（Bearer：「Insufficient USD or Diem balance…」；x402ウォレット：PAYMENT_REQUIREDの本文とヘッダー）、またはAPIキーのUSD／DIEM利用上限に達しています。
403	APIキーのmodelPrivacy設定によりモデルがブロックされています。PRIVATE_ONLYキーでは匿名化モデルを使用できません。ほとんどの編集モデルとbria-bg-removerがこれに含まれます。
404	編集／複数画像編集：プロバイダーが入力メディアを見つけられなかったか、取得できませんでした（本文にはプロバイダーのメッセージが含まれます）。
413	マルチパートファイルが25 MBを超えているか、リクエスト本文が大きすぎます。
415	/image/multi-editのみ。本文が空の場合に返されます。いずれかのルートで誤ったContent-Typeを指定すると400になります（"'Content-Type' must be 'application/json'"）。JSONまたはマルチパートを送信してください。
422	編集／複数画像編集でのコンテンツポリシー違反（{"error":"Your prompt violates the content policy of Venice.ai or the model provider"}。codeフィールドはありません）、または処理中に画像がピクセル数の上限を超えた場合（例：/image/editの入力が8Kを超える）。
429	レート制限に達したか、上流プロバイダーが過負荷状態です。
500	編集／アップスケール／背景除去に失敗しました。
503	モデルが容量上限に達しています。ジッターを加えて再試行してください。

422のコンテンツポリシーによる拒否では、通常、料金は発生しません。プロバイダーがすでに画像を生成した後にVenice独自のモデレーションが画像をブロックした場合、編集の料金は発生します。本文の形式と再試行の方法については、venice-errorsを参照してください。

注意点

• フィールド名はエンドポイントによって異なります：/image/editでは**modelを使用します（modelIdは非推奨の別名です）。/image/multi-editではmodelIdのみ**を受け付けます。
• resolutionの動作はエンドポイントごとに異なります。/image/editでは、解像度に対応していないモデルに送信すると400になります。/image/multi-editでは、無視されます。
• qualityは/image/multi-editにはありますが、/image/editにはありません。
• aspectRatiosにautoが含まれていないモデル（例：gpt-image-2-edit）には、aspect_ratio: "auto"を送信しないでください。代わりにフィールドを省略してください。
• マルチパートの/image/multi-editでは、同じフィールド名imagesを使って複数のパートを送信してください。順序が重要です。ベース画像を最初に指定してください。
• /image/upscaleでは、JSONに生のbase64が必要です。data:image/...;base64,のプレフィックスを削除してください。編集、複数画像編集、背景除去ではデータURIを使用できます。
• 大きな入力に対してscale: 4を指定した/image/upscaleでは、16 MP未満に収まるように倍率が自動的に下げられます。実際の倍率が2を超える場合、倍率が下げられても4倍の料金が請求されます。
• 編集／複数画像編集でenhance_promptを指定すると、書き換えが生成された場合に$0.04が請求されます。レイテンシーまたはコストを重視する場合は、オフにしてください。
• safe_mode: trueにより、本来は有効な出力がぼかされる場合があります。x-venice-is-blurredを確認してください。入力を管理し、ToS上の影響を受け入れられる場合に限り、falseに切り替えてください。
• 一部のモデルでは、含まれる枚数を超えた入力画像1枚ごとに追加料金がかかります（pricing.inputImages）。includedが0の場合、画像1枚の/image/editでも追加料金が発生します。