编辑图片
图生图 / 图片编辑:GPT Image(支持 mask)、Seedream,以及「Gemini 特价版(AI Studio / Vertex)」分组的 Gemini。
/v1/images/edits基于参考图生成或局部编辑。请求格式推荐 multipart/form-data(本地文件,参考图字段 image / image[],可重复),也接受 JSON(参考图为 HTTP(S) URL 或 Data URL);两种写法字段同名。右侧示例用 JSON,multipart 写法见图片生成指南。
JSON 编辑与异步任务不保留 output_compression、moderation、user、response_format。「Gemini 官方直连(企业级)」分组没有本端点,请在生成图片里传参考图。
产生扣费的非流式响应会返回本次实际扣费:响应头 X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency,以及响应体根对象 usage 里的 cost / cost_usd / currency(usage 原有字段保留)。cost_usd 为本次从余额实际扣除的美元金额,cost 为同一笔扣费的人民币金额,currency 恒为 CNY。流式(SSE)不返回,请到控制台「使用记录」查看;未扣费的响应(如错误)不带。详见账户 API · 扣费。
请求头
Bearer sk-…:控制台「API 密钥」里创建的密钥,所属分组须包含请求的模型
respond-async:GPT Image / Gemini 立即返回 202 Accepted、task_id 与 status_url,再用 GET /v1/images/tasks?task_id=… 轮询。生成 2K / 4K 大图时建议使用;Seedream 忽略此头、照常同步返回
可选值respond-async
请求体参数JSON
data[].b64_json。 参考图最多 16 张。先确认当前密钥的 GET /v1/models 包含此 ID
生成或编辑指令;为空返回 400 prompt must not be empty。网关不限长度,上限为官方上限
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度1–32000 字符
例:1024x1024、2048x2048、3840x2160。不合规在生成前返回 400、不计费;不接受 1K / 2K / 4K
限制auto 或 宽x高:边长为 16 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400
档位越高输出 token 越多、费用越高:1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token
可选值autolowmediumhigh
限制网关不校验、原样转发;档位越高输出 token 越多
部分分组只支持 1,传更大值返回 400;≤ 0 按 1 处理
范围1–10默认1
transparent 需配合 png 或 webp;2.0 透明背景属预览能力
可选值autoopaquetransparent
决定 b64_json 解码后的格式
可选值pngjpegwebp
仅 jpeg / webp;只在同步 generations JSON 与 multipart 编辑中保留
范围0–100默认100
不会关闭内容安全检查
可选值autolow
终端用户识别字符串,不是 HopBase 账户 ID,也不改变计费归属
传什么都以 b64_json 返回,不能靠 url 取得下载链接,请省略
限制传什么都以 b64_json 返回,请省略
true 改为 HopBase Images SSE(期间发送 keepalive,最后一个 data: 事件才是 Images JSON,以 [DONE] 结束),不是 OpenAI 原生逐张预览事件;SDK 请保持 false
限制true 返回 HopBase Images SSE,SDK 请保持 false默认false
兼容字段;GPT Image 2 默认高保真处理参考图,请省略
可选值lowhigh
multipart 文件(image / image[]),或 JSON 的 HTTP(S) URL / Data URL 字符串、字符串数组。不读 images,不接受裸 base64 或 file_id;转发前可能压缩
限制1–16 张(官方上限);远程 URL 单张 ≤ 26214400 字节且须返回 image/*。只读 image,不读 images
透明区域表示要编辑;网关会把 mask 缩放到第一张参考图的尺寸;不保证遮罩外逐像素不变
限制带 alpha 通道的 PNG;透明区域表示要编辑
- transparent 需要 png 或 webp
- output_compression 只对 jpeg / webp 生效
先确认当前密钥的 GET /v1/models 包含此 ID
生成或编辑指令;为空返回 400 prompt must not be empty。网关不限长度,上限为官方上限
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度1–32000 字符
例:1024x1024、2048x2048、3840x2160。不合规在生成前返回 400、不计费;不接受 1K / 2K / 4K
限制auto 或 宽x高:边长为 16 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400
档位越高输出 token 越多、费用越高:1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token
可选值autolowmediumhighxhighmax
限制网关不校验、原样转发;档位越高输出 token 越多
部分分组只支持 1,传更大值返回 400;≤ 0 按 1 处理
范围1–10默认1
transparent 需配合 png 或 webp;2.0 透明背景属预览能力
可选值autoopaquetransparent
决定 b64_json 解码后的格式
可选值pngjpegwebp
仅 jpeg / webp;只在同步 generations JSON 与 multipart 编辑中保留
范围0–100默认100
不会关闭内容安全检查
可选值autolow
终端用户识别字符串,不是 HopBase 账户 ID,也不改变计费归属
传什么都以 b64_json 返回,不能靠 url 取得下载链接,请省略
限制传什么都以 b64_json 返回,请省略
true 改为 HopBase Images SSE(期间发送 keepalive,最后一个 data: 事件才是 Images JSON,以 [DONE] 结束),不是 OpenAI 原生逐张预览事件;SDK 请保持 false
限制true 返回 HopBase Images SSE,SDK 请保持 false默认false
兼容字段;GPT Image 2 默认高保真处理参考图,请省略
可选值lowhigh
multipart 文件(image / image[]),或 JSON 的 HTTP(S) URL / Data URL 字符串、字符串数组。不读 images,不接受裸 base64 或 file_id;转发前可能压缩
限制1–16 张(官方上限);远程 URL 单张 ≤ 26214400 字节且须返回 image/*。只读 image,不读 images
透明区域表示要编辑;网关会把 mask 缩放到第一张参考图的尺寸;不保证遮罩外逐像素不变
限制带 alpha 通道的 PNG;透明区域表示要编辑
- transparent 需要 png 或 webp
- output_compression 只对 jpeg / webp 生效
先确认当前密钥的 GET /v1/models 包含此 ID
生成或编辑指令;为空返回 400 prompt must not be empty。网关不限长度,上限为官方上限
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度1–32000 字符
例:1024x1024、2048x2048、3840x2160。不合规在生成前返回 400、不计费;不接受 1K / 2K / 4K
限制auto 或 宽x高:边长为 16 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400
档位越高输出 token 越多、费用越高:1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token
可选值autolowmediumhighxhighmax
限制网关不校验、原样转发;档位越高输出 token 越多
部分分组只支持 1,传更大值返回 400;≤ 0 按 1 处理
范围1–10默认1
transparent 需配合 png 或 webp;2.0 透明背景属预览能力
可选值autoopaquetransparent
决定 b64_json 解码后的格式
可选值pngjpegwebp
仅 jpeg / webp;只在同步 generations JSON 与 multipart 编辑中保留
范围0–100默认100
不会关闭内容安全检查
可选值autolow
终端用户识别字符串,不是 HopBase 账户 ID,也不改变计费归属
传什么都以 b64_json 返回,不能靠 url 取得下载链接,请省略
限制传什么都以 b64_json 返回,请省略
true 改为 HopBase Images SSE(期间发送 keepalive,最后一个 data: 事件才是 Images JSON,以 [DONE] 结束),不是 OpenAI 原生逐张预览事件;SDK 请保持 false
限制true 返回 HopBase Images SSE,SDK 请保持 false默认false
兼容字段;GPT Image 2 默认高保真处理参考图,请省略
可选值lowhigh
multipart 文件(image / image[]),或 JSON 的 HTTP(S) URL / Data URL 字符串、字符串数组。不读 images,不接受裸 base64 或 file_id;转发前可能压缩
限制1–16 张(官方上限);远程 URL 单张 ≤ 26214400 字节且须返回 image/*。只读 image,不读 images
透明区域表示要编辑;网关会把 mask 缩放到第一张参考图的尺寸;不保证遮罩外逐像素不变
限制带 alpha 通道的 PNG;透明区域表示要编辑
- transparent 需要 png 或 webp
- output_compression 只对 jpeg / webp 生效
先确认当前密钥的 GET /v1/models 包含此 ID
生成或编辑指令;为空返回 400 prompt must not be empty。网关不限长度,上限为官方上限
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度1–32000 字符
例:1024x1024、2048x2048、3840x2160。不合规在生成前返回 400、不计费;不接受 1K / 2K / 4K
限制auto 或 宽x高:边长为 16 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400
档位越高输出 token 越多、费用越高:1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token
可选值autolowmediumhighxhighmax
限制网关不校验、原样转发;档位越高输出 token 越多
部分分组只支持 1,传更大值返回 400;≤ 0 按 1 处理
范围1–10默认1
transparent 需配合 png 或 webp;2.0 透明背景属预览能力
可选值autoopaquetransparent
决定 b64_json 解码后的格式
可选值pngjpegwebpsvggif
仅 jpeg / webp;只在同步 generations JSON 与 multipart 编辑中保留
范围0–100默认100
不会关闭内容安全检查
可选值autolow
终端用户识别字符串,不是 HopBase 账户 ID,也不改变计费归属
传什么都以 b64_json 返回,不能靠 url 取得下载链接,请省略
限制传什么都以 b64_json 返回,请省略
true 改为 HopBase Images SSE(期间发送 keepalive,最后一个 data: 事件才是 Images JSON,以 [DONE] 结束),不是 OpenAI 原生逐张预览事件;SDK 请保持 false
限制true 返回 HopBase Images SSE,SDK 请保持 false默认false
兼容字段;GPT Image 2 默认高保真处理参考图,请省略
可选值lowhigh
出图前的规划强度,不单独收费;其他取值网关返回 400
可选值lowmediumhigh
默认"high"
仅 output_format=gif:动图帧数。gif 的 size 是单帧尺寸,所有帧拼在一张边长不超过 3840 的图上,请用 auto 或 512x512 这类小尺寸
范围2–16默认9
仅 output_format=gif:每帧时长(毫秒)
范围20–2000默认200
multipart 文件(image / image[]),或 JSON 的 HTTP(S) URL / Data URL 字符串、字符串数组。不读 images,不接受裸 base64 或 file_id;转发前可能压缩
限制1–16 张(官方上限);远程 URL 单张 ≤ 26214400 字节且须返回 image/*。只读 image,不读 images
透明区域表示要编辑;网关会把 mask 缩放到第一张参考图的尺寸;不保证遮罩外逐像素不变
限制带 alpha 通道的 PNG;透明区域表示要编辑
仅 GPT Image 2.6:画了圈、箭头或批注的透明 PNG 叠加层,与第一张输入图同尺寸;模型按标注修改,不能与 mask 同用
- transparent 需要 png 或 webp
- output_compression 只对 jpeg / webp 生效
- output_format=svg 时 n 只能为 1
- markup 不能与 mask 同用
先确认当前密钥的 GET /v1/models 包含此 ID
生成或编辑指令;为空返回 400 prompt must not be empty。网关不限长度,上限为官方上限
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度1–32000 字符
例:1024x1024、2048x2048、3840x2160。不合规在生成前返回 400、不计费;不接受 1K / 2K / 4K
限制auto 或 宽x高:边长为 16 的倍数、单边 ≤ 3840、长短边比 ≤ 3:1、总像素 655360–8294400
档位越高输出 token 越多、费用越高:1024x1024 实测 low 约 200、high 约 1,760、xhigh 约 3,120、max 约 7,020 输出 token
可选值autolowmediumhighxhighmax
限制网关不校验、原样转发;档位越高输出 token 越多
部分分组只支持 1,传更大值返回 400;≤ 0 按 1 处理
范围1–10默认1
transparent 需配合 png 或 webp;2.0 透明背景属预览能力
可选值autoopaquetransparent
决定 b64_json 解码后的格式
可选值pngjpegwebpsvggif
仅 jpeg / webp;只在同步 generations JSON 与 multipart 编辑中保留
范围0–100默认100
不会关闭内容安全检查
可选值autolow
终端用户识别字符串,不是 HopBase 账户 ID,也不改变计费归属
传什么都以 b64_json 返回,不能靠 url 取得下载链接,请省略
限制传什么都以 b64_json 返回,请省略
true 改为 HopBase Images SSE(期间发送 keepalive,最后一个 data: 事件才是 Images JSON,以 [DONE] 结束),不是 OpenAI 原生逐张预览事件;SDK 请保持 false
限制true 返回 HopBase Images SSE,SDK 请保持 false默认false
兼容字段;GPT Image 2 默认高保真处理参考图,请省略
可选值lowhigh
出图前的规划强度,不单独收费;其他取值网关返回 400
可选值lowmediumhigh
默认"high"
仅 output_format=gif:动图帧数。gif 的 size 是单帧尺寸,所有帧拼在一张边长不超过 3840 的图上,请用 auto 或 512x512 这类小尺寸
范围2–16默认9
仅 output_format=gif:每帧时长(毫秒)
范围20–2000默认200
multipart 文件(image / image[]),或 JSON 的 HTTP(S) URL / Data URL 字符串、字符串数组。不读 images,不接受裸 base64 或 file_id;转发前可能压缩
限制1–16 张(官方上限);远程 URL 单张 ≤ 26214400 字节且须返回 image/*。只读 image,不读 images
透明区域表示要编辑;网关会把 mask 缩放到第一张参考图的尺寸;不保证遮罩外逐像素不变
限制带 alpha 通道的 PNG;透明区域表示要编辑
仅 GPT Image 2.6:画了圈、箭头或批注的透明 PNG 叠加层,与第一张输入图同尺寸;模型按标注修改,不能与 mask 同用
- transparent 需要 png 或 webp
- output_compression 只对 jpeg / webp 生效
- output_format=svg 时 n 只能为 1
- markup 不能与 mask 同用
以当前密钥 GET /v1/models 的返回为准
模型拒答或只回文字时返回 400(消息引用该段文字)或 502:请改写提示词
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度≥ 1 字符
并行生成。全有或全无:任一张失败则整个请求失败、不计费
限制按输出档位封顶:1K ≤ 10,2K ≤ 5范围1–10默认1
顶层扁平写法,等价于 google.image_config.image_size;覆盖 size 推导的档位
可选值1K2K
默认"1K"
顶层扁平写法,等价于 google.image_config.aspect_ratio,优先于 size
可选值1:12:33:23:44:34:55:49:1616:921:9
默认"1:1"
宽x高 从不因比例被拒:映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位。显式写出超过型号档位的 1K / 2K / 4K 返回 400;同时传 image_size 时以它为准
可选值1K2K
限制auto、任意比例的 宽x高(映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位),或型号档位
SDK 可写成 extra_body.google.image_config;三种写法等价
可选值1:12:33:23:44:34:55:49:1616:921:9
可选值1K2K
参考图,放在 generations 请求体即可;同时传时以 images 为准。「Gemini 官方直连(企业级)」单张解码后 ≤ 20 MiB,没有 /v1/images/edits
限制参考图:字符串或字符串数组,最多 14 张
同 image,同时传时以 images 为准
限制参考图:字符串或字符串数组,最多 14 张
不支持:传 mask 返回 400;局部修改请在 prompt 中描述区域
不支持 transparent(返回 400)
不能为"transparent"
不支持,请省略或传 false
不能为true
- 2K 输出每次最多 5 张(响应体积上限)
以当前密钥 GET /v1/models 的返回为准
模型拒答或只回文字时返回 400(消息引用该段文字)或 502:请改写提示词
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度≥ 1 字符
并行生成。全有或全无:任一张失败则整个请求失败、不计费
限制按输出档位封顶:1K ≤ 10,2K ≤ 5范围1–10默认1
顶层扁平写法,等价于 google.image_config.image_size;覆盖 size 推导的档位
可选值1K2K
默认"1K"
顶层扁平写法,等价于 google.image_config.aspect_ratio,优先于 size
可选值1:12:33:23:44:34:55:49:1616:921:9
默认"1:1"
宽x高 从不因比例被拒:映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位。显式写出超过型号档位的 1K / 2K / 4K 返回 400;同时传 image_size 时以它为准
可选值1K2K
限制auto、任意比例的 宽x高(映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位),或型号档位
SDK 可写成 extra_body.google.image_config;三种写法等价
可选值1:12:33:23:44:34:55:49:1616:921:9
可选值1K2K
参考图,放在 generations 请求体即可;同时传时以 images 为准。「Gemini 官方直连(企业级)」单张解码后 ≤ 20 MiB,没有 /v1/images/edits
限制参考图:字符串或字符串数组,最多 14 张
同 image,同时传时以 images 为准
限制参考图:字符串或字符串数组,最多 14 张
不支持:传 mask 返回 400;局部修改请在 prompt 中描述区域
不支持 transparent(返回 400)
不能为"transparent"
不支持,请省略或传 false
不能为true
- 2K 输出每次最多 5 张(响应体积上限)
以当前密钥 GET /v1/models 的返回为准
模型拒答或只回文字时返回 400(消息引用该段文字)或 502:请改写提示词
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度≥ 1 字符
并行生成。全有或全无:任一张失败则整个请求失败、不计费
限制按输出档位封顶:1K ≤ 10,2K ≤ 5,4K ≤ 2范围1–10默认1
顶层扁平写法,等价于 google.image_config.image_size;覆盖 size 推导的档位
可选值1K2K4K
默认"1K"
顶层扁平写法,等价于 google.image_config.aspect_ratio,优先于 size
可选值1:12:33:23:44:34:55:49:1616:921:9
默认"1:1"
宽x高 从不因比例被拒:映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位。显式写出超过型号档位的 1K / 2K / 4K 返回 400;同时传 image_size 时以它为准
可选值1K2K4K
限制auto、任意比例的 宽x高(映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位),或型号档位
SDK 可写成 extra_body.google.image_config;三种写法等价
可选值1:12:33:23:44:34:55:49:1616:921:9
可选值1K2K4K
参考图,放在 generations 请求体即可;同时传时以 images 为准。「Gemini 官方直连(企业级)」单张解码后 ≤ 20 MiB,没有 /v1/images/edits
限制参考图:字符串或字符串数组,最多 14 张
同 image,同时传时以 images 为准
限制参考图:字符串或字符串数组,最多 14 张
不支持:传 mask 返回 400;局部修改请在 prompt 中描述区域
不支持 transparent(返回 400)
不能为"transparent"
不支持,请省略或传 false
不能为true
- 2K 输出每次最多 5 张(响应体积上限)
- 4K 输出每次最多 2 张(响应体积上限)
以当前密钥 GET /v1/models 的返回为准
模型拒答或只回文字时返回 400(消息引用该段文字)或 502:请改写提示词
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度≥ 1 字符
并行生成。全有或全无:任一张失败则整个请求失败、不计费
限制按输出档位封顶:1K ≤ 10,2K ≤ 5,4K ≤ 2范围1–10默认1
顶层扁平写法,等价于 google.image_config.image_size;覆盖 size 推导的档位
可选值1K2K4K
默认"1K"
顶层扁平写法,等价于 google.image_config.aspect_ratio,优先于 size
可选值1:12:33:23:44:34:55:49:1616:921:9
默认"1:1"
宽x高 从不因比例被拒:映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位。显式写出超过型号档位的 1K / 2K / 4K 返回 400;同时传 image_size 时以它为准
可选值1K2K4K
限制auto、任意比例的 宽x高(映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位),或型号档位
SDK 可写成 extra_body.google.image_config;三种写法等价
可选值1:12:33:23:44:34:55:49:1616:921:9
可选值1K2K4K
参考图,放在 generations 请求体即可;同时传时以 images 为准。「Gemini 官方直连(企业级)」单张解码后 ≤ 20 MiB,没有 /v1/images/edits
限制参考图:字符串或字符串数组,最多 14 张
同 image,同时传时以 images 为准
限制参考图:字符串或字符串数组,最多 14 张
不支持:传 mask 返回 400;局部修改请在 prompt 中描述区域
不支持 transparent(返回 400)
不能为"transparent"
不支持,请省略或传 false
不能为true
- 2K 输出每次最多 5 张(响应体积上限)
- 4K 输出每次最多 2 张(响应体积上限)
以当前密钥 GET /v1/models 的返回为准
模型拒答或只回文字时返回 400(消息引用该段文字)或 502:请改写提示词
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度≥ 1 字符
并行生成。全有或全无:任一张失败则整个请求失败、不计费
限制按输出档位封顶:1K ≤ 10范围1–10默认1
顶层扁平写法,等价于 google.image_config.image_size;覆盖 size 推导的档位
可选值1K
默认"1K"
顶层扁平写法,等价于 google.image_config.aspect_ratio,优先于 size
可选值1:12:33:23:44:34:55:49:1616:921:9
默认"1:1"
宽x高 从不因比例被拒:映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位。显式写出超过型号档位的 1K / 2K / 4K 返回 400;同时传 image_size 时以它为准
可选值1K
限制auto、任意比例的 宽x高(映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位),或型号档位
SDK 可写成 extra_body.google.image_config;三种写法等价
可选值1:12:33:23:44:34:55:49:1616:921:9
可选值1K
参考图,放在 generations 请求体即可;同时传时以 images 为准。「Gemini 官方直连(企业级)」单张解码后 ≤ 20 MiB,没有 /v1/images/edits
限制参考图:字符串或字符串数组,最多 14 张
同 image,同时传时以 images 为准
限制参考图:字符串或字符串数组,最多 14 张
不支持:传 mask 返回 400;局部修改请在 prompt 中描述区域
不支持 transparent(返回 400)
不能为"transparent"
不支持,请省略或传 false
不能为true
以当前密钥 GET /v1/models 的返回为准
模型拒答或只回文字时返回 400(消息引用该段文字)或 502:请改写提示词
限制去除首尾空白后不能为空,否则 400「prompt must not be empty」长度≥ 1 字符
并行生成。全有或全无:任一张失败则整个请求失败、不计费
限制按输出档位封顶:1K ≤ 10范围1–10默认1
顶层扁平写法,等价于 google.image_config.image_size;覆盖 size 推导的档位
可选值1K
默认"1K"
顶层扁平写法,等价于 google.image_config.aspect_ratio,优先于 size
可选值1:12:33:23:44:34:55:49:1616:921:9
默认"1:1"
宽x高 从不因比例被拒:映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位。显式写出超过型号档位的 1K / 2K / 4K 返回 400;同时传 image_size 时以它为准
可选值1K
限制auto、任意比例的 宽x高(映射到最接近的官方比例,档位按长边推导并静默降到型号最高档位),或型号档位
SDK 可写成 extra_body.google.image_config;三种写法等价
可选值1:12:33:23:44:34:55:49:1616:921:9
可选值1K
参考图,放在 generations 请求体即可;同时传时以 images 为准。「Gemini 官方直连(企业级)」单张解码后 ≤ 20 MiB,没有 /v1/images/edits
限制参考图:字符串或字符串数组,最多 3 张
同 image,同时传时以 images 为准
限制参考图:字符串或字符串数组,最多 3 张
不支持:传 mask 返回 400;局部修改请在 prompt 中描述区域
不支持 transparent(返回 400)
不能为"transparent"
不支持,请省略或传 false
不能为true
使用当前密钥 GET /v1/models 返回的完整 ID
图片内容、构图、风格或编辑指令;局部编辑可描述坐标、bbox、箭头或参考图中的涂画区域
限制去除首尾空白后不能为空,否则 400「missing prompt」长度≥ 1 字符
不合规在生成前返回 400 并提示合法区间、不计费
可选值1K1.5K2K
限制简写 1K / 1.5K / 2K,或 宽x高:总像素 921600–4624220,宽高比 1:16–16:1
其他值(含 null)返回 400
限制only a single output is supported (n=1)默认1
url 返回 24 小时有效的签名直链;b64_json 返回 data[].b64_json。非流式组图不能用 b64_json(须 stream: true)
可选值urlb64_json
默认"url"
4.5 仅 jpeg
可选值pngjpeg
必须是对象
可选值standard
传入后触发单图 / 多图图生图或编辑;/v1/images/edits 必须至少 1 张。URL 在提交时不下载、不检查大小
限制参考图(传入即图生图 / 编辑):最多 10 张;Data URL 单张 ≤ 31457280 字节;URL 提交时不下载
仅 seedream-5-0-pro:true 把 1 张 PNG / JPEG 输入图拆成底图 + 至多 16 个透明 PNG 图层;此时 prompt 可省略、size 只认 1K / 1.5K / 2K / auto(缺省 auto)。1K 约需 1.5 分钟,客户端超时请设 ≥ 5 分钟。详见 Seedream · 图层拆分
限制不支持图层拆分:传 true 返回 400「model seedream-5-5 does not support layer_decomposition」不能为true
本站默认 false(官方默认 true),传 true 才加水印
限制本站默认 false(官方默认 true);传 true 才加水印默认false
仅 seedream-5-5 / seedream-5-0-pro:transparent 只用于图生图,须恰好 1 张带透明通道的输入图(JPEG / BMP Data URL 返回 400),输出 PNG,不可配 output_format: jpeg。详见 Seedream · 透明背景
可选值opaquetransparent
默认"opaque"
仅 seedream-5-0-lite / seedream-4-5:auto 开组图,模型按 prompt 决定出几张(不超过 max_images);单张失败放在 data[].error、不计费,全部失败返回 400。非流式组图服务端最多等约 280 秒,建议配 stream: true。详见 Seedream · 组图
max_images 为 1–15 的整数,参考图数 + max_images ≤ 15;multipart 写 sequential_image_generation_options[max_images] 或 max_images
仅 seedream-5-0-lite / seedream-4-5:true 返回 SSE,逐张推 image_generation.partial_succeeded / image_generation.partial_failed,最后 image_generation.completed 与 data: [DONE];按成功张数计费,流式响应不带本次扣费字段。详见 Seedream · 流式
限制不支持:传 true 返回 400「model seedream-5-5 does not support stream」不能为true
联网搜索暂不支持,传入返回 400
不支持:/v1/images/edits 带 mask 即返回 400(null 也一样)
- background transparent:恰好 1 张带透明通道的输入图,输出 png
使用当前密钥 GET /v1/models 返回的完整 ID
图片内容、构图、风格或编辑指令;局部编辑可描述坐标、bbox、箭头或参考图中的涂画区域
限制去除首尾空白后不能为空,否则 400「missing prompt」;layer_decomposition: true 时可省略长度≥ 1 字符
不合规在生成前返回 400 并提示合法区间、不计费
可选值1K1.5K2K
限制简写 1K / 1.5K / 2K,或 宽x高:总像素 921600–4624220,宽高比 1:16–16:1;图层拆分只认 1K / 1.5K / 2K / auto(缺省 auto)
其他值(含 null)返回 400
限制only a single output is supported (n=1)默认1
url 返回 24 小时有效的签名直链;b64_json 返回 data[].b64_json。非流式组图不能用 b64_json(须 stream: true)
可选值urlb64_json
默认"url"
4.5 仅 jpeg
可选值pngjpeg
必须是对象
可选值standardfast
传入后触发单图 / 多图图生图或编辑;/v1/images/edits 必须至少 1 张。URL 在提交时不下载、不检查大小
限制参考图(传入即图生图 / 编辑):最多 10 张;Data URL 单张 ≤ 31457280 字节;URL 提交时不下载
仅 seedream-5-0-pro:true 把 1 张 PNG / JPEG 输入图拆成底图 + 至多 16 个透明 PNG 图层;此时 prompt 可省略、size 只认 1K / 1.5K / 2K / auto(缺省 auto)。1K 约需 1.5 分钟,客户端超时请设 ≥ 5 分钟。详见 Seedream · 图层拆分
限制图层拆分:把 1 张输入图拆成底图 + 至多 16 个透明 PNG 图层默认false
本站默认 false(官方默认 true),传 true 才加水印
限制本站默认 false(官方默认 true);传 true 才加水印默认false
仅 seedream-5-5 / seedream-5-0-pro:transparent 只用于图生图,须恰好 1 张带透明通道的输入图(JPEG / BMP Data URL 返回 400),输出 PNG,不可配 output_format: jpeg。详见 Seedream · 透明背景
可选值opaquetransparent
默认"opaque"
仅 seedream-5-0-lite / seedream-4-5:auto 开组图,模型按 prompt 决定出几张(不超过 max_images);单张失败放在 data[].error、不计费,全部失败返回 400。非流式组图服务端最多等约 280 秒,建议配 stream: true。详见 Seedream · 组图
max_images 为 1–15 的整数,参考图数 + max_images ≤ 15;multipart 写 sequential_image_generation_options[max_images] 或 max_images
仅 seedream-5-0-lite / seedream-4-5:true 返回 SSE,逐张推 image_generation.partial_succeeded / image_generation.partial_failed,最后 image_generation.completed 与 data: [DONE];按成功张数计费,流式响应不带本次扣费字段。详见 Seedream · 流式
限制不支持:传 true 返回 400「model seedream-5-0-pro does not support stream」不能为true
联网搜索暂不支持,传入返回 400
不支持:/v1/images/edits 带 mask 即返回 400(null 也一样)
- 图层拆分:prompt 可省略、size 只认档位(缺省 auto)、恰好 1 张 PNG / JPEG 输入图
- background transparent:恰好 1 张带透明通道的输入图,输出 png
使用当前密钥 GET /v1/models 返回的完整 ID
图片内容、构图、风格或编辑指令;局部编辑可描述坐标、bbox、箭头或参考图中的涂画区域
限制去除首尾空白后不能为空,否则 400「missing prompt」长度≥ 1 字符
不合规在生成前返回 400 并提示合法区间、不计费
可选值2K3K4K
限制简写 2K / 3K / 4K,或 宽x高:总像素 3686400–16777216,宽高比 1:16–16:1
其他值(含 null)返回 400
限制only a single output is supported (n=1)默认1
url 返回 24 小时有效的签名直链;b64_json 返回 data[].b64_json。非流式组图不能用 b64_json(须 stream: true)
可选值urlb64_json
默认"url"
4.5 仅 jpeg
可选值pngjpeg
必须是对象
可选值standard
传入后触发单图 / 多图图生图或编辑;/v1/images/edits 必须至少 1 张。URL 在提交时不下载、不检查大小
限制参考图(传入即图生图 / 编辑):最多 14 张;Data URL 单张 ≤ 31457280 字节;URL 提交时不下载
仅 seedream-5-0-pro:true 把 1 张 PNG / JPEG 输入图拆成底图 + 至多 16 个透明 PNG 图层;此时 prompt 可省略、size 只认 1K / 1.5K / 2K / auto(缺省 auto)。1K 约需 1.5 分钟,客户端超时请设 ≥ 5 分钟。详见 Seedream · 图层拆分
限制不支持图层拆分:传 true 返回 400「model seedream-5-0-lite does not support layer_decomposition」不能为true
本站默认 false(官方默认 true),传 true 才加水印
限制本站默认 false(官方默认 true);传 true 才加水印默认false
仅 seedream-5-5 / seedream-5-0-pro:transparent 只用于图生图,须恰好 1 张带透明通道的输入图(JPEG / BMP Data URL 返回 400),输出 PNG,不可配 output_format: jpeg。详见 Seedream · 透明背景
仅 seedream-5-0-lite / seedream-4-5:auto 开组图,模型按 prompt 决定出几张(不超过 max_images);单张失败放在 data[].error、不计费,全部失败返回 400。非流式组图服务端最多等约 280 秒,建议配 stream: true。详见 Seedream · 组图
可选值autodisabled
限制auto 组图:模型按 prompt 决定出几张(不超过 max_images)默认"disabled"
max_images 为 1–15 的整数,参考图数 + max_images ≤ 15;multipart 写 sequential_image_generation_options[max_images] 或 max_images
组图最多张数;参考图数 + max_images ≤ 15
范围1–15
仅 seedream-5-0-lite / seedream-4-5:true 返回 SSE,逐张推 image_generation.partial_succeeded / image_generation.partial_failed,最后 image_generation.completed 与 data: [DONE];按成功张数计费,流式响应不带本次扣费字段。详见 Seedream · 流式
默认false
联网搜索暂不支持,传入返回 400
不支持:/v1/images/edits 带 mask 即返回 400(null 也一样)
- 非流式组图不能配 b64_json(要求 stream=true)
使用当前密钥 GET /v1/models 返回的完整 ID
图片内容、构图、风格或编辑指令;局部编辑可描述坐标、bbox、箭头或参考图中的涂画区域
限制去除首尾空白后不能为空,否则 400「missing prompt」长度≥ 1 字符
不合规在生成前返回 400 并提示合法区间、不计费
可选值2K4K
限制简写 2K / 4K,或 宽x高:总像素 3686400–16777216,宽高比 1:16–16:1
其他值(含 null)返回 400
限制only a single output is supported (n=1)默认1
url 返回 24 小时有效的签名直链;b64_json 返回 data[].b64_json。非流式组图不能用 b64_json(须 stream: true)
可选值urlb64_json
默认"url"
4.5 仅 jpeg
可选值jpeg
必须是对象
可选值standard
传入后触发单图 / 多图图生图或编辑;/v1/images/edits 必须至少 1 张。URL 在提交时不下载、不检查大小
限制参考图(传入即图生图 / 编辑):最多 14 张;Data URL 单张 ≤ 31457280 字节;URL 提交时不下载
仅 seedream-5-0-pro:true 把 1 张 PNG / JPEG 输入图拆成底图 + 至多 16 个透明 PNG 图层;此时 prompt 可省略、size 只认 1K / 1.5K / 2K / auto(缺省 auto)。1K 约需 1.5 分钟,客户端超时请设 ≥ 5 分钟。详见 Seedream · 图层拆分
限制不支持图层拆分:传 true 返回 400「model seedream-4-5 does not support layer_decomposition」不能为true
本站默认 false(官方默认 true),传 true 才加水印
限制本站默认 false(官方默认 true);传 true 才加水印默认false
仅 seedream-5-5 / seedream-5-0-pro:transparent 只用于图生图,须恰好 1 张带透明通道的输入图(JPEG / BMP Data URL 返回 400),输出 PNG,不可配 output_format: jpeg。详见 Seedream · 透明背景
仅 seedream-5-0-lite / seedream-4-5:auto 开组图,模型按 prompt 决定出几张(不超过 max_images);单张失败放在 data[].error、不计费,全部失败返回 400。非流式组图服务端最多等约 280 秒,建议配 stream: true。详见 Seedream · 组图
可选值autodisabled
限制auto 组图:模型按 prompt 决定出几张(不超过 max_images)默认"disabled"
max_images 为 1–15 的整数,参考图数 + max_images ≤ 15;multipart 写 sequential_image_generation_options[max_images] 或 max_images
组图最多张数;参考图数 + max_images ≤ 15
范围1–15
仅 seedream-5-0-lite / seedream-4-5:true 返回 SSE,逐张推 image_generation.partial_succeeded / image_generation.partial_failed,最后 image_generation.completed 与 data: [DONE];按成功张数计费,流式响应不带本次扣费字段。详见 Seedream · 流式
默认false
联网搜索暂不支持,传入返回 400
不支持:/v1/images/edits 带 mask 即返回 400(null 也一样)
- 非流式组图不能配 b64_json(要求 stream=true)
返回
200同步成功
202带 Prefer: respond-async 时
响应头
本次请求扣费的人民币金额(与 X-HopBase-Cost-USD 为同一笔扣费),最多 6 位小数,如 0.0816。只在本次产生扣费时返回;流式(SSE)不返回;生图耗时约 40 秒以上时响应头已提前发出,以响应体 usage.cost 为准
本次请求实际从余额扣除的美元金额,与使用记录里这一条相同,最多 8 位小数,如 0.012;只随 X-HopBase-Cost 一起返回
X-HopBase-Cost 的币种,恒为 CNY
Unix 秒
每张图一项
GPT Image / Gemini:Base64 图片数据,解码后按 output_format 保存;Gemini 可能是 JPEG,请看 mime_type。Seedream 传 response_format: b64_json 时也返回此字段
Seedream:24 小时有效的签名直链,过期只能重新生成
Seedream 组图:这一张生成失败(多为内容审核),不计费
错误码
失败原因
Seedream:实际输出 宽x高
Seedream 图层拆分:底图按请求的 output_format,图层恒为 png
Seedream 图层拆分:底图为 0,图层从 1 起,按升序叠放
Seedream 图层拆分(仅图层):图层在底图中的位置
[left, top, right, bottom],底图像素坐标
同一位置的归一化坐标,0–999
Seedream 图层拆分(仅图层):图层名
Seedream 图层拆分(仅图层):图层内容描述
图片 MIME
模型改写后的提示词(部分模型)
可能返回
输入 Token
输出 Token
合计
Grok Imagine:xAI 官方计量,单位是 1e-10 美元,按官方价折算,不是本次扣费;本次实际从余额扣除的美元金额看 cost_usd,cost 为同一笔扣费的人民币金额
网关附加:本次扣费的人民币金额(与 cost_usd 为同一笔扣费),与响应头 X-HopBase-Cost 相同;流式不返回
网关附加:本次实际从余额扣除的美元金额,与响应头 X-HopBase-Cost-USD 及使用记录相同;流式不返回
网关附加:cost 的币种,恒为 CNY
错误
missing_api_key / invalid_api_key / api_key_expired)insufficient_quota)model_not_found),或路径不属于该分组(route_not_found)request_too_large)user_concurrency_limit / apikey_concurrency_limit),带 Retry-After