跑通图片和视频生成

接入图片或视频服务商,让一次生成完整跑通:请求变量、带数组下标的解析路径、状态轮询、结果入库,以及在 agent 对话里显示图片和视频。

一次图片或视频生成要经过四个环节,用户才能看到结果:发给服务商的请求、服务商的响应(通常是一个任务 ID)、让任务结束的状态查询,以及文件存储。本文为 image-creation 和 video-creation 两个场景逐一配置这四个环节,再说明 agent 如何发布同一份结果。相关概念见 AI 渠道、场景与任务生命周期。

准备工作

  • 一个图片或视频服务商的账号和 API Key,以及它的提交响应和状态查询响应的真实样例。
  • 已在 设置 → 存储配置 中配置文件存储。没有存储时任务仍会成功,但结果不会进入用户的文件,agent 也没有文件可发布。见配置文件存储与上传。
  • 一个持有 ai.read 和 ai.write 的管理员账号。
  • 仅 agent 部分需要:Agent 启动模板已经运行,agent.general 已配置模型。

接入服务商

创建 Provider 和它的请求

在 设置 → AI 配置(/admin/config/ai)中创建 Provider,填写 base URL 和 API Key,做法见接入 AI 服务商。在 请求参数 里,用下面的变量拼出服务商要求的请求体:

变量值
{{prompt}}请求的提示词
{{input}}请求的 input;没有提供时是提示词
{{metadata.<name>}}请求里的其他字段,例如 size、aspect_ratio、duration
{{externalTaskId}}服务商的任务 ID,拿到之后才有值,用在状态查询地址里
{{sceneKey}}、{{channelKey}}、{{mediaType}}本次调用的场景、Provider 和输出类型
{{secret.<key>}}后台配置里分类为 secret 的一项设置

文本值原样插入,其他类型的值按 JSON 插入,所以时长这样的数字发给服务商时仍是数字。使用上表以外的变量会报 Unsupported template variable。模板里直接粘贴密钥也会报错,请改用 secret 引用。

发给 POST /api/<scene>/generate 的字段里,除了 prompt、mediaType 这类保留名之外的都是请求的 metadata。agent 的 model.generate 调用里 input 的字段也是。例如,图片 agent 里选的画幅以 {{metadata.aspect_ratio}} 发给服务商。

每个模型加一个 Provider 场景

为图片模型加一个输出类型为 图片 的 Provider 场景,为视频模型加一个 视频 的。在 Provider 场景 endpoint 里填以 / 开头的路径(会拼到 Provider 的 base URL 后面),或者完整的 https:// 地址。计价按路由场景与设置价格配置。

让解析路径对上服务商的字段

对照真实响应填写 上游任务 ID 路径、状态路径、结果路径 和 错误路径。路径从 $ 开始,可以带数组下标:

提交响应
{ "code": 200, "data": [{ "status": "submitted", "task_id": "task_1" }] }
字段路径
上游任务 ID 路径$.data[0].task_id
状态路径$.data[0].status
完成后的状态响应
{ "data": { "status": "completed", "result": { "images": [{ "url": ["https://cdn.example.com/a.png"] }] } } }
字段路径
状态路径$.data.status
结果路径$.data.result.images[0].url[0]

下标越界,或者对对象使用下标,都按未提供处理。提交响应和状态响应的结构通常不同,状态查询的路径在 状态查询响应字段 里单独填写。

把服务商返回的每种状态都映射上

在 状态映射 里,用逗号分隔列出服务商的哪些字符串代表 排队中、运行中、成功、失败 和 已取消。匹配不区分大小写。提交响应里的状态也要列进去(上例的 submitted 应归到 排队中)。状态不在任何列表里时任务失败,报 Unmapped AI channel status,即使服务商已经受理。

保存前粘贴一份真实响应,点击 测试解析。

设置结果如何返回

大多数图片和视频 API 返回的是任务 ID。在 结果获取 中选择 状态轮询,在 状态查询 URL 模板 里填入带 {{externalTaskId}} 的地址,并填写 间隔秒。

在 Provider 场景上,状态查询地址可以是以 / 开头的路径。这个路径相对 Provider 的 base URL 解析,规则与 endpoint 相同:

Provider base URL        https://api.example.com
状态查询 URL 模板         /v1/tasks/{{externalTaskId}}
实际查询                  https://api.example.com/v1/tasks/task_1

完整的 https:// 地址原样使用。服务商主动回调的情况见接收异步结果。

路由场景

把 image-creation 路由到图片 Provider 场景,把 video-creation 路由到视频 Provider 场景。场景只能路由到输出类型相同、已启用且就绪的 Provider 场景。

运行中的任务如何收尾

服务商受理的任务一直是 running,直到状态被查询。有三处会查询状态,服务商报告任务结束时都会结算积分:

触发方时机
客户端读取 GET /api/status?taskId=…每当轮询间隔已过。/app/ai/<taskId> 页面打开期间会这样做。
定时任务 ai-channel-tasks每分钟一次,处理没有人在看的任务。见后台任务。
agent 的 model.collect运行取回它用 async: true 发起的生成时。

任务成功后,系统下载输出里的每个 URL,作为私有文件存入用户的 /generated 文件夹,并标记为来自这个任务。之后任务的输出列出这些已存储的文件。

检查存储 endpoint

生成的文件通过你配置的存储服务写入。对 S3 兼容的服务,对象地址取决于 S3 endpoint:

Endpoint对象地址
https://s3.example.comhttps://s3.example.com/<bucket>/<key>(路径风格)
主机名已经以桶名开头https://<bucket>.storage.example.com/<key>
主机名以 .aliyuncs.com 结尾https://<bucket>.oss-<region>.aliyuncs.com/<key>(虚拟主机风格)

请求签名和预签名 URL 使用同一个地址,所以 endpoint 要严格按服务商文档填写。阿里云 OSS 填地域 endpoint,不要带桶名。

由 agent 发布

Agent 通过同样的场景生成,不需要额外配置。在一次运行里:

  1. Skill 调用 model.generate,带上 sceneKey: "image-creation" 或 "video-creation" 和一个 saveTo 路径。使用 async: true 时 Skill 先得到任务句柄,之后用同一个 saveTo 调用 model.collect。
  2. 写在 saveTo 的是一份清单,里面指明存储文件。图片或视频本身已经在存储里。
  3. Skill 用 kind: "image" 或 "video" 和这个路径调用 artifact.publish。产物的版本指向这个存储文件,不会重新下载或上传。前提是清单里只有一个文件,文件属于该用户、来自 AI 任务,并且内容类型与发布的类型一致。
  4. 对话在消息里显示产物:图片显示为预览,视频显示为带控制条的播放器。产物仍然可以在右侧面板打开。

预览授权的有效期是一分钟。视频在播放期间按区间读取,所以加载因授权过期而失败时,播放器重新获取一次授权,并从原位置继续播放。授权仍有效时加载失败,卡片改为显示打开和下载操作。

如果需要画幅选择和每次运行的张数上限,安装图片 Agent。

验证

  1. 在 /app/ai 发起一个图片任务,或者用 API:

    curl -X POST https://<your-domain>/api/image-creation/generate \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"prompt":"A lighthouse at dusk","mediaType":"image"}'
  2. 在 /app/ai/<taskId> 上,任务从 running 变为 succeeded,事件里有 Generated output imported to storage.

  3. 图片出现在 /app/assets 中该用户的生成文件里。

  4. 用 video-creation 和 "mediaType":"video" 再做一遍。

  5. 如果安装了 agent,在 /app/agent 里请求一张图或一段视频。结果显示在消息里,页面停留超过一分钟后视频仍能播放。

  6. 在仓库里,pnpm validate:generation-pipeline 检查解析路径、相对的状态查询地址和对象寻址。随 agent 启动模板分发的 pnpm validate:agent-generation 检查发布和播放器。两者都不调用服务商。

故障排查

服务商已受理,任务却失败

提交响应里的状态不在任何 状态映射 列表里,或者 状态路径 指向了错误的字段。任务的错误信息里有未映射的状态名,把它加到 排队中 或 运行中。

任务一直在运行

检查 上游任务 ID 路径 能否从提交响应里读到 ID(服务商返回数组时要带下标),轮询是否启用并填了 状态查询 URL 模板,以及后台任务是否在运行。超过五分钟没有执行一轮时,/setup 会给出警告。

任务成功了,但没有文件入库

任务事件里有 Generated output storage import skipped.,并附带每个 URL 的失败原因。S3 兼容服务返回 403,通常是 endpoint 的寻址风格与上表不符。

agent 的产物显示无法加载

发布的路径不是本次运行里某次生成的 saveTo 清单,或者类型与文件不符。视频要以 video 发布,图片要以 image 发布。

下一步