编辑图片

图生图 / 图片编辑：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 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400

quality:可选string

档位越高输出 token 越多、费用越高：1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token

可选值autolowmediumhigh

限制网关不校验、原样转发；档位越高输出 token 越多

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 取得下载链接，请省略

限制传什么都以 b64_json 返回，请省略

stream:可选boolean

true 改为 HopBase Images SSE（期间发送 keepalive，最后一个 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 单张 ≤ 26214400 字节且须返回 image/*。只读 image，不读 images

mask:可选string

透明区域表示要编辑；网关会把 mask 缩放到第一张参考图的尺寸；不保证遮罩外逐像素不变

限制带 alpha 通道的 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 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400

quality:可选string

档位越高输出 token 越多、费用越高：1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token

可选值autolowmediumhighxhighmax

限制网关不校验、原样转发；档位越高输出 token 越多

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 取得下载链接，请省略

限制传什么都以 b64_json 返回，请省略

stream:可选boolean

true 改为 HopBase Images SSE（期间发送 keepalive，最后一个 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 单张 ≤ 26214400 字节且须返回 image/*。只读 image，不读 images

mask:可选string

透明区域表示要编辑；网关会把 mask 缩放到第一张参考图的尺寸；不保证遮罩外逐像素不变

限制带 alpha 通道的 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 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400

quality:可选string

档位越高输出 token 越多、费用越高：1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token

可选值autolowmediumhighxhighmax

限制网关不校验、原样转发；档位越高输出 token 越多

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 取得下载链接，请省略

限制传什么都以 b64_json 返回，请省略

stream:可选boolean

true 改为 HopBase Images SSE（期间发送 keepalive，最后一个 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 单张 ≤ 26214400 字节且须返回 image/*。只读 image，不读 images

mask:可选string

透明区域表示要编辑；网关会把 mask 缩放到第一张参考图的尺寸；不保证遮罩外逐像素不变

限制带 alpha 通道的 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

并行生成。全有或全无：任一张失败则整个请求失败、不计费

限制按输出档位封顶：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；三种写法等价

image:可选string 或 array of string

参考图，放在 generations 请求体即可；同时传时以 images 为准。「Gemini 官方直连」单张解码后 ≤ 20 MiB，没有 /v1/images/edits

限制参考图：字符串或字符串数组，最多 14 张

images:可选string 或 array of string

同 image，同时传时以 images 为准

限制参考图：字符串或字符串数组，最多 14 张

mask:不支持

不支持：传 mask 返回 400；局部修改请在 prompt 中描述区域

background:可选any

不支持 transparent（返回 400）

不能为"transparent"

stream:可选any

不支持，请省略或传 false

不能为true

2K 输出每次最多 5 张（响应体积上限）

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

以当前密钥 GET /v1/models 的返回为准

prompt:必填string

模型拒答或只回文字时返回 400（消息引用该段文字）或 502：请改写提示词

限制去除首尾空白后不能为空，否则 400「prompt must not be empty」长度≥ 1 字符

n:可选integer

并行生成。全有或全无：任一张失败则整个请求失败、不计费

限制按输出档位封顶：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

限制auto、任意比例的宽x高（映射到最接近的官方比例，档位按长边推导并静默降到型号最高档位），或型号档位

google:可选object

SDK 可写成 extra_body.google.image_config；三种写法等价

image:可选string 或 array of string

参考图，放在 generations 请求体即可；同时传时以 images 为准。「Gemini 官方直连」单张解码后 ≤ 20 MiB，没有 /v1/images/edits

限制参考图：字符串或字符串数组，最多 14 张

images:可选string 或 array of string

同 image，同时传时以 images 为准

限制参考图：字符串或字符串数组，最多 14 张

mask:不支持

不支持：传 mask 返回 400；局部修改请在 prompt 中描述区域

background:可选any

不支持 transparent（返回 400）

不能为"transparent"

stream:可选any

不支持，请省略或传 false

不能为true

2K 输出每次最多 5 张（响应体积上限）

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

以当前密钥 GET /v1/models 的返回为准

prompt:必填string

模型拒答或只回文字时返回 400（消息引用该段文字）或 502：请改写提示词

限制去除首尾空白后不能为空，否则 400「prompt must not be empty」长度≥ 1 字符

n:可选integer

并行生成。全有或全无：任一张失败则整个请求失败、不计费

限制按输出档位封顶：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

限制auto、任意比例的宽x高（映射到最接近的官方比例，档位按长边推导并静默降到型号最高档位），或型号档位

google:可选object

SDK 可写成 extra_body.google.image_config；三种写法等价

image:可选string 或 array of string

参考图，放在 generations 请求体即可；同时传时以 images 为准。「Gemini 官方直连」单张解码后 ≤ 20 MiB，没有 /v1/images/edits

限制参考图：字符串或字符串数组，最多 14 张

images:可选string 或 array of string

同 image，同时传时以 images 为准

限制参考图：字符串或字符串数组，最多 14 张

mask:不支持

不支持：传 mask 返回 400；局部修改请在 prompt 中描述区域

background:可选any

不支持 transparent（返回 400）

不能为"transparent"

stream:可选any

不支持，请省略或传 false

不能为true

2K 输出每次最多 5 张（响应体积上限）
4K 输出每次最多 2 张（响应体积上限）

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

以当前密钥 GET /v1/models 的返回为准

prompt:必填string

模型拒答或只回文字时返回 400（消息引用该段文字）或 502：请改写提示词

限制去除首尾空白后不能为空，否则 400「prompt must not be empty」长度≥ 1 字符

n:可选integer

并行生成。全有或全无：任一张失败则整个请求失败、不计费

限制按输出档位封顶：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

限制auto、任意比例的宽x高（映射到最接近的官方比例，档位按长边推导并静默降到型号最高档位），或型号档位

google:可选object

SDK 可写成 extra_body.google.image_config；三种写法等价

image:可选string 或 array of string

参考图，放在 generations 请求体即可；同时传时以 images 为准。「Gemini 官方直连」单张解码后 ≤ 20 MiB，没有 /v1/images/edits

限制参考图：字符串或字符串数组，最多 14 张

images:可选string 或 array of string

同 image，同时传时以 images 为准

限制参考图：字符串或字符串数组，最多 14 张

mask:不支持

不支持：传 mask 返回 400；局部修改请在 prompt 中描述区域

background:可选any

不支持 transparent（返回 400）

不能为"transparent"

stream:可选any

不支持，请省略或传 false

不能为true

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

以当前密钥 GET /v1/models 的返回为准

prompt:必填string

模型拒答或只回文字时返回 400（消息引用该段文字）或 502：请改写提示词

限制去除首尾空白后不能为空，否则 400「prompt must not be empty」长度≥ 1 字符

n:可选integer

并行生成。全有或全无：任一张失败则整个请求失败、不计费

限制按输出档位封顶：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

限制auto、任意比例的宽x高（映射到最接近的官方比例，档位按长边推导并静默降到型号最高档位），或型号档位

google:可选object

SDK 可写成 extra_body.google.image_config；三种写法等价

image:可选string 或 array of string

参考图，放在 generations 请求体即可；同时传时以 images 为准。「Gemini 官方直连」单张解码后 ≤ 20 MiB，没有 /v1/images/edits

限制参考图：字符串或字符串数组，最多 3 张

images:可选string 或 array of string

同 image，同时传时以 images 为准

限制参考图：字符串或字符串数组，最多 3 张

mask:不支持

不支持：传 mask 返回 400；局部修改请在 prompt 中描述区域

background:可选any

不支持 transparent（返回 400）

不能为"transparent"

stream:可选any

不支持，请省略或传 false

不能为true

200同步成功

202带 Prefer: respond-async 时

created:可选integer

Unix 秒

data:必填array of object

每张图一项

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

返回

错误

相关页面