模型路由 图片生成模型

一、概述

POST /v1/images/generations — 创建图片生成任务GET /v1/images/generations/{task_id} — 查询单个任务GET /v1/images/generations — 查询任务列表

二、前提条件

1. 建议提前阅读使用约束与支持的模型提供商了解相关信息。

2. 已创建模型路由实例，详细操作指导请参见创建模型路由实例。

3. 已创建 BYOK 实例，详细操作指导请参见创建 BYOK 实例。

4. 已创建模型路由访问密钥（API Key），详细操作指导请参见创建模型路由访问密钥。

5. 已完成图片生成模型关联和模型路由策略配置，详细操作指导请参见配置模型调度管理。

四、请求地址

POST {CMR_BASE_URL}/v1/images/generationsGET {CMR_BASE_URL}/v1/images/generations/{task_id}GET {CMR_BASE_URL}/v1/images/generations

CMR_BASE_URL 为控制台展示的实例访问地址。请求使用 CMR 模型名称和 CMR API Key，无需填写厂商的接口地址或 API Key。

五、请求头

Header	必填	说明
Authorization	是	Bearer <CMR_API_KEY>
Content-Type	是	提交时固定为 application/json
X-User-Id	否	终端用户标识，交给支持滥用追踪的模型。不能写在请求体里
Idempotency-Key	否	交给支持幂等键的模型。CMR 不据此去重，再次提交会得到新任务

六、快速开始

将示例中的访问地址、API Key 和模型名称替换为自己的配置。

七、cURL

# ① 创建任务（窗口内完成时响应已含 result）curl –request POST "${CMR_BASE_URL}/v1/images/generations" \\ –header "Authorization: Bearer ${CMR_API_KEY}" \\ –header "Content-Type: application/json" \\ –data '{ "model": "cmr-image", "contents": [ { "type": "text", "text": "一只戴墨镜的柴犬坐在冲浪板上，写实风格" } ], "size": "1536×1024" }'# → {"id":"imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B","status":"in_progress","error":null}# ② 轮询任务状态，直到 status 为 completed、failed 或 expiredcurl –request GET "${CMR_BASE_URL}/v1/images/generations/imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B" \\ –header "Authorization: Bearer ${CMR_API_KEY}"# ③ status=completed 后，从 result.data[0].url 或 result.data[0].b64_json 取图

八、Python

import osimport timeimport requestsbase_url = os.environ["CMR_BASE_URL"]headers = { "Authorization": f"Bearer {os.environ['CMR_API_KEY']}", "Content-Type": "application/json",}# ① 创建任务resp = requests.post( f"{base_url}/v1/images/generations", headers=headers, json={ "model": "cmr-image", "contents": [ {"type": "text", "text": "一只戴墨镜的柴犬坐在冲浪板上，写实风格"} ], "size": "1536×1024", }, timeout=120,)resp.raise_for_status()task = resp.json()# ② 未终态时轮询（建议间隔 2 秒以上）while task["status"] in ("queued", "in_progress"): time.sleep(2) task = requests.get( f"{base_url}/v1/images/generations/{task['id']}", headers=headers, timeout=30, ).json()# ③ 获取结果if task["status"] == "completed": image = task["result"]["data"][0] print(image.get("url") or image.get("b64_json"))else: print(task["error"])

九、创建任务

POST /v1/images/generations

十、请求参数

参数	类型	必填	说明
model	string	是	CMR 模型名称，可用值以控制台为准
contents	array	否	提示词与图片，见素材结构。至少包含一个 type=text。与 prompt 二选一
prompt	string	否	单段提示词，由 CMR 转成一条文本内容。与 contents 同时出现返回 400
n	integer	否	独立生成张数，≥1。不填按 1 张提交。不是组图张数上限，模型自己的上限由模型判断
size	string	否	精确像素：auto 或宽 x 高（如 1536×1024）。与 resolution 互斥
aspect_ratio	string	否	宽高比：auto 或宽:高（如 3:2）。与精确像素同时填写时，比例必须一致（21:9 与 7:3 视为一致）
resolution	string	否	档位：512、1K、1.5K、2K、3K、4K、1080p，大小写不敏感。2K 不等于 2048×2048
quality	string	否	auto、low、medium、high、xhigh、max
background	string	否	auto、opaque、transparent。transparent 与 jpeg 同时填写返回 400
output_format	string	否	png、jpeg、webp。jpg 按 jpeg 处理
output_compression	integer	否	0～100，用于 JPEG、WebP
response_format	string	否	希望的交付形式：url 或 b64_json。模型能否照此返回以模型为准
seed	integer	否	随机种子，≥0。填写 0 会原样提交
negative_prompt	string	否	不希望出现的内容（按模型支持）
watermark	boolean	否	是否添加水印（按模型支持）
moderation	string	否	auto 或 low
input_fidelity	string	否	参考图保真度：high 或 low。必须同时有参考图
user	string	否	终端用户标识，用于审计。与请求头 X-User-Id 相互独立
continuation	string \| object \| array	否	上一张结果的 result.continuation，原样回传。非空，序列化后 ≤10MB

参数取值与模型能力：选填参数是否生效取决于所选模型。除 n 不填按 1 张、图片 role 不填按参考图外，未填写的选填参数 CMR 不自动补默认值。标准字段不能传 null。

size 写成档位或比例时会改记：size: "2K" 视为 resolution，size: "16:9" 视为 aspect_ratio。改记后与已填写字段冲突同样返回 400。

stream 只能省略或为 false。image、images、mask、async、wait、operation、provider_extra、safety_user_id、idempotency_key、n_explicit 出现在顶层返回 400。extra_body、extra_headers、extra_query、timeout 会被去掉，厂商参数写在顶层。

十一、素材结构

contents 按数组顺序保留。没有图片为文生图，有图片为编辑或参考生图，没有单独的操作类型字段。不提供 /v1/images/edits。

类型	格式	说明
文本	{"type":"text","text":"…"}	提示词。一个任务至少一个；多条按顺序用换行拼接
图片	{"type":"image","role":"reference" \| "mask","url":"…","id":"…"}	role 缺省 reference。url 为 HTTPS URL 或 data:image/<类型>;base64,…，不接受 HTTP 和裸 base64。id 可选，同一次请求内唯一
蒙版	role 为 mask 的图片	至多一张，且必须同时有一张 reference。模型不支持时忽略

十二、请求示例

文生图：

{ "model": "cmr-image", "contents": [ { "type": "text", "text": "一只戴墨镜的柴犬坐在冲浪板上，写实风格" } ], "size": "1536×1024"}

参考图编辑：

{ "model": "cmr-image", "contents": [ { "type": "text", "text": "把沙发换成深绿色天鹅绒，保持光照不变" }, { "type": "image", "role": "reference", "url": "https://example.com/room.jpg", "id": "room" } ], "size": "1536×1024"}

十三、响应参数

响应体与「查询任务」的任务对象相同。

参数	类型	是否一定返回	说明
id	string	是	任务 ID，形如 imgtask_ 加 26 位字符
object	string	是	固定为 image
status	string	是	见任务状态
model	string	是	请求中的 CMR 模型名称
created_at	integer	是	创建时间，Unix 时间戳，单位为秒
completed_at	integer \| null	是	到达终态的时间；未终态为 null
expires_at	integer	是	任务保留截止时间，创建后 24 小时。此后查询返回 404。不是图片 URL 的过期时间
error	object \| null	是	失败或超时原因；成功和进行中为 null。字段见「错误响应」
result	object \| null	否	仅终态返回。completed 为结果，failed、expired 为 null。进行中不返回该字段。字段见「查询任务」

情形	HTTP	响应
窗口内生成成功	200	status=completed，带 result
窗口内生成失败或结果无法保存	200	status=failed 或 expired，result 为 null，原因在 error
仍在生成，或等待窗口为 0	202	status=in_progress，无 result
参数不合法，或窗口内模型调用被拒绝	4xx / 5xx	错误对象，无任务 ID。任务若已创建，记为 failed（调用超时为 expired），可用列表找到

十四、响应示例

{ "id": "imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW5B", "object": "image", "status": "in_progress", "model": "cmr-image", "created_at": 1789000000, "completed_at": null, "expires_at": 1789086400, "error": null}

等待窗口由实例 ImageConfig.WaitSeconds 配置，取值 0～300 秒，缺省 15 秒，请求不能修改。为 0 时立即返回 202。返回 id 只表示任务已受理；是否已有图片看 status。

十五、Provider 自定义参数

CMR 实例默认开启参数转换，并默认透传厂商自定义参数。按厂商要求将参数放入请求即可，无需逐个配置放行；如果实例已配置参数过滤规则，则按该规则处理。

例如，所选模型用单独字段控制组图时，可以这样请求：

{ "model": "cmr-image", "contents": [ { "type": "text", "text": "同一只柴犬的四个角度" } ], "sequential_image_generation": "auto", "sequential_image_generation_options": { "max_images": 4 }}

n 仍是独立张数，CMR 不会把它改写成厂商的组图字段。如需设置默认值、修改参数值或过滤字段，可在目标 CMR 实例的参数转换配置中设置规则。通过管理 API 配置时，使用 CreateParamTranslationConfig 保存、TestParamTranslationConfig 预览；生图规则的端点填写 images_create（查询为 images_retrieve，列表为 images_list）。自定义参数的名称、填写层级和取值以厂商说明为准。更换模型或厂商后，请确认这些参数仍然适用。

十六、查询任务

GET /v1/images/generations/{task_id}

路径参数 task_id 为创建时返回的 id。不使用请求体。任务存在时 HTTP 始终为 200。进行中的异步任务会向模型核对状态。距上次保存不足 2 秒的查询直接返回已保存状态。每次查询计入每分钟请求次数，被限流时返回 429。另一把 Key 的任务、不存在的任务、超过 24 小时的任务都返回 404。

十七、响应参数

基本字段：

参数	类型	是否一定返回	说明
id	string	是	任务 ID
object	string	是	固定为 image
status	string	是	任务状态，参考任务状态
created_at	integer	是	任务创建时间，Unix 时间戳，单位为秒
completed_at	integer \| null	是	到达终态的时间；未终态为 null
expires_at	integer	是	任务保留截止时间，创建后 24 小时
model	string	是	创建请求中的模型名称
error	object \| null	是	失败原因；成功和进行中为 null
result	object \| null	否	仅终态返回。completed 时为结果，failed、expired 时为 null

任务失败：查询接口本身失败（如任务不存在、无权限）返回统一错误格式；任务生成失败是任务属性而非请求失败——查询仍返回 HTTP 200，失败原因在 error 字段中。

result（仅 status=completed）：

参数	类型	是否一定返回	说明
result.created	integer	是	结果时间，Unix 时间戳，单位为秒
result.data	array	是	成功得到的图片
result.errors	array	是	部分图片失败时的错误，字段同 error，可带 index。全部成功时为 []。任务仍可以是 completed
result.background	string	否	模型实际使用的背景
result.quality	string	否	模型实际使用的质量
result.size	string	否	模型实际使用的尺寸。各张不一致时可能不返回
result.output_format	string	否	模型实际使用的编码
result.provider_details	object	否	模型返回的附加内容，结构以模型为准
result.continuation	string \| object \| array	否	多轮修改的回传内容。下一轮原样放入请求的 continuation
result.usage	object	否	用量。无法确定时不返回该字段

result.data[]：

参数	类型	是否一定返回	说明
result.data[].index	integer	是	这张图在本次结果中的下标，从 0 开始
result.data[].url	string \| null	是	图片 URL。模型未返回时为 null
result.data[].b64_json	string \| null	是	图片 base64。模型未返回时为 null。成功的图至少有 url 或 b64_json 之一
result.data[].expires_at	integer	否	模型给出的这张图的过期时间
result.data[].revised_prompt	string	否	模型改写后的提示词
result.data[].size	string	否	这张图的尺寸
result.data[].output_format	string	否	这张图的编码
result.data[].provider_details	object	否	这张图的附加字段，如水印图地址

用量 result.usage（模型未提供的项不返回，不补 0）：

参数	类型	是否一定返回	说明
result.usage.input_tokens	integer	否	模型报告的输入 token
result.usage.output_tokens	integer	否	模型报告的输出 token
result.usage.total_tokens	integer	否	模型报告的总 token。CMR 不用输入与输出相加来填
result.usage.input_images	integer	否	参考图张数，不含蒙版
result.usage.generated_images	integer	否	实际交付张数（带 url 或 b64_json 的项）
result.usage.resolution	string	否	计费档：512、1k、1.5k、2k、2.5k、3k、3.5k、4k。按成图面积取最近一档，与请求的 resolution 不是同一取值表
result.usage.provider_details	object	否	模型用量中的附加字段

十八、响应示例

{ "id": "imgtask_01JQ8ZC3M9X7YB2KDVF6AHRW4T", "object": "image", "status": "completed", "created_at": 1789000000, "completed_at": 1789000012, "expires_at": 1789086400, "model": "cmr-image", "error": null, "result": { "created": 1789000012, "data": [ { "index": 0, "url": "https://upstream.example.com/out.png", "b64_json": null, "size": "1536×1024", "output_format": "png" } ], "errors": [], "usage": { "input_tokens": 18, "output_tokens": 4160, "total_tokens": 4178, "input_images": 0, "generated_images": 1, "resolution": "1.5k" } }}

十九、查询任务列表

GET /v1/images/generations

只读已保存的记录，不向模型核对状态，也不返回图片。窗口内已经拿到结果的任务同样在列表中。仅返回当前 API Key 的任务。

20、请求参数

参数	类型	说明
status	string	按状态过滤：queued、in_progress、completed、failed、expired
model	string	按创建时的模型名称精确过滤
limit	integer	每页数量，1～100，默认 20
cursor	string	上一页返回的 next_cursor，原样回传。无法解析时返回 400

按创建时间从新到旧。不支持 offset。

21、响应参数

参数	类型	说明
object	string	固定为 list
data	array	任务列表。每项含 id、object、status、model、created_at、completed_at、expires_at、error，不含 result
has_more	boolean	是否还有更早的任务
next_cursor	string \| null	下一页游标。没有下一页时为 null

has_more 为 true 时，下次请求带 cursor=<next_cursor>。需要图片时用 id 查询单任务。列表不计入每分钟请求次数。

22、任务状态

状态	说明
queued	状态枚举中的排队值，列表可按它过滤。当前受理后写入的状态是 in_progress
in_progress	生成中，此状态无 result
completed	生成成功，result 可用
failed	生成失败，原因见 error。含内容审核不通过、结果过大（result_too_large）、任务中断（interrupted）、模型返回无法识别（upstream_error、unknown_status）
expired	任务时限内未结束，默认 10 分钟。error.code 为 task_timeout。与 24 小时保留期不是同一件事

状态只会向前迁移；终态（completed / failed / expired）不再变化。建议轮询间隔 2 秒以上。创建满 24 小时后任务不可再查询。

23、结果地址说明

·result.data[].url 为模型侧的临时下载地址，有效期因厂商而异，请在任务完成后尽快下载转存。

·模型返回 b64_json 时，图片内容随任务保存至 expires_at（创建后 24 小时）。

·任务的 expires_at 是记录保留截止，不是 URL 过期时间。模型若返回 result.data[].expires_at，以该字段为准。

·URL 过期后访问会失败，CMR 不重新签发地址。

24、错误响应

·请求失败时，CMR 返回统一的错误格式：

{ "error": { "message": "size and resolution are mutually exclusive", "type": "invalid_request_error", "param": "size", "code": "invalid_parameter" }}

参数	说明
error.message	错误说明；来自模型侧的错误保留原文
error.type	错误类型
error.param	相关请求参数；无法定位时为 null
error.code	错误码，以实际响应为准

这种响应没有任务 ID。参数错误、鉴权失败、在途任务超限和副本容量不足发生在创建任务之前，不会留下任务。窗口内模型调用本身失败时，任务记为 failed，调用超时记为 expired。

·常见错误码

HTTP	type	code	场景与处理建议
400	invalid_request_error	invalid_parameter	字段缺失、类型不对、size 与 resolution 冲突、蒙版不合法、游标无法解析（invalid_cursor），按 error.param 修正。
400	invalid_request_error	unsupported_parameter	stream 不为 false，去掉该字段。
401	authentication_error	unauthorized	API Key 无效，检查 CMR_API_KEY。
403	permission_error	forbidden	Key 没有实例归属，或没有访问权限。
404	not_found_error	task_not_found	任务不存在、不属于当前 Key，或已超过 24 小时。编辑请改用创建接口并在 contents 中带图片；/v1/images/edits 返回 404。
429	rate_limit_error	rate_limit_exceeded	在途任务数达到 Key、用户组或实例的每分钟请求数配置，或查询达到每分钟次数。降低频率后重试。提交被拒绝时响应可能带 x-ratelimit-*-image_tasks。
502	api_error	upstream_error	模型返回内容无法识别，或模型报告失败。稍后重试；持续失败时用列表找到任务并联系支持。
503	api_error	server_overloaded	当前副本容量已满，本次没有创建任务。按 Retry-After 重试。
503	api_error	storage_unavailable	任务存储不可用，稍后重试。