生成与编辑图片

从提交图片生成或编辑请求到查询任务、读取图像和处理失败。

图片生成和编辑都返回任务 ID。提交后查询同一任务，完成后读取图像。

准备 API Key

在 API Key 页面创建或复制完整 API Key，将 API_KEY 替换为密钥。不要使用 Key 前缀或 API Key ID。以下请求使用生产 API https://api.creative-reasoning.com。

生成图像

curl -X POST 'https://api.creative-reasoning.com/unified/v1/images/tasks' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "creative-reasoning-image-1.5",
  "prompt": "白色背景上的蓝色陶瓷杯",
  "n": 1,
  "size": "1024x1024",
  "quality": "low"
}'

首次受理返回 HTTP 202。下面是响应结构示例，ID 为示意值。保存实际响应的 id；pending 表示等待执行，还没有生成结果。

{
  "id": "01a09ec9-7d00-7000-8000-000000000001",
  "status": "pending",
  "created_at": 1789370400,
  "model": "creative-reasoning-image-1.5",
  "poll_url": "/unified/v1/tasks/01a09ec9-7d00-7000-8000-000000000001"
}

查询并读取结果

用响应中的 id 替换 TASK_ID_FROM_SUBMIT_RESPONSE，并使用提交时的同一 API Key：

curl 'https://api.creative-reasoning.com/unified/v1/tasks/TASK_ID_FROM_SUBMIT_RESPONSE' \
  -H 'Authorization: Bearer API_KEY'

查询返回 HTTP 200 时，仍需判断 status。pending、processing 表示继续等待，可每隔 5 秒查询一次并设置总等待上限；到期后保留 ID，稍后继续查询。failed 表示生成失败，读取 error.code 和 error.message。只有 completed 才读取 data。

下面是完成响应的结构示例，媒体内容及 URL 凭证均为占位值：

{
  "id": "01a09ec9-7d00-7000-8000-000000000001",
  "status": "completed",
  "created_at": 1789370400,
  "model": "creative-reasoning-image-1.5",
  "completed_at": 1789370460,
  "data": [
    {
      "b64_json": "BASE64_IMAGE_DATA"
    }
  ]
}

逐项读取 data：有 b64_json 时 Base64 解码成图片文件；若包含 data:image/...;base64, 前缀，先去掉前缀。有 url 时使用完整链接下载。BASE64_IMAGE_DATA 不是可解码的图片。任务终态正文保留 24 小时，及时保存图片到自己的存储。

编辑图像

下面通过 JSON 的 image 提供待编辑图片。把 https://customer.example.com/assets/cup.png 换成你自己的、CR 可直接访问的图片 URL；也可使用 Base64 Data URI。接口不接收 multipart 表单。

curl -X POST 'https://api.creative-reasoning.com/unified/v1/images/edit-tasks' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "creative-reasoning-image-1.5",
  "prompt": "将杯子改为红色，保持其余画面不变",
  "n": 1,
  "size": "1024x1024",
  "quality": "low",
  "image": "https://customer.example.com/assets/cup.png"
}'

保存这次编辑响应的新 id，用上面的查询请求读取编辑结果。image 也可以是图片地址数组，用于多图合成；单图局部编辑可提供 mask。详细取值见 Image 1.5 参数。

按方向扩展画布

扩图只适用于明确支持 image_outpaint 的模型。model 决定操作，expansion 描述扩展范围；普通图片生成或编辑模型不会因为传入 expansion 而获得扩图能力。

先用自己的模型调用 API Key 查询可用模型。把 API_KEY 换成在 CR 控制台创建的 API Key；它不是 Management Token。

curl 'https://api.creative-reasoning.com/unified/v1/models?capability=image_outpaint' \
  -H 'Authorization: Bearer API_KEY'

响应 data[].id 是可用于调用的模型名称，data[].capabilities.image_outpaint 给出该模型的扩图参数边界。空列表表示当前 API Key 没有可用扩图模型，请联系管理员确认权限与可用性。

取得模型名称后，登录扩图模型接入文档，按该名称查找并打开对应模型的详细页。该页提供绑定到具体调用名称的参数表、完整请求、任务查询、结果解释、错误处理与计费说明。使用其中的扩图示例，不要直接替换成本页普通图片生成或编辑示例中的模型名称。

目录默认只展示模型广场中的模型。如果发现接口返回的名称不在目录中，可直接打开 https://creative-reasoning.com/docs/zh/models/calling/YOUR_MODEL。将 YOUR_MODEL 替换为 data[].id，并按 URL 路径段编码，例如将 / 编码为 %2F。详细页仍需登录，并按当前账号权限展示；若无法访问，请联系管理员核对账号与 API Key 所属团队的权限。

用蒙版指定编辑区域

creative-reasoning-image-1.5 支持蒙版编辑。准备与原图像素宽高相同的 PNG 蒙版：需要修改的区域设为完全透明（Alpha = 0），保留区域设为不透明（Alpha = 255）。只有黑白颜色、没有透明区域的图片不能表示这一选区。蒙版引导模型编辑，但不保证蒙版外像素逐点不变。

把下面两个素材 URL 替换为你自己的、CR 可直接访问的原图与蒙版地址。蒙版不是生成图片的透明背景设置，也不要放进 provider_options。

curl -X POST 'https://api.creative-reasoning.com/unified/v1/images/edit-tasks' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "creative-reasoning-image-1.5",
  "image": "https://customer.example.com/assets/source.png",
  "mask": {"image_url": "https://customer.example.com/assets/mask.png"},
  "prompt": "移除蒙版透明区域内的目标，并根据周围内容自然补全背景。不要添加替代目标，尽量保持蒙版外的内容、构图和光线不变。"
}'

保存提交响应的 id，按本页查询步骤使用同一 API Key 获取任务结果；HTTP 202 仅表示受理。下载后的蒙版必须是有效的透明 PNG，宽高与第一张原图相同；素材每个不超过 50 MiB，蒙版不超过 67,108,864 像素。格式、尺寸或透明选区不正确时，读取提交错误或任务 error.message，修正素材后再提交。

mask 的对象形式与 OpenAI 图片编辑 JSON 接口的 image_url 形式一致。CR 也保留字符串简写："mask":"https://customer.example.com/assets/mask.png"。两者均可使用 Base64 Data URI；不支持 file_id、蒙版数组或同时混用多个引用字段。字符串简写是 CR 统一接口的兼容格式。

调整图片参数

size 使用像 1024x1024 这样的像素尺寸；quality 可选择 low、medium、high。修改尺寸时同时满足边长、比例和像素总数限制，见完整模型参数表。更换模型时重新核对其支持范围。

回调与失败恢复

可在提交正文顶层添加自己的 HTTPS callback_url。收到的终态与查询结果相同；以任务 id 去重。地址约束和重投规则见回调说明。
需要安全重试提交时，添加 Idempotency-Key: YOUR_UNIQUE_OPERATION_ID。这是调用方为本次业务操作生成并保存的唯一编号，不是密钥。相同操作重试必须复用该编号和原请求正文。
已有任务 ID 时查询原任务。没有幂等键且提交超时时，不要盲目重发 POST，以免重复生成和计费。
401 检查 API Key；404 查询时检查 ID 和是否使用原 Key；failed 读取错误原因；410 task_expired 表示结果正文已过期。完整恢复规则见任务错误与幂等提交。

兼容接口

已有接入可继续使用 /unified/v1/images/generations 和 /unified/v1/images/edits。它们可能直接返回图片，也可能返回任务；详情见兼容响应处理。迁移到本页接口后，提交先返回任务，必须按上文查询结果。

图片与视频 Skill

需要让 Claude Code 或 Codex 用自然语言生成、编辑图片和视频时，安装 cr-media Skill。该指南包含插件与 npx skills 安装、升级、API Key 配置，以及本地参考图和 URL 的使用限制。

生成与编辑图片

关联 API

本页目录