跳到内容

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。

json
{
  "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可选StringVega Agent 模型 ID
forwardedProps.scenario_name必填Stringvideo-mixcut / video-qa
forwardedProps.approval_mode可选Stringnever / level:high。默认值 never
forwardedProps.database可选Stringvideo-qa 的知识库名称。默认值 default

消息 ​

参数必填类型说明
messages.role必填String用户输入 user / 外部工具结果 tool
messages.content必填String / Array文本或 ContentPart 数组
messages.toolCallId条件必填String为 role: tool 时的原始工具调用 ID

素材输入 ​

参数必填类型说明
type必填Stringtext / mixcut_assets
text条件必填Stringtype: text 的制作指令
metadata条件必填Objecttype: mixcut_assets 的素材信息
metadata.attachments条件必填Array素材列表
metadata.attachments.url条件必填String外部素材 URL。与同一项的 fileId 二选一
metadata.attachments.fileId条件必填StringVOD 文件 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。以下是执行开始事件的数据。

json
{
  "type": "RUN_STARTED",
  "timestamp": 1784102011155,
  "threadId": "thread-001",
  "runId": "run-001"
}

文本按 messageId 逐段累积 delta。

json
{
  "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记录错误内容与执行标识,并标记失败状态

历史记录查询 ​

bash
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 表示查询结束。

取消执行 ​

bash
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 的限制与错误码请参考下方相关文档。

请求示例 ​

请求示例 ​

bash
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 会在执行高风险工具前请求审批。以下是待审批事件的数据示例。

json
{
  "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 只能指定一次。

json
{
  "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。

json
{
  "name": "lookup_product",
  "description": "按商品编码查询已审核的商品说明。",
  "parameters": {
    "type": "object",
    "properties": {
      "productCode": {
        "type": "string"
      }
    },
    "required": [
      "productCode"
    ]
  }
}

将该对象放入请求的 tools 数组中。收到工具调用后,校验已注册函数的输入并执行,然后按以下格式传递结果。保持相同的 threadId、工具定义与场景。

json
{
  "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 传递。请一并确认是否存在未处理的外部工具调用。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages