Media AI Agent API Reference
Endpoint: https://smartmedia.vod-qcloud.com/agui认证: VOD ApiToken / Bearer
VOD 是 Media AI Agent 的认证、消息、流式响应与执行管理规范。视频制作与媒体问答均通用适用。
调用规范
基本信息
| 项目 | 取值 |
|---|---|
| 主机 | smartmedia.vod-qcloud.com |
| 认证 | Authorization: Bearer $VOD_API_TOKEN |
| 请求格式 | application/json |
| 执行响应 | SSE / AG-UI 事件 |
| 执行 / 恢复 | POST /agui/chat |
| 消息历史 | POST /agui/history |
| 取消执行 | POST /agui/cancel |
调用准备
指定 VOD 应用的 SubAppId,先签发 API 密钥。签发密钥需以 TC3 签名调用 vod.intl.tencentcloudapi.com 的 CreateAigcApiToken。
{
"SubAppId": 123456789
}将响应中的 ApiToken 用作 Agent 请求的 Bearer 密钥。密钥与所选应用绑定,通过 fileId 传入的 VOD 素材也必须位于同一应用中。外部素材可通过 URL 传入。
密钥的签发与管理请参考 VOD API 密钥签发。签发密钥所用的 TC3 签名不要放进 Agent 请求体中。
API 列表与请求参数
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
threadId | 必填 | String | 会话 ID。同一会话共享上下文 |
runId | 必填 | String | 当前执行的唯一 ID |
messages | 必填 | Array | 用户消息或外部工具结果 |
forwardedProps | 必填 | Object | 场景、模型及执行选项 |
tools | 可选 | Array | 由客户端执行的外部工具 |
resume | 可选 | Array | 待审批工具的审批 / 拒绝结果 |
执行选项
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
forwardedProps.model | 可选 | String | Vega Agent 模型 ID |
forwardedProps.scenario_name | 必填 | String | video-mixcut / video-qa |
forwardedProps.approval_mode | 可选 | String | never / level:high。默认值 never |
forwardedProps.database | 可选 | String | video-qa 的知识库名称。默认值 default |
消息
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
messages.role | 必填 | String | 用户输入 user / 外部工具结果 tool |
messages.content | 必填 | String / Array | 文本或 ContentPart 数组 |
messages.toolCallId | 条件必填 | String | 为 role: tool 时的原始工具调用 ID |
素材输入
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
type | 必填 | String | text / mixcut_assets |
text | 条件必填 | String | type: text 的制作指令 |
metadata | 条件必填 | Object | type: mixcut_assets 的素材信息 |
metadata.attachments | 条件必填 | Array | 素材列表 |
metadata.attachments.url | 条件必填 | String | 外部素材 URL。与同一项的 fileId 二选一 |
metadata.attachments.fileId | 条件必填 | String | VOD 文件 ID。与同一项的 url 二选一 |
响应与执行流程
响应事件
| 事件 | 说明 |
|---|---|
RUN_STARTED | 执行开始 |
TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END | 回答消息开始 / 追加文本 / 结束 |
REASONING_START / REASONING_END | 推理步骤开始 / 结束 |
REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENT / REASONING_MESSAGE_END | 推理消息开始 / 追加内容 / 结束 |
TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END | 工具调用开始 / 追加参数 / 调用信息传递完成 |
TOOL_CALL_RESULT | 工具执行结果 |
RUN_FINISHED | 当前执行结束,或等待审批 / 外部工具结果 |
RUN_ERROR | 执行错误 |
MESSAGES_SNAPSHOT | 历史记录查询的全量消息快照 |
事件数据示例
将 SSE 的 data 字段解析为 JSON。以下是执行开始事件的数据。
{
"type": "RUN_STARTED",
"timestamp": 1784102011155,
"threadId": "thread-001",
"runId": "run-001"
}文本按 messageId 逐段累积 delta。
{
"type": "TEXT_MESSAGE_CONTENT",
"timestamp": 1784102019050,
"messageId": "msg-002",
"delta": "正在根据所选素材准备剪辑结构。"
}工具参数按 toolCallId 累积 TOOL_CALL_ARGS.delta 后再解析为 JSON。TOOL_CALL_END 表示调用信息传递结束,工具执行结果在 TOOL_CALL_RESULT 中确认。
执行状态区分
| 接收状态 | 处理方式 |
|---|---|
RUN_FINISHED + outcome.type: interrupt | 展示待审批项,并通过 resume 传递决定 |
调用外部工具后的 RUN_FINISHED | 由客户端执行工具后传递结果 |
没有待处理审批 / 外部工具调用的 RUN_FINISHED | 当前执行结束。从消息与工具结果中确认最终产物 |
RUN_ERROR | 记录错误内容与执行标识,并标记失败状态 |
历史记录查询
curl -N -sS https://smartmedia.vod-qcloud.com/agui/history \
-H "Authorization: Bearer $VOD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"threadId": "thread-001",
"runId": "history-001",
"forwardedProps": {
"scenario_name": "video-mixcut"
}
}'传入 threadId 与查询请求的 runId。响应为 SSE,会话的全量消息包含在 MESSAGES_SNAPSHOT 事件的 messages 中。重新连接时用该快照恢复界面。历史记录查询响应中的 RUN_FINISHED 表示查询结束。
取消执行
curl -sS https://smartmedia.vod-qcloud.com/agui/cancel \
-H "Authorization: Bearer $VOD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"threadId": "thread-001",
"runId": "cancel-001",
"forwardedProps": {
"scenario_name": "video-mixcut"
}
}'仅关闭浏览器或断开 SSE 连接并不会取消执行。如需中断,请调用取消 API。
错误与调用限制
请一并确认响应的 HTTP 状态、错误码及请求标识。认证与权限类错误请在确认配置后重新请求;若已创建任务或资源,请在重新提交前查询当前状态。各 API 的限制与错误码请参考下方相关文档。
请求示例
请求示例
curl -N -sS https://smartmedia.vod-qcloud.com/agui/chat \
-H "Authorization: Bearer $VOD_API_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.json将两段视频拼接请求的 JSON 保存为 request.json。完整配置请参考 Vega Agent 请求示例。
结果与资源管理
可选功能
视频拼接示例无需以下配置即可运行。需要审批步骤或对接外部系统时使用。
审批与恢复
approval_mode: level:high 会在执行高风险工具前请求审批。以下是待审批事件的数据示例。
{
"type": "RUN_FINISHED",
"threadId": "thread-001",
"runId": "run-001",
"outcome": {
"type": "interrupt",
"interrupts": [
{
"id": "interrupt-001",
"reason": "tool_call",
"message": "正在应用剪辑方案并渲染成片。",
"toolCallId": "call-001",
"responseSchema": {
"type": "object",
"properties": {
"feedback": {
"type": "string"
}
}
}
}
]
}
}恢复参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
resume.interruptId | 必填 | String | 审批请求的 interrupts.id |
resume.status | 必填 | String | 批准 resolved / 拒绝 cancelled |
resume.payload | 可选 | Object | 关于该决定的补充信息 |
resume.payload.feedback | 可选 | String | 修改请求或拒绝理由 |
在同一 threadId 中以新的 runId 恢复执行。保持首次请求的 approval_mode 与 scenario_name,且每个待审批 ID 只能指定一次。
{
"threadId": "thread-001",
"runId": "run-002",
"messages": [
{
"role": "user",
"content": ""
}
],
"forwardedProps": {
"model": "wand-vega-agent-1.0-pro",
"scenario_name": "video-mixcut",
"approval_mode": "level:high"
},
"resume": [
{
"interruptId": "interrupt-001",
"status": "resolved"
}
]
}外部工具
外部工具是由 Agent 决定调用、客户端负责执行的函数。在 tools 中注册名称、说明与 JSON Schema。
{
"name": "lookup_product",
"description": "按商品编码查询已审核的商品说明。",
"parameters": {
"type": "object",
"properties": {
"productCode": {
"type": "string"
}
},
"required": [
"productCode"
]
}
}将该对象放入请求的 tools 数组中。收到工具调用后,校验已注册函数的输入并执行,然后按以下格式传递结果。保持相同的 threadId、工具定义与场景。
{
"threadId": "thread-001",
"runId": "run-003",
"messages": [
{
"role": "tool",
"toolCallId": "call-ext-001",
"content": "商品编码 P100:便携式无线音箱。颜色为黑色。"
}
],
"forwardedProps": {
"model": "wand-vega-agent-1.0-pro",
"scenario_name": "video-mixcut",
"approval_mode": "never"
},
"tools": [
{
"name": "lookup_product",
"description": "按商品编码查询已审核的商品说明。",
"parameters": {
"type": "object",
"properties": {
"productCode": {
"type": "string"
}
},
"required": [
"productCode"
]
}
}
]
}等待外部工具结果也会通过不带 outcome 的 RUN_FINISHED 传递。请一并确认是否存在未处理的外部工具调用。