跑通图片和视频生成
接入图片或视频服务商,让一次生成完整跑通:请求变量、带数组下标的解析路径、状态轮询、结果入库,以及在 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.com | https://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 通过同样的场景生成,不需要额外配置。在一次运行里:
- Skill 调用
model.generate,带上sceneKey: "image-creation"或"video-creation"和一个saveTo路径。使用async: true时 Skill 先得到任务句柄,之后用同一个saveTo调用model.collect。 - 写在
saveTo的是一份清单,里面指明存储文件。图片或视频本身已经在存储里。 - Skill 用
kind: "image"或"video"和这个路径调用artifact.publish。产物的版本指向这个存储文件,不会重新下载或上传。前提是清单里只有一个文件,文件属于该用户、来自 AI 任务,并且内容类型与发布的类型一致。 - 对话在消息里显示产物:图片显示为预览,视频显示为带控制条的播放器。产物仍然可以在右侧面板打开。
预览授权的有效期是一分钟。视频在播放期间按区间读取,所以加载因授权过期而失败时,播放器重新获取一次授权,并从原位置继续播放。授权仍有效时加载失败,卡片改为显示打开和下载操作。
如果需要画幅选择和每次运行的张数上限,安装图片 Agent。
验证
-
在
/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"}' -
在
/app/ai/<taskId>上,任务从running变为succeeded,事件里有Generated output imported to storage. -
图片出现在
/app/assets中该用户的生成文件里。 -
用
video-creation和"mediaType":"video"再做一遍。 -
如果安装了 agent,在
/app/agent里请求一张图或一段视频。结果显示在消息里,页面停留超过一分钟后视频仍能播放。 -
在仓库里,
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 发布。