媒体任务参考

本页集中说明模型参数、任务查询、结果字段、回调及幂等规则。首次接入请按生成与编辑图片或生成视频完成一次调用。

准备 API Key

本页示例使用生产 API https://api.creative-reasoning.com。在 API Key 页面创建或复制完整 API Key，将请求头中的 API_KEY 替换为完整密钥即可。

选择提交接口

三个提交接口复用图片与视频参数。模型支持的尺寸、时长、参考图、质量及扩展参数没有改变。图片编辑只接收 JSON，不接收 multipart。

提交图片任务

下面是最小提交示例。需要避免重试造成重复生成时，按本页后文添加可选的 Idempotency-Key 请求头。

curl "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"
  }'

首次受理返回 202 Accepted，不等待生成完成。保存 id 和 poll_url；响应的 Location 也包含查询路径。poll_url 是相对路径，拼在 https://api.creative-reasoning.com 后得到完整查询地址。

{
  "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"
}

202 表示任务已被受理，不代表生成成功。部分模型参数错误只能在执行时发现，此时任务会进入 failed。

提交视频或编辑任务

视频将请求发到 /unified/v1/videos/tasks，正文仍使用 model、content 和该模型支持的参数。例如：

{
  "model": "creative-reasoning-video-1.0",
  "content": [{"type": "text", "text": "海边日落"}],
  "duration": 4,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}

编辑将 JSON 请求发到 /unified/v1/images/edit-tasks，通过 image 提供素材，并按模型能力选用 mask。不要把上述视频参数直接用于其他模型，先核对参数差异。

请求视频尾帧

在模型目录选择支持输出尾帧及 4 秒、720p、16:9 参数组合的模型，将 YOUR_VIDEO_MODEL 替换为该模型名称。下面请求一个视频及其尾帧。return_last_frame 放在 provider_options 中；字段名使用下划线。这里的尾帧是生成结果，与通过 content[].role: "last_frame" 提供的输入图片不同。

curl "https://api.creative-reasoning.com/unified/v1/videos/tasks" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL",
    "content": [{"type": "text", "text": "一只蓝色陶瓷杯放在木桌上，阳光照在杯身上，镜头缓慢向前推进。"}],
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "provider_options": {"return_last_frame": true}
  }'

保存返回的 id，按本页的查询步骤获取结果。需要完成通知时，再在请求顶层加入自己的 callback_url。请求尾帧不增加 data 中的视频数量；读取时仍需检查 last_frame_url 是否存在。

请求参数

通用参数

所有接口使用 Authorization: Bearer API_KEY 和 Content-Type: application/json。

有通用字段的参数放在顶层。例如视频时长使用 duration，宽高比使用 aspect_ratio。没有通用字段的模型能力才使用 provider_options，例如支持声音控制的模型使用 provider_options.generate_audio。不要在两处重复指定同一参数：有的模型采用通用字段，有的模型会拒绝冲突值。

provider_options 任意深度出现 callback_url 都返回 400 reserved_parameter。增加 callback_url 不改变模型支持的生成参数，也不会让不支持某种输入的模型获得该能力。

图片参数

适用于图片任务接口 POST /unified/v1/images/tasks、POST /unified/v1/images/edit-tasks，以及兼容接口 POST /unified/v1/images/generations、POST /unified/v1/images/edits。编辑接口只接受 JSON，不接受 multipart 表单。

例如 1024x1024、1024*1024、1K 和 16:9 不能互换。接口中的 size 示例值不是每个模型都接受的默认值。

creative-reasoning-image-1.5

生成、编辑的推荐调用 ID、完整参数、尺寸限制及返回说明，统一见该模型的接入文档。该页面登录后可见。

先运行其中一个最小示例，再按同页参数表调整 size、quality、image 或 mask。提交完成后，继续查询原任务并保存实际返回的图片。

视频参数

适用于 POST /unified/v1/videos/tasks 和 POST /unified/v1/videos/generations。

以上是请求设置。实际成片属性以视频结果字段为准，结果中的 duration 和 fps 可以是小数；结果缺失的字段不继承请求值。支持输出尾帧的模型可使用 provider_options.return_last_frame: true，见完整请求示例。

content 输入类型与角色

带首帧的 content 结构如下。图片 URL 需要替换为可访问的素材地址，所选模型必须支持首帧输入：

[
  {"type": "text", "text": "镜头缓慢向前推进"},
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "https://customer.example.com/assets/first-frame.png"}
  }
]

参考图应显式填写 role: "reference_image"。省略 role 可能被当作首帧。JSON 结构合法不代表该模型支持这些媒体类型、数量或组合。

上面的 creative-reasoning-video-1.0 文生视频示例只包含文字，不传参考图片、视频或音频。provider_options.generate_audio 是可选布尔值，用于控制生成声音，不是输入参考音频。时长、分辨率和声音开关的取值见下面的模型支持表。

视频模型支持范围

以下设置适用于 creative-reasoning-video-1.0、creative-reasoning-video-1.0-i2v 和 creative-reasoning-video-1.0-r2v：

resolution 放在请求顶层，不使用图片的 quality 字段。adaptive 在文生视频中按提示词选择比例，在首帧模型中参考首帧，在参考模型中优先参考视频、其次图片。实际成片属性仍以返回结果为准。

输入图片使用 JPEG、PNG 或 WebP；单张不超过 30 MB，宽高各为 300–6000 像素，宽高比在 0.4–2.5 之间。参考视频使用 MP4 或 MOV，单条 2–15 秒且不超过 50 MB，所有参考视频总时长不超过 15 秒；参考音频使用 WAV 或 MP3，单条 2–15 秒且不超过 15 MB，总时长不超过 15 秒。使用 CR 可访问的完整素材 URL。

role: "last_frame" 表示输入尾帧，不代表返回 last_frame_url。输入素材、时长和分辨率会影响用量，费用以模型价格及调用明细为准。

creative-reasoning-video-1.0

该模型从文字生成视频。用 content 中的 text 描述画面和动作，参数取值见上表。完整的提交、查询及下载步骤见生成视频。

creative-reasoning-video-1.0-i2v

该模型使用首帧图片生成视频。示例使用一张图片、role: "first_frame"、duration: 4、resolution: "480p" 和 aspect_ratio: "16:9" ，不需要 provider_options。示例使用一张可公开访问的白猫图片。

{
  "model": "creative-reasoning-video-1.0-i2v",
  "content": [
    {
      "type": "text",
      "text": "白色长毛猫在绿色草地上缓慢向镜头走来，尾巴轻轻摆动，阳光柔和，固定镜头，保持图片中猫的外观。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}

替换图片时使用 CR 可直接访问的 URL，并同步修改提示词。其他输入数量和媒体组合见视频模型支持范围。resolution 选择档位，实际宽高和时长以生成结果为准。

creative-reasoning-video-1.0-r2v

该模型使用参考图片引导视频生成。示例使用一张图片、role: "reference_image"、duration: 4、resolution: "480p" 和 aspect_ratio: "16:9" ，不需要 provider_options。图片必须显式标注参考角色。示例使用一张可公开访问的白猫图片。

{
  "model": "creative-reasoning-video-1.0-r2v",
  "content": [
    {
      "type": "text",
      "text": "白色长毛猫在绿色草地上缓慢向镜头走来，尾巴轻轻摆动，阳光柔和，固定镜头，保持图片中猫的外观。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
      },
      "role": "reference_image"
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}

替换图片时使用 CR 可直接访问的 URL，并同步修改提示词。其他输入数量和媒体组合见视频模型支持范围。resolution 选择档位，实际宽高和时长以生成结果为准。

未支持的字段可能被忽略，也可能导致请求或任务失败。HTTP 2xx 只表示请求已被接受，不证明所有可选参数都生效；异步任务仍可能在之后返回 failed。

查询或等待结果

使用提交任务时的同一 API Key。用另一把 API Key 查询会返回 404，即使两把 Key 属于同一个团队。将 TASK_ID_FROM_SUBMIT_RESPONSE 替换为提交响应中的 id，再查询该任务：

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

查询成功返回 200 和任务对象。根据 status 处理：

希望少做短间隔轮询时，调用 /unified/v1/tasks/TASK_ID_FROM_SUBMIT_RESPONSE/wait。它最多等待 30 秒；仍未完成时，返回 200 和当前状态。可以再次等待同一个 ID。等待超时、客户端断开或重复查询不会取消任务，也不会重新生成。

支持返回尾帧的视频模型可在提交时设置 provider_options.return_last_frame: true。模型返回尾帧时，成功结果的 data[].last_frame_url 提供尾帧图片下载链接；未返回时省略该字段。任务查询、等待结果和完成回调中的字段一致。链接的使用与有效期见下载视频及尾帧。

生成失败同样通过 200 返回任务对象，使用 status: failed 表示；不要只看 HTTP 状态判断生成是否成功。终态正文从完成时起保留 24 小时，过期返回 410 task_expired。及时保存结果，下载链接还有自身的有效期。

读取图像用量

部分图像模型将输入与输出用量合并为计费 Token，在价格表和调用明细中显示为“综合用量”。若统一响应包含 usage.billing.tokenhub_tokens，该值就是本次请求的计费用量，例如：

{
  "usage": {
    "billing": {"tokenhub_tokens": 3763}
  }
}

该数量是本次生成或编辑的输入与输出综合计费用量，使用对应的计费 Token 单价计算费用。它不代表原厂文本输入或图片输出 Token。此类响应不提供可还原的输入、输出和缓存分项；读取这些分项的客户端应允许字段缺失。图片仍从 data[].url 或 data[].b64_json 读取。

单价以模型目录的对应计费项为准，参见图像计费项和费用计算示例。同步结果与异步任务的完成结果使用相同的用量含义。

读取视频结果字段

每个 data[] 元素对应一个视频，尾帧属于同一元素。以下字段含义统一，可用字段因模型而异；模型未报告或字段无效时省略，不用请求设置代替生成结果。客户端须允许新增可选字段，历史结果可以缺少 type。

任务顶层 tools 提供工具执行统计，各视频中不重复。例如：

{
  "tools": [{"type": "web_search", "calls": 2}]
}

calls 为非负整数，明确返回 0 时保留；只报告工具、没有次数时省略 calls。没有工具信息时省略 tools，请求开启搜索不代表实际调用。统计仅提供执行信息，不参与费用计算，usage 的含义不变。任务级 extensions 仅承载已定义的任务信息，当前没有已定义扩展字段，响应省略此对象。

查询、wait、完成回调及回调重试返回同一份保存的终态，包含相同下载链接。图片的 URL、Base64 和多图返回形态保持不变。

成功响应示例

下面展示包含尾帧的完整任务对象。下载链接中的 OPAQUE_VIDEO_TOKEN 和 OPAQUE_FRAME_TOKEN 是占位符，实际使用时保留响应中的完整 URL。示例只展示部分可选字段，不代表每次生成都会返回这些字段。

{
  "id": "01a09ec9-7d00-7000-8000-000000000002",
  "status": "completed",
  "model": "YOUR_VIDEO_MODEL",
  "created_at": 1789370400,
  "completed_at": 1789370640,
  "data": [{
    "type": "video",
    "url": "https://api.creative-reasoning.com/_cr/v1/media/video/01a09ec9-7d00-7000-8000-000000000002/OPAQUE_VIDEO_TOKEN",
    "last_frame_url": "https://api.creative-reasoning.com/_cr/v1/media/video/01a09ec9-7d00-7000-8000-000000000002/OPAQUE_FRAME_TOKEN",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "has_audio": false,
    "seed": 0
  }],
  "usage": {"output": {"video_tokens": 87300}}
}

兼容可选字段

读取结果时保留有效的 false、0 和小数。字段缺失表示未报告，不能默认成无音频、零次工具调用或请求中设置的值。GET、wait 和完成回调中的字段含义相同；忽略未识别的新增字段，并允许历史结果缺少 type。

下载与保存结果

直接使用 data[].url 播放或下载视频，不要解析或拼接 URL。示例中的 OPAQUE_VIDEO_TOKEN 仅为占位符。真实链接自生成起最多有效 24 小时；如果源文件提前过期，链接也会提前失效。需要长期保存时，请及时下载到自己的存储。

对于支持返回尾帧的模型，在提交请求的 provider_options 中设置 return_last_frame: true。模型返回尾帧时，data[].last_frame_url 是尾帧图片的下载链接；未返回时省略该字段。任务查询和完成回调中的链接一致。尾帧链接与视频链接遵循相同的访问和过期规则，请直接使用返回的完整 URL。

视频规格、音频状态及任务级工具统计见视频结果字段。同一字段在查询和回调中的含义一致，可用字段因模型而异。

CR 流式转发视频，不跳转到供应商地址。下载支持 GET、HEAD 和单段 Range，无需附加 CR API Key。链接本身包含访问凭证，请勿写入公开日志或发给无关人员。过期或被篡改的链接返回 404。

回调重试、管理员重新投递和后续查询使用同一份已保存正文，不延长其中下载链接的有效期。下载失败不改变生成状态，也不会再次收取生成费用。

图片从 data[].url 下载或读取 data[].b64_json。图片链接也可能过期，需要长期保存的结果请及时下载到自己的存储。

使用 callback_url 接收通知

需要通知时，在任一提交正文顶层加入 callback_url：

{
  "callback_url": "https://customer.example.com/webhooks/cr-media?token=your-random-token"
}

这只是追加字段的示例，提交时仍需提供 model 和生成参数。回调地址遵循HTTPS 回调规则，不能放入 provider_options。

CR 只发送 completed 或 failed。回调正文与该任务保存的终态 GET 响应逐字节一致，没有事件外层。成功结果包含 data 和可用的 usage；视频结构见本页成功响应示例，图片保留模型支持的 url 或 b64_json。

准备回调地址

提供一个无需 CR API Key 即可接收 POST 的 HTTPS 地址。该地址需要满足以下规则：

• 使用绝对 HTTPS URL，UTF-8 编码后不超过 2048 字节。
• 可以包含 path 和 query，但不能包含 userinfo 或 fragment。
• 域名的全部 DNS 地址都必须是公网地址。
• 不能指向 CR API 本身。

生产环境不要使用 localhost、IP 内网地址或依赖 HTTP 重定向的地址。如需校验调用方，可以在 query 中放置随机 token，并在接收端比对。不要把完整回调 URL 写入日志。

接收终态

失败回调的 status 是 failed，并包含 error。取消的任务使用 error.code: "task_cancelled"。失败回调不包含 data 或 usage。

error.code 用 CR 自己的词汇说明失败原因：取消为 task_cancelled，未归类的失败为 task_failed。CR 不会返回模型供应商的错误文案、错误码或标识，因此这些取值对所有模型一致。完整集合与安全的分支写法见错误码。

每次投递只依赖以下标准请求头：

正常解析 JSON 即可，不需要保留原始正文。

防止重复处理

网络超时可能导致同一个终态被重复发送。使用正文中的 CR 任务 id 作为幂等键。保存结果时，为任务 id 建立唯一约束；如果该任务已经处理，直接返回 2xx。

先保存结果，再返回 2xx。如果业务处理时间较长，先把结果写入队列或数据库，再异步处理。

处理重试

CR 首次投递失败后，最多再重试 3 次。重试分别安排在失败后的 1、2、4 秒。同一任务的每次投递使用相同正文。

• 任意 2xx 表示投递成功。
• 非 2xx、连接错误、TLS 错误和超时会触发重试。
• 3xx 不会跳转。

CR 等待单次响应的时间不超过 10 秒。

回调投递失败不改变生成任务状态，也不重复计费。需要对账时，使用提交响应中的 poll_url 查询任务。查询接口和回调返回相同的终态正文。

避免重复生成与处理错误

以下规则适用于 /unified/v1/images/tasks、/unified/v1/images/edit-tasks 和 /unified/v1/videos/tasks。需要安全重试这些提交请求时，添加可选的 Idempotency-Key 请求头。它是由你生成的业务操作唯一标识，不是 API Key，也不参与认证。将下面的 YOUR_UNIQUE_OPERATION_ID 替换为本次操作的唯一编号，例如保存在业务记录中的 UUID；同一操作重试时复用该值和请求正文，新操作使用新值：

Idempotency-Key: YOUR_UNIQUE_OPERATION_ID

标识长度为 1–256 个不含空白的可打印 ASCII 字符。它只在同一 API Key、同一操作、同一接口范围内复用任务；不跨图片/视频或新旧提交接口去重。

• 相同键和相同请求：返回同一任务；任务已终态时 POST 可返回 200，但正文仍是任务对象。
• 已受理任务：只要提交时的 API Key 仍有效，可以用相同键和请求恢复任务，即使该模型已不再接受新的生成请求。
• 相同键、不同请求：返回 409 idempotency_conflict，不创建第二个任务。修改 callback 地址也属于请求变更。
• 超时、断网或 503：不表示任务一定未受理。已设置幂等头时，以相同键和相同请求重试；已经拿到 ID 时直接查询。未设置幂等头时，不要盲目重发 POST，以免重复生成。
• 每把 API Key 最多同时保留 128 个未完成任务。达到限制返回 429 task_capacity_exceeded，稍后重试。
• 等待连接达到上限时，/wait 返回 429 task_wait_capacity_exceeded，改用普通 GET 查询。
• 400 invalid_parameter：检查请求，尤其不要在新接口传 response_mode。

任务记录保留到终态后的 30 天，用于幂等识别；这不延长结果正文的 24 小时有效期。不要永久重复使用同一个幂等键。不带该 Header 的每次 POST 都是新的生成任务。

任务最长执行 24 小时。无法确认提交结果时，CR 不会盲目再次生成；最终可能返回 submission_unknown，该任务不向客户扣费。生成终态失败不扣生成费用；生成成功但客户回调不通，仍按成功生成计费。

兼容接口

兼容接口不提供上述任务接口的幂等提交保证。已拿到任务 ID 时查询原任务；提交超时且没有 ID 时，先确认是否已经受理。

旧的 /unified/v1/images/generations、/unified/v1/images/edits 和 /unified/v1/videos/generations 继续支持，尚未废弃。旧图片接口仍按所选模型保留同步结果或任务响应，旧视频接口仍返回任务。迁移时需要同时修改提交路径和结果处理代码，不能只替换 URL 后继续直接读取 data。

图片生成与编辑兼容接口

将 YOUR_MODEL 替换为模型目录中支持相应图片操作的模型名称。

生成图像

先按图片参数与模型示例确认 size、quality 和输入限制，再运行请求。通用示例不代表所有可选参数都受支持。

正在读取服务信息…

编辑图像

正在读取服务信息…

编辑接口使用 JSON，不接收 multipart 上传。将示例 URL 替换为 CR 服务可访问的图像。先确认所选模型支持编辑，再按图片参数核对格式、数组和 mask 支持；文生图通过不代表编辑也可用。

处理响应

同步响应直接读取 data。只轮询 pending 或 processing 任务，并使用提交任务的 API Key。轮询时设置间隔和总等待上限；到期后保留任务 ID，稍后继续查询。

根据模型的原生行为和是否传入回调地址，处理已受理的请求：

异步图片响应没有 poll_url 时，查询 GET /unified/v1/images/generations/{id}，将 {id} 替换为提交响应中的 CR id。不要重新 POST 来查询结果。图片编辑任务也使用这条查询路径。

接收图片回调

生成和 JSON 编辑接口都支持顶层 callback_url。不传该字段时，原有同步或异步行为不变。不要把它放进 provider_options，否则返回 400 reserved_parameter。

带回调的请求返回 status: "pending"、CR 任务 id 和 poll_url。图片编辑任务也使用 /unified/v1/images/generations/{task_id} 查询。同步模型仍在本次 POST 内完成生成，然后保存结果并排队通知；添加回调不代表 POST 会立即返回，也不会再次调用模型。

回调格式、地址校验和重投规则见本页的回调说明。

503 callback_unavailable 表示回调无法登记或保存；如果错误发生在模型服务接受请求之后，生成可能已经开始，不要无条件重新提交。

视频生成兼容接口

视频接口使用异步任务，不提供等待出片后直接返回媒体的同步 POST。不传 callback_url 时，提交响应仍返回 CR id 和 poll_url。使用提交任务的 API Key 轮询该地址，直到 completed 或 failed，不要重复提交生成请求。

以下示例使用 creative-reasoning-video-1.0 的文生视频示例参数。将回调 URL 换为你的接收地址，并把 callback_url 放在请求顶层。更换模型前，核对视频参数与模型差异，不要沿用另一模型的时长、清晰度或宽高比。

curl "https://api.creative-reasoning.com/unified/v1/videos/generations" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "creative-reasoning-video-1.0",
    "content": [{"type": "text", "text": "海边日落"}],
    "duration": 4,
    "resolution": "480p",
    "aspect_ratio": "16:9",
    "callback_url": "https://customer.example.com/webhooks/cr-video"
  }'

不要把 callback_url 放入 provider_options。该名称在 provider_options 的任意深度都是保留参数，服务会返回 400 reserved_parameter。

保存响应中的 id 和 poll_url。id 在提交响应、查询响应和回调正文中保持一致：

{
  "id": "0199c9e6-9381-7f30-9aa0-0df86dca6cdf",
  "status": "pending",
  "created_at": 1788912000,
  "model": "creative-reasoning-video-1.0",
  "poll_url": "/unified/v1/videos/generations/0199c9e6-9381-7f30-9aa0-0df86dca6cdf"
}

503 callback_unavailable 表示回调服务暂不可用，可能发生在任务受理前或受理后。不能仅凭 503 判断任务未创建。收到该错误时，不要自动重发 POST；保留请求 ID，联系支持确认任务是否已创建。503 media_unavailable 表示视频下载服务暂不可用，删除 callback_url 无法解决；请联系支持后再提交。