文档目录

图像

images/generations 字段与响应、n 的真实语义、b64_json、尺寸与档位,以及厂商原生出图路径。

内容最后核对:2026-11-18

本页目录

POST /v1/images/generations

字段说明
model必填
prompt必填
n张数。只用于预扣估算,计费按实际返回张数
size1024x1024 或 1K / 2K / 4K 档位,原样透传给上游
response_formaturl(默认)或 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/generationDashScope 三段式(input / parameters)

目前只有它提供原生出图路径。方舟的图片走 OpenAI 形状的 /v1/images/generations —— 它的原生命名空间 /api/v3 只用于视频任务(见视频 API)。

请求体按厂商形状写,不用套 OpenAI 的 prompt / size。用官方 SDK 时这一层由 SDK 拼,我们照它的形状解析。

常见错误

现象code原因
400image.tier_unsupported该模型没有请求的档位
400model.modality_not_supported拿文本模型打图片端点
402quota.insufficient余额不足(预扣就失败)
502upstream.error上游拒绝(内容审核、提示词违规也走这里)

内容审核拒绝通常是上游返回的 4xx 被折成 502 upstream.error 或 400 upstream.bad_request,具体看 message —— 网关不替你改写审核结论。