图像生成
接口说明
POST /v1/images/generations 通用协议
接口地址
POST /v1/images/generations
POST /v1/images/edits均为同步接口:请求发起后阻塞等待上游返回图像,响应体里直接包含图片数据,不走异步任务查询。/v1/images/edits 是图像编辑专用端点(目前用于 Qwen-Image 系列的 edit 模型),两个端点的鉴权、计费、错误规则完全一致。
接口路径与调用方式对齐 OpenAI 官方 Images 接口,但请求体、响应体的具体格式取决于所选模型。文档未列出的参数原样透传给上游,是否生效取决于所选模型的上游实现。
模型系列
各系列的请求风格、专属参数与完整示例见对应系列页:
| 系列 | 请求风格 | 当前模型 |
|---|---|---|
| Seedream 系列 | OpenAI 风格(扩展参数) | Doubao-Seedream-5.0-lite、Doubao-seedream-4.5、Doubao-seedream-4.0 |
| Qwen-Image 系列 | DashScope 多模态协议 | qwen-image-2.0-pro、qwen-image-edit-max、qwen-image-edit-plus、qwen-image-edit |
| Wan 图像系列 | DashScope 多模态协议(仅图像编辑) | wan2.6-image |
| GPT-Image 系列 | OpenAI 官方协议 | gpt-image-2、gpt-image-1.5、gpt-image-1 |
| Gemini 系列 | OpenAI 风格(特殊限制) | gemini-2.5-flash-image |
平台处理的字段
| 字段 | 类型 | 必填 | 默认 | 平台行为 |
|---|---|---|---|---|
model | string | 是 | — | 校验链与 Chat 一致:缺失或为空 → 400 invalid_request;不在该 key 的模型白名单内 → 403 model_not_allowed;平台没有该模型 → 404 model_not_found |
prompt | string | 视模型而定 | — | gemini 系列模型必填(见 Gemini 系列),缺失 → 400 invalid_request;其余模型不做校验,原样透传给上游 |
n | integer | 否 | 1 | gemini 系列模型仅支持 1,传大于 1 的值 → 400 invalid_request;其余模型透传给上游,实际计费按响应中的图片张数 |
size | string | 否 | 上游默认 | 影响计费档位(见下文"计费");gemini 系列模型不向上游转发该值 |
请求体存在双协议,按你选择的模型区分:
- OpenAI 风格(Seedream、GPT-Image、Gemini 系列):
prompt/n/size直接放在请求体顶层。 - DashScope 多模态协议(Qwen-Image 系列):提示词放在
input.messages结构里,n/size等生成参数嵌套在parameters对象里,没有顶层prompt,详见 Qwen-Image 系列。 - 平台读取
n/size(用于计费)的规则与之对应:请求体中只要出现parameters键,平台就只从parameters内读取,顶层的n/size会被整体忽略(不做字段级回退)。
响应格式
平台默认不改写响应体,上游返回什么就原样转发给你(状态码 200):
- 走 OpenAI 兼容协议的上游返回标准 OpenAI Images 格式:
{"created": ..., "data": [{"url": "..."}]}或{"created": ..., "data": [{"b64_json": "..."}]},取决于该上游本身的实现。 - 走 DashScope 协议的上游返回 DashScope 原生响应结构(
output.choices[].message.content[].image等),不是 OpenAI 格式,需按对应模型的原生响应格式解析。 - gemini 系列模型的部分线路会把上游原生响应统一合成为 OpenAI 格式(仅
b64_json),详见 Gemini 系列。
计费
图像生成按张计费,单价按 size 对应的档位取值(未命中该 size 档位时按模型默认档位计价),各模型价格见模型列表。实际扣费按响应中平台能识别出的图片张数结算;若响应结构无法识别出张数,按请求时的预扣张数结算(不退不补)。
错误
| 状态码 | code | 触发场景 |
|---|---|---|
| 402 | insufficient_credits | 账户余额不足以覆盖预扣费用 |
| 403 | model_not_allowed | 请求的 model 不在该 API Key 的模型白名单内 |
| 404 | model_not_found | 平台没有该模型 |
| 502 | upstream_error | 上游返回错误、重试耗尽,或(gemini 系列模型)上游本次没有返回图片;该次调用不扣费 |
| 503 | no_available_channel | 该模型当前没有可用渠道 |
完整错误响应体格式与更多错误码见错误码。