画像を編集

画像から画像 / 画像編集：GPT Image（mask 対応）、Seedream、および「Gemini 全モデル（画像生成含む）」グループの Gemini。

POST/v1/images/edits

参照画像をもとに生成、または部分編集します。リクエスト形式は multipart/form-data を推奨します（ローカルファイル、参照画像フィールドは image / image[] で繰り返し可）。JSON（参照画像は HTTP(S) URL または Data URL）も受け付け、どちらもフィールド名は同じです。右側の例は JSON です。multipart の書き方は画像生成ガイドを参照してください。

JSON での編集と非同期タスクでは output_compression、moderation、user、response_format は保持されません。「Gemini 公式ダイレクト」グループにはこのエンドポイントがないため、画像を生成で参照画像を渡してください。

画像を編集

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "参照画像をゴッホの「星月夜」風の油絵にしてください",
    "image": "https://example.com/input.png",
    "size": "1536x1024",
    "quality": "medium"
  }'

200application/json

{
  "created": 1790222400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 1310,
    "output_tokens": 1056,
    "total_tokens": 2366
  }
}

ヘッダー

Authorization:必須string

Bearer sk-…：コンソールの「API キー」で作成したキー。キーのグループにリクエストするモデルが含まれている必要があります

Prefer:任意string

respond-async：GPT Image / Gemini は即座に 202 Accepted、task_id、status_url を返すので、GET /v1/images/tasks?task_id=… でポーリングします。2K / 4K の大きな画像を生成する場合に推奨します。Seedream はこのヘッダーを無視し、通常どおり同期で返します

取りうる値respond-async

リクエストボディJSON

モデル画像リクエストビルダーで開くモデルのドキュメント

グループ：GPT Image 全モデル。結果は data[].b64_json から読み取ります。参照画像は最大 16 枚。

model:必須"gpt-image-2"

まず現在のキーの GET /v1/models にこの ID が含まれていることを確認してください

prompt:必須string

生成または編集の指示。空の場合は 400 prompt must not be empty。ゲートウェイでは長さを制限せず、上限は公式上限に従います

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ1–32000 文字

size:任意"auto" または string

例：1024x1024、2048x2048、3840x2160。不正な値は生成前に 400 を返し、課金されません。1K / 2K / 4K は受け付けません

制限auto または幅x高さ：辺の長さは 16 の倍数、1 辺 3840 以下、長辺と短辺の比 3:1 以下、総ピクセル数 655360–8294400

quality:任意string

レベルが高いほど出力トークンが増え、費用も高くなります。1024x1024 の実測では low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 出力トークンです

取りうる値autolowmediumhigh

制限ゲートウェイでは検証せず、そのまま転送。レベルが高いほど出力トークンが増えます

n:任意integer

一部のグループは 1 のみ対応で、それより大きい値は 400 を返します。0 以下は 1 として扱います

範囲1–10デフォルト1

background:任意string

transparent は png または webp と組み合わせる必要があります。2.0 の透明背景はプレビュー機能です

取りうる値autoopaquetransparent

output_format:任意string

b64_json をデコードした後の形式を決めます

取りうる値pngjpegwebp

output_compression:任意integer

jpeg / webp のみ。同期の generations JSON と multipart の編集でのみ保持されます

範囲0–100デフォルト100

moderation:任意string

コンテンツの安全性チェックを無効にするものではありません

取りうる値autolow

user:任意string

エンドユーザー識別用の文字列。HopBase のアカウント ID ではなく、課金の帰属も変わりません

response_format:任意string

何を指定しても b64_json で返され、url でダウンロードリンクは取得できません。省略してください

stream:任意boolean

true にすると HopBase Images SSE になります（その間キープアライブを送信し、最後の data: イベントだけが Images JSON で、[DONE] で終わります）。OpenAI ネイティブの画像ごとのプレビューイベントではありません。SDK では false のままにしてください

制限true で HopBase Images SSE を返します。SDK では false のままにしてくださいデフォルトfalse

input_fidelity:任意string

互換用フィールド。GPT Image 2 は既定で参照画像を高忠実度で処理するため、省略してください

取りうる値lowhigh

image:必須string または array of string

multipart のファイル（image / image[]）、または JSON の HTTP(S) URL / Data URL 文字列、文字列配列。images は読み取らず、生の base64 や file_id は受け付けません。転送前に圧縮されることがあります

制限1–16 枚（公式上限）。リモート URL は 1 枚 26214400 バイト以下で、image/* を返す必要があります。image のみ読み取り、images は読み取りません

mask:任意string

透明な領域が編集対象です。ゲートウェイは mask を 1 枚目の参照画像のサイズに合わせて拡縮します。マスク外がピクセル単位で変わらないことは保証されません

制限アルファチャンネル付きの PNG。透明な領域が編集対象です

transparent には png または webp が必要です
output_compression は jpeg / webp でのみ有効です

model:必須"gpt-image-2.5-flare"

まず現在のキーの GET /v1/models にこの ID が含まれていることを確認してください

prompt:必須string

生成または編集の指示。空の場合は 400 prompt must not be empty。ゲートウェイでは長さを制限せず、上限は公式上限に従います

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ1–32000 文字

size:任意"auto" または string

例：1024x1024、2048x2048、3840x2160。不正な値は生成前に 400 を返し、課金されません。1K / 2K / 4K は受け付けません

制限auto または幅x高さ：辺の長さは 16 の倍数、1 辺 3840 以下、長辺と短辺の比 3:1 以下、総ピクセル数 655360–8294400

quality:任意string

レベルが高いほど出力トークンが増え、費用も高くなります。1024x1024 の実測では low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 出力トークンです

取りうる値autolowmediumhighxhighmax

制限ゲートウェイでは検証せず、そのまま転送。レベルが高いほど出力トークンが増えます

n:任意integer

一部のグループは 1 のみ対応で、それより大きい値は 400 を返します。0 以下は 1 として扱います

範囲1–10デフォルト1

background:任意string

transparent は png または webp と組み合わせる必要があります。2.0 の透明背景はプレビュー機能です

取りうる値autoopaquetransparent

output_format:任意string

b64_json をデコードした後の形式を決めます

取りうる値pngjpegwebp

output_compression:任意integer

jpeg / webp のみ。同期の generations JSON と multipart の編集でのみ保持されます

範囲0–100デフォルト100

moderation:任意string

コンテンツの安全性チェックを無効にするものではありません

取りうる値autolow

user:任意string

エンドユーザー識別用の文字列。HopBase のアカウント ID ではなく、課金の帰属も変わりません

response_format:任意string

何を指定しても b64_json で返され、url でダウンロードリンクは取得できません。省略してください

stream:任意boolean

制限true で HopBase Images SSE を返します。SDK では false のままにしてくださいデフォルトfalse

input_fidelity:任意string

互換用フィールド。GPT Image 2 は既定で参照画像を高忠実度で処理するため、省略してください

取りうる値lowhigh

image:必須string または array of string

制限1–16 枚（公式上限）。リモート URL は 1 枚 26214400 バイト以下で、image/* を返す必要があります。image のみ読み取り、images は読み取りません

mask:任意string

制限アルファチャンネル付きの PNG。透明な領域が編集対象です

transparent には png または webp が必要です
output_compression は jpeg / webp でのみ有効です

model:必須"gpt-image-2.5-sunburst"

まず現在のキーの GET /v1/models にこの ID が含まれていることを確認してください

prompt:必須string

生成または編集の指示。空の場合は 400 prompt must not be empty。ゲートウェイでは長さを制限せず、上限は公式上限に従います

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ1–32000 文字

size:任意"auto" または string

例：1024x1024、2048x2048、3840x2160。不正な値は生成前に 400 を返し、課金されません。1K / 2K / 4K は受け付けません

制限auto または幅x高さ：辺の長さは 16 の倍数、1 辺 3840 以下、長辺と短辺の比 3:1 以下、総ピクセル数 655360–8294400

quality:任意string

レベルが高いほど出力トークンが増え、費用も高くなります。1024x1024 の実測では low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 出力トークンです

取りうる値autolowmediumhighxhighmax

制限ゲートウェイでは検証せず、そのまま転送。レベルが高いほど出力トークンが増えます

n:任意integer

一部のグループは 1 のみ対応で、それより大きい値は 400 を返します。0 以下は 1 として扱います

範囲1–10デフォルト1

background:任意string

transparent は png または webp と組み合わせる必要があります。2.0 の透明背景はプレビュー機能です

取りうる値autoopaquetransparent

output_format:任意string

b64_json をデコードした後の形式を決めます

取りうる値pngjpegwebp

output_compression:任意integer

jpeg / webp のみ。同期の generations JSON と multipart の編集でのみ保持されます

範囲0–100デフォルト100

moderation:任意string

コンテンツの安全性チェックを無効にするものではありません

取りうる値autolow

user:任意string

エンドユーザー識別用の文字列。HopBase のアカウント ID ではなく、課金の帰属も変わりません

response_format:任意string

何を指定しても b64_json で返され、url でダウンロードリンクは取得できません。省略してください

stream:任意boolean

制限true で HopBase Images SSE を返します。SDK では false のままにしてくださいデフォルトfalse

input_fidelity:任意string

互換用フィールド。GPT Image 2 は既定で参照画像を高忠実度で処理するため、省略してください

取りうる値lowhigh

image:必須string または array of string

制限1–16 枚（公式上限）。リモート URL は 1 枚 26214400 バイト以下で、image/* を返す必要があります。image のみ読み取り、images は読み取りません

mask:任意string

制限アルファチャンネル付きの PNG。透明な領域が編集対象です

transparent には png または webp が必要です
output_compression は jpeg / webp でのみ有効です

model:必須"gemini-3.1-flash-image"

現在のキーの GET /v1/models の返り値が基準です

prompt:必須string

モデルが拒否した、またはテキストのみを返した場合は 400（メッセージにそのテキストを引用）または 502 を返します。プロンプトを書き換えてください

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ≥ 1 文字

n:任意integer

並列で生成します。全か無か：いずれか 1 枚でも失敗するとリクエスト全体が失敗し、課金されません

制限出力解像度ごとの上限：1K ≤ 10、2K ≤ 5範囲1–10デフォルト1

image_size:任意string

トップレベルのフラットな書き方で、google.image_config.image_size と等価です。size から導かれるレベルを上書きします

取りうる値1K2K

デフォルト"1K"

aspect_ratio:任意string

トップレベルのフラットな書き方で、google.image_config.aspect_ratio と等価です。size より優先されます

取りうる値1:12:33:23:44:34:55:49:1616:921:9

デフォルト"1:1"

size:任意"auto" または string

幅x高さ は比率を理由に拒否されることはありません。最も近い公式の比率に対応付けられ、レベルは長辺から導かれ、モデルの最高レベルまで黙って引き下げられます。モデルのレベルを超える 1K / 2K / 4K を明示すると 400 を返します。image_size も同時に指定した場合はそちらが優先されます

取りうる値1K2K

制限auto、任意の比率の幅x高さ（最も近い公式の比率に対応付け、解像度は長辺から導き、モデルの最高解像度まで黙って引き下げ）、またはモデルの解像度

google:任意object

SDK では extra_body.google.image_config とも書けます。3 つの書き方は等価です

image:任意string または array of string

参照画像。generations のリクエストボディに入れるだけで使えます。両方指定した場合は images が優先されます。「Gemini 公式ダイレクト」は 1 枚あたりデコード後 20 MiB 以下で、/v1/images/edits はありません

制限参照画像：文字列または文字列の配列、最大 14 枚

images:任意string または array of string

image と同じ。両方指定した場合は images が優先されます

制限参照画像：文字列または文字列の配列、最大 14 枚

mask:非対応

非対応：mask を指定すると 400 を返します。部分的な修正はプロンプトで領域を説明してください

background:任意any

transparent には非対応（400 を返します）

指定不可"transparent"

stream:任意any

非対応。省略するか false を指定してください

指定不可true

2K 出力は 1 回あたり最大 5 枚（レスポンスサイズの上限）

model:必須"gemini-3.1-flash-image-preview"

現在のキーの GET /v1/models の返り値が基準です

prompt:必須string

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ≥ 1 文字

n:任意integer

並列で生成します。全か無か：いずれか 1 枚でも失敗するとリクエスト全体が失敗し、課金されません

制限出力解像度ごとの上限：1K ≤ 10、2K ≤ 5範囲1–10デフォルト1

image_size:任意string

トップレベルのフラットな書き方で、google.image_config.image_size と等価です。size から導かれるレベルを上書きします

取りうる値1K2K

デフォルト"1K"

aspect_ratio:任意string

トップレベルのフラットな書き方で、google.image_config.aspect_ratio と等価です。size より優先されます

取りうる値1:12:33:23:44:34:55:49:1616:921:9

デフォルト"1:1"

size:任意"auto" または string

取りうる値1K2K

google:任意object

SDK では extra_body.google.image_config とも書けます。3 つの書き方は等価です

image:任意string または array of string

制限参照画像：文字列または文字列の配列、最大 14 枚

images:任意string または array of string

image と同じ。両方指定した場合は images が優先されます

制限参照画像：文字列または文字列の配列、最大 14 枚

mask:非対応

非対応：mask を指定すると 400 を返します。部分的な修正はプロンプトで領域を説明してください

background:任意any

transparent には非対応（400 を返します）

指定不可"transparent"

stream:任意any

非対応。省略するか false を指定してください

指定不可true

2K 出力は 1 回あたり最大 5 枚（レスポンスサイズの上限）

model:必須"gemini-3-pro-image"

現在のキーの GET /v1/models の返り値が基準です

prompt:必須string

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ≥ 1 文字

n:任意integer

並列で生成します。全か無か：いずれか 1 枚でも失敗するとリクエスト全体が失敗し、課金されません

制限出力解像度ごとの上限：1K ≤ 10、2K ≤ 5、4K ≤ 2範囲1–10デフォルト1

image_size:任意string

トップレベルのフラットな書き方で、google.image_config.image_size と等価です。size から導かれるレベルを上書きします

取りうる値1K2K4K

デフォルト"1K"

aspect_ratio:任意string

トップレベルのフラットな書き方で、google.image_config.aspect_ratio と等価です。size より優先されます

取りうる値1:12:33:23:44:34:55:49:1616:921:9

デフォルト"1:1"

size:任意"auto" または string

取りうる値1K2K4K

google:任意object

SDK では extra_body.google.image_config とも書けます。3 つの書き方は等価です

image:任意string または array of string

制限参照画像：文字列または文字列の配列、最大 14 枚

images:任意string または array of string

image と同じ。両方指定した場合は images が優先されます

制限参照画像：文字列または文字列の配列、最大 14 枚

mask:非対応

非対応：mask を指定すると 400 を返します。部分的な修正はプロンプトで領域を説明してください

background:任意any

transparent には非対応（400 を返します）

指定不可"transparent"

stream:任意any

非対応。省略するか false を指定してください

指定不可true

2K 出力は 1 回あたり最大 5 枚（レスポンスサイズの上限）
4K 出力は 1 回あたり最大 2 枚（レスポンスサイズの上限）

model:必須"gemini-3.1-flash-lite-image"

現在のキーの GET /v1/models の返り値が基準です

prompt:必須string

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ≥ 1 文字

n:任意integer

並列で生成します。全か無か：いずれか 1 枚でも失敗するとリクエスト全体が失敗し、課金されません

制限出力解像度ごとの上限：1K ≤ 10範囲1–10デフォルト1

image_size:任意string

トップレベルのフラットな書き方で、google.image_config.image_size と等価です。size から導かれるレベルを上書きします

取りうる値1K

デフォルト"1K"

aspect_ratio:任意string

トップレベルのフラットな書き方で、google.image_config.aspect_ratio と等価です。size より優先されます

取りうる値1:12:33:23:44:34:55:49:1616:921:9

デフォルト"1:1"

size:任意"auto" または string

取りうる値1K

google:任意object

SDK では extra_body.google.image_config とも書けます。3 つの書き方は等価です

image:任意string または array of string

制限参照画像：文字列または文字列の配列、最大 14 枚

images:任意string または array of string

image と同じ。両方指定した場合は images が優先されます

制限参照画像：文字列または文字列の配列、最大 14 枚

mask:非対応

非対応：mask を指定すると 400 を返します。部分的な修正はプロンプトで領域を説明してください

background:任意any

transparent には非対応（400 を返します）

指定不可"transparent"

stream:任意any

非対応。省略するか false を指定してください

指定不可true

model:必須"gemini-2.5-flash-image"

現在のキーの GET /v1/models の返り値が基準です

prompt:必須string

制限前後の空白を除いて空にはできません。空の場合は 400「prompt must not be empty」長さ≥ 1 文字

n:任意integer

並列で生成します。全か無か：いずれか 1 枚でも失敗するとリクエスト全体が失敗し、課金されません

制限出力解像度ごとの上限：1K ≤ 10範囲1–10デフォルト1

image_size:任意string

トップレベルのフラットな書き方で、google.image_config.image_size と等価です。size から導かれるレベルを上書きします

取りうる値1K

デフォルト"1K"

aspect_ratio:任意string

トップレベルのフラットな書き方で、google.image_config.aspect_ratio と等価です。size より優先されます

取りうる値1:12:33:23:44:34:55:49:1616:921:9

デフォルト"1:1"

size:任意"auto" または string

取りうる値1K

google:任意object

SDK では extra_body.google.image_config とも書けます。3 つの書き方は等価です

image:任意string または array of string

制限参照画像：文字列または文字列の配列、最大 3 枚

images:任意string または array of string

image と同じ。両方指定した場合は images が優先されます

制限参照画像：文字列または文字列の配列、最大 3 枚

mask:非対応

非対応：mask を指定すると 400 を返します。部分的な修正はプロンプトで領域を説明してください

background:任意any

transparent には非対応（400 を返します）

指定不可"transparent"

stream:任意any

非対応。省略するか false を指定してください

指定不可true

レスポンス

200同期で成功

202Prefer: respond-async 指定時

created:任意integer

Unix 秒

data:必須array of object

画像 1 枚につき 1 項目

usage:任意object

返される場合あり

エラー

400パラメータ不正（生成前に拒否、課金なし）

401キー未指定、キーが無効または期限切れ（missing_api_key / invalid_api_key / api_key_expired）

402残高、またはキー・メンバー・部門のクォータを使い切った（insufficient_quota）

404モデルがこのキーのグループにない（model_not_found）、またはパスがそのグループに属さない（route_not_found）

413リクエストボディが 60 MB を超えた（request_too_large）

429アカウントまたはキーの同時実行数が上限に達した（user_concurrency_limit / apikey_concurrency_limit）。Retry-After 付き

ヘッダー

リクエストボディJSON

レスポンス

エラー

関連ページ