图像
images/generations 字段与响应、n 的真实语义、b64_json、尺寸与档位,以及厂商原生出图路径。
内容最后核对:2026-11-18
本页目录
POST /v1/images/generations
| 字段 | 说明 |
|---|---|
model | 必填 |
prompt | 必填 |
n | 张数。只用于预扣估算,计费按实际返回张数 |
size | 1024x1024 或 1K / 2K / 4K 档位,原样透传给上游 |
response_format | url(默认)或 b64_json,也认 camelCase |
quality / style | 按模型而定,认就透传,不认就忽略 |
响应:
{"created": 1763000000,
"data": [{"url": "...", "reachable": true, "expires_at": "...", "revised_prompt": "..."}],
"usage": {"billed_count": 1, "requested_count": 1, "cost_quota": 120,
"unit": "per_image", "size_tier": "1K"}}
reachable是网关在返回前做的一次可达性探测。false表示上游给的链接当时拉不到(通常是签名或区域问题),不是你写错了请求。expires_at是上游链接的有效期。网关不保存图片,拿到就下载。usage.shortfall只在「要的比给的多」时出现,写明差额。
关于 n
n 只影响预扣。上游实际返回几张就按几张计费:
- 要 2 张只回 1 张 → 按 1 张收,
usage.shortfall写明; - 要 1 张回了 2 张(少见)→ 按 2 张收。价格是「每张」的,不是「每次」的。
要严格控成本就一次要一张、由你并发发起。
b64_json
response_format: "b64_json" 在图片端点支持:data[].b64_json 是 base64 字符串。
视频端点不支持它(明确 400):产物可能几百 MB,塞进 JSON 后响应体会过大甚至直接失败。
尺寸与档位
size 同时是上游参数与计价档位:
| 写法 | 结果 |
|---|---|
1K / 2K / 4K | 精确档位,计价明确 |
1024x1024 | 若能对上某个档位就用它,否则按模型默认档 |
1792x1024 | 非标准尺寸:透传给上游,但计价走默认档(猜成 1080p 或 720p 都会错) |
定价页会显示「这个尺寸没有精确档位」。要精确成本就写标准档位。
厂商原生出图路径
base 配成 <网关地址>/v1 时,厂商 SDK 自己追加的路径也认:
| 厂商 | 路径 | 形状 |
|---|---|---|
| 阿里百炼(Qwen-Image) | POST /api/v1/services/aigc/multimodal-generation/generation | DashScope 三段式(input / parameters) |
目前只有它提供原生出图路径。方舟的图片走 OpenAI 形状的 /v1/images/generations ——
它的原生命名空间 /api/v3 只用于视频任务(见视频 API)。
请求体按厂商形状写,不用套 OpenAI 的 prompt / size。用官方 SDK 时这一层由 SDK 拼,我们照它的形状解析。
常见错误
| 现象 | code | 原因 |
|---|---|---|
| 400 | image.tier_unsupported | 该模型没有请求的档位 |
| 400 | model.modality_not_supported | 拿文本模型打图片端点 |
| 402 | quota.insufficient | 余额不足(预扣就失败) |
| 502 | upstream.error | 上游拒绝(内容审核、提示词违规也走这里) |
内容审核拒绝通常是上游返回的 4xx 被折成 502 upstream.error 或 400 upstream.bad_request,具体看 message —— 网关不替你改写审核结论。