本文档介绍智能体API接口的输入输出参数。调用该接口可获取智能体的大模型回复、参考资料、多模态卡片数据，实现追问、引用角标、图文混排等高级产品功能，您可根据这些数据自定义UI效果。
基于火山引擎IAM的AK/SK鉴权ServiceName=volc_torchlight_api
接口验签及请求公共参数逻辑参考火山引擎官网统一规范，可按照如下签名方法和demo，进行实现：
签名方法：签名方法--API签名调用指南-火山引擎
签名过程demo：签名过程Demo--API签名调用指南-火山引擎
签名源码示例：签名源码示例--API签名调用指南-火山引擎
若使用主账号 (强烈不建议，主账号权限过大) 接入，可跳过此步骤，忽略此前提；
若为子账号接入，需要首先登陆控制台，开通接口访问权限；否则会报错100013:AccessDenied错误;
开通接口权限步骤：
使用火山引擎控制台主账号，登录控制台；
点击用户头像进入访问控制模块，在用户模块点击管理按钮进入子账号权限管理界面；
切换到权限TAB，点击添加权限按钮，在搜索栏输入“TorchlightApiFullAccess”权限，并选中确认；
若有多个子账号访问平台，需对每个子账号进行相应权限配置。
| 通信协议 | HTTPS |
|---|---|
| 请求方法（Method） | POST |
| 域名（Host） | mercury.volcengineapi.com |
| Service | volc_torchlight_api |
| Version | 2024-01-01 |
| Action | ChatCompletion |
| Region | cn-north-1 |
| ContentType | application/json |
| URL | https://mercury.volcengineapi.com?Action=ChatCompletion&Version=2024-01-01 |
|---|---|
| Method | POST |
| Content-Type | application/json |
ChatCompletionRequest
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| bot_id | String | 是 | 智能体ID，在控制台创建智能体后获取，控制台地址：https://console.volcengine.com/ask-echo/my-agent |
messages | Array[Message] | 是 |
|
| stream | Boolean | 否 | 是否启用流式响应。默认 false |
| user_id | String | 否 | 用户身份标识 |
| device_id | String | 否 | 设备身份标识 |
knowledge | String | 否 | 可以传入智能体未获取到的知识信息，增强问答效果。
|
location_info | LocationInfo | 否 | 当前地理位置信息
|
Message
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
role | String | 是 |
|
content | String/Object | 是 | 对话消息列表
|
LocationInfo
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| province | String | 否 | 当前位置所在省份，建议传，有助于提升智能体返回效果 |
| city | String | 否 | 当前位置所在市，建议传，有助于提升智能体返回效果 |
| district | String | 否 | 当前位置所在区，建议传，有助于提升智能体返回效果 |
| town | String | 否 | 当前位置所在县/街道，建议传，有助于提升智能体返回效果 |
| longitude | Number | 否 | 当前位置经度 |
| latitude | Number | 否 | 当前位置纬度 |
ChatCompletionResponse
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| id | String | 是 | 响应的唯一标识符 |
object | String | 是 | 响应对象的类型
|
| choices | Array[Choice] | 是 | 返回项 |
| created | Number | 是 | 响应创建时间戳(秒) |
| references | Array[Reference] | 否 | 大模型参考内容，流式只在首帧出 |
| follow_ups | Array[FollowUp] | 否 | 追问内容 |
Choice
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
delta | Object | 否 | 流式响应使用。包含增量更新内容
|
| message | Object | 否 | 非流式响应使用。包含完整的回复消息，和delta结构一致 |
finish_reason | String | 是 | 生成终止的原因，可能的值：
|
| index | Number | 是 | 当前选择的索引编号。在单个响应中通常为 0，在多选择配置下可能有多个索引 |
Reference
| 字段名 | 类型 | 必须 | 说明 |
|---|---|---|---|
| id | String | 是 | 引用内容唯一ID |
| source_type | String | 是 | 内容源 |
| site_name | String | 否 | 站点名，与SourceType存在映射，枚举场景优先使用SourceType |
| title | String | 否 | 标题 |
publish_time | Number | 否 | 发布时间，UnixSecond时间戳 |
| url | String | 否 | 落地页，部分搜索引擎结果没有URL |
cover_image | Object | 否 | 封面图
|
FollowUp
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item | String | 是 | 相关搜索词 |
Cards
| 卡片类型 | 响应示例 |
|---|---|
墨迹天气 |
|
抖音视频 |
|
{ "bot_id": "7429717161499017747", "user_id": "108210528", "messages": [ { "role": "system", // systemprompt "content": "你是一个AI助手，你的名字是中国芯，你没有性别..." }, { "role":"user", // 历史对话 "content":"周杰伦有什么歌" }, { "role":"assistant", "content":"周杰伦唱过《稻香》《叶惠美》《东风破》《菊花台》" }, { "role": "user", // 当前问题 "content": "最后一首讲了什么" } ] "knowledge":"正在播放孙燕姿的《天黑黑》，正在驾驶2024款问界M9MAX五座版", "location_info":{ //当前位置 "province": "陕西省", "city": "西安市", "district": "未央区", "town": "玄武路", "longitude": 108.962354, //经度 "latitude": 34.303007 //维度 }, "stream": true // 流式输出 }
{ "id": "202412041530171E9F2E4A5A8B75F4E8A0", "object": "chat.completion", "choices": [ { "delta": null, "message": { "role": "assistant", "content": "据 12 月 2 日消息，荣耀将于当晚 19 点举办荣耀 300 系列环球旅拍新品发布会，正式发布该系列智能手机，其中包括荣耀 300 Ultra。近日，有爆料人士汇总其配置信息：搭载降频版高通骁龙 8 Gen 3 移动平台（主频 3.0GHz，该平台于 10 月 25 日发布），配备 1.5K OLED 护眼屏幕，后置三摄（含 5000 万像素大底主摄和潜望式长焦摄像头），前置 5000 万像素双摄，支持 100W 有线及无线充电，配备荣耀巨犀玻璃，支持卫星通信技术，采用塑料中框。不少人认为其起售价格可能在 4000 元左右。 " }, "finish_reason": "stop", "index": 0 } ], "created": 1733297420, "references": [ { "id": "7443704254352720423", "source_type": "toutiao_article", "site_name": "头条图文", "title": "荣耀300 Ultra配置汇总 今晚正式发布 起售价4000元？", "publish_time": 1733122470, "url": "[https://open.toutiao.com/a7443704254352720423/?biz_log=BsCxB16MLUHCxRS3RVcWnYJQgmNcdJybTBD1x9hGNVSYmkJfChvDHwNwHyEWAfeqYqLqKi9UPm4BarBbpc6nXatYRZhUnfncGiXiZKEwVrY2eGYgAbskZeosd2jyLy9fcRBeGTQ6naQAjjgoU&group_id=7443704254352720423&label=torchlight&utm_source=suntest_1_default_content](https://open.toutiao.com/a7443704254352720423/?biz_log=BsCxB16MLUHCxRS3RVcWnYJQgmNcdJybTBD1x9hGNVSYmkJfChvDHwNwHyEWAfeqYqLqKi9UPm4BarBbpc6nXatYRZhUnfncGiXiZKEwVrY2eGYgAbskZeosd2jyLy9fcRBeGTQ6naQAjjgoU&group_id=7443704254352720423&label=torchlight&utm_source=suntest_1_default_content)", "cover_image": { "url": "[https://p6-open-sign.onewsimg.com/tos-cn-i-tjoges91tu/c86d4a5edd1cf88072cae08c9d7df687~tplv-obj.jpeg?lk3s=2c3e0c70&scene=torchlight&x-expires=1796369419&x-signature=X96H3jMCpFIUyvh5KDRO8ftCu4I%3D](https://p6-open-sign.onewsimg.com/tos-cn-i-tjoges91tu/c86d4a5edd1cf88072cae08c9d7df687~tplv-obj.jpeg?lk3s=2c3e0c70&scene=torchlight&x-expires=1796369419&x-signature=X96H3jMCpFIUyvh5KDRO8ftCu4I%3D)", "width": 600, "height": 518 } } ], "follow_ups": [ { "item": "荣耀300 Ultra的续航能力如何?" }, { "item": "荣耀300 Ultra的拍照效果怎样?" }, { "item": "荣耀300 Ultra的游戏性能怎么样?" } ], "usage": { "prompt_tokens": 2276, "completion_tokens": 229, "total_tokens": 2505 }, "cards": [ { "card_type": "video", "video_card": { "id": "7439578236809380406", "source_type": "xigua_feed_video", "site_name": "西瓜视频", "title": "荣耀CEO赵明：2027年手机或搭载千亿参数大模型", "cover_image": { "url": "[https://p6-open-sign.onewsimg.com/tos-cn-i-tjoges91tu/1befd816f6f672de911e5c20df4e8979~tplv-obj.jpeg?lk3s=2c3e0c70&scene=torchlight&x-expires=1796369420&x-signature=CjnAmmkSshOJTYE%2BxVuNp7vMS1c%3D](https://p6-open-sign.onewsimg.com/tos-cn-i-tjoges91tu/1befd816f6f672de911e5c20df4e8979~tplv-obj.jpeg?lk3s=2c3e0c70&scene=torchlight&x-expires=1796369420&x-signature=CjnAmmkSshOJTYE%2BxVuNp7vMS1c%3D)", "width": 1600, "height": 900 }, "url": "[https://open.toutiao.com/video/url/?param=CvAQAP9jejHRznz7DG9aNf78cnQmacQPHJgq714Zb1kdudmrzg7xCVAFHACqJNVeYLB3z6vh7ReiFCU5gksQzBBdWFKcNTtfNvmMxvUKQGRqLHshkFesmojiWGSuQr568Her2iwjhmHJTfqFmygBnSLB1gHvbBWEQeH3QRzTLp5UbJZZXgAHUGiaRG3WP1rCqNfWSBbUaRquPEACdWNrR6&partner=suntest_1_default_content&version=3](https://open.toutiao.com/video/url/?param=CvAQAP9jejHRznz7DG9aNf78cnQmacQPHJgq714Zb1kdudmrzg7xCVAFHACqJNVeYLB3z6vh7ReiFCU5gksQzBBdWFKcNTtfNvmMxvUKQGRqLHshkFesmojiWGSuQr568Her2iwjhmHJTfqFmygBnSLB1gHvbBWEQeH3QRzTLp5UbJZZXgAHUGiaRG3WP1rCqNfWSBbUaRquPEACdWNrR6&partner=suntest_1_default_content&version=3)", "width": 1600, "height": 900, "duration": 25 } } ] }
data:{"id":"2024120415414954BC859A628D38329176","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"据"},"message":null,"finish_reason":"","index":0}],"created":1733298110,"references":[{"id":"7443704254352720423","source_type":"toutiao_article","site_name":"头条图文","title":"荣耀300 Ultra配置汇总 今晚正式发布 起售价4000元？","publish_time":1733122470,"url":"https://open.toutiao.com/a7443704254352720423/?biz_log=BsCxB16MLUHCxRS3RVcWnYJQgmNcdJybTBD1x9hGNVSYmkJfChvDHwNwHyEWAfeqYqLqKi9UPm4BarBbpc6nXatYRZhUnfncGiXiZKEwVrY2eGYgAbskZeosd2jyLy9fcRBeGTQ6naQAjjgoU&group_id=7443704254352720423&label=torchlight&utm_source=suntest_1_default_content","cover_image":{"url":"https://p6-open-sign.onewsimg.com/tos-cn-i-tjoges91tu/c86d4a5edd1cf88072cae08c9d7df687~tplv-obj.jpeg?lk3s=2c3e0c70&scene=torchlight&x-expires=1796369419&x-signature=X96H3jMCpFIUyvh5KDRO8ftCu4I%3D","width":600,"height":518}}],"cards":[{"card_type":"video","video_card":{"id":"7439578236809380406","source_type":"xigua_feed_video","site_name":"西瓜视频","title":"荣耀CEO赵明：2027年手机或搭载千亿参数大模型","cover_image":{"url":"https://p6-open-sign.onewsimg.com/tos-cn-i-tjoges91tu/1befd816f6f672de911e5c20df4e8979~tplv-obj.jpeg?lk3s=2c3e0c70&scene=torchlight&x-expires=1796369420&x-signature=CjnAmmkSshOJTYE%2BxVuNp7vMS1c%3D","width":1600,"height":900},"url":"https://open.toutiao.com/video/url/?param=CvAQAP9jejHRznz7DG9aNf78cnQmacQPHJgq714Zb1kdudmrzg7xCVAFHACqJNVeYLB3z6vh7gTbxQGrZnMxaceVyq3yuH9t1n4n79xuYAVQYXJpSLJTZfRaqBUw6QNzdZQSDvn5mnMWmHXrCVn6guxX8S2zSV9jdy1rGeUcE66EKKcx2V3GAmeU4MPKnv2QaJAFdiCNDg2jMBDbEZs7T6&partner=suntest_1_default_content&version=3","width":1600,"height":900,"duration":25}}]} data:{"id":"2024120415414954BC859A628D38329176","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":" "},"message":null,"finish_reason":"","index":0}],"created":1733298110,"references":null} data:{"id":"2024120415414954BC859A628D38329176","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"1"},"message":null,"finish_reason":"","index":0}],"created":1733298110,"references":null} ... data:{"id":"2024120415414954BC859A628D38329176","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":""},"message":null,"finish_reason":"stop","index":0}],"created":1733298110,"references":null} data:{"id":"2024120415414954BC859A628D38329176","object":"chat.completion.chunk","choices":null,"created":1733298110,"references":null,"follow_ups":[{"item":"荣耀300 Ultra的无线充电速度有多快?"},{"item":"荣耀300 Ultra的卫星通信技术有何特点?"},{"item":"荣耀300 Ultra的1.5K OLED护眼屏幕效果怎样?"}]} data:{"id":"2024120415414954BC859A628D38329176","object":"chat.completion.chunk","choices":null,"created":1733298110,"references":null,"usage":{"prompt_tokens":2276,"completion_tokens":247,"total_tokens":2523}} data:[DONE]
{ "id": "202503071408427F84E1F2F5F44FDA0FF6", "object": "chat.completion.chunk", "choices": [ { "delta": { "role": "assistant", "content": "\n", "tool_calls": null }, "message": null, "finish_reason": "", "index": 0 } ], "created": 1741327738, "references": null }
说明：在总结输出中插入引用标记，指示文本来源于哪个参考资料。
格式：[ref_x]，其中 x 为参考资料的编号。
生效场景：流式输出、非流式输出
开启方法： 控制台开启开关
注意事项：
说明：在输出内容中穿插图片，以Markdown格式呈现。
生效场景：仅支持流式输出
开启方法： 控制台开启开关
输出格式：
文本内容以常规方式输出
图片以Markdown语法输出：
图片会作为独立帧返回
注意事项：
返回数据参考：
// 普通文本帧 { "id": "202503121053195DDBF4E949D2ECF224C4", "object": "chat.completion.chunk", "choices": [ { "delta": { "role": "assistant", "content": "餐厅", "tool_calls": null }, "message": null, "finish_reason": "", "index": 0 } ], "created": 1741748005, "references": null } // 图片插入帧 { "id": "202503121053195DDBF4E949D2ECF224C4", "object": "chat.completion.chunk", "choices": [ { "delta": { "role": "assistant", "content": "\n\n", "tool_calls": null }, "message": null, "finish_reason": "", "index": 0 } ], "created": 1741748006, "references": null }
网关错误：
此接口基于火山引擎TOP网关发布，如果遇到网关层报错（例如验签错误），我们将返回火山引擎TOP网关错误，响应格式如下：
{ "ResponseMetadata": { "RequestId": "202210271151020102121450321B8D2A21", "Action": "ScanSyncArticles", "Version": "2023-01-01", "Service": "volc_torchlight_api", "Region": "cn-north-1", "Error": { "CodeN": 100010, "Code": "SignatureDoesNotMatch", "Message": "The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details." } } }
业务错误：
{ "error": { "message": "错误的详细描述信息", "type": "错误类型", "code": "具体错误代码", "param": "可选，导致错误的参数名称" } }
当流式输出过程中出现错误时，错误信息将在以 data: 开头的数据块中返回。字段解释如下：
| 字段 | 类型 | 描述 | 必须 | 备注 |
|---|---|---|---|---|
type | String | 错误类型标识符 | 是 |
|
| code | String | 具体错误代码 | 是 | 提供具体错误码，或者和type一致 |
| message | String | 错误描述 | 是 | 提供具体错误描述，或者和type一致 |
| param | String | 导致错误的参数名称 | 否 | 只有参数错误时会返回 |
// 认证错误 { "error": { "code": "invalid_api_key", "message": "API key expired or invalid", "type": "authentication_error", "param": null } } // 请求参数错误 { "error": { "code": "invalid_parameter", "message": "stream requires bool type", "type": "validation_error", "param": "stream" } } // 速率限制 { "error": { "code": "llm_rate_limit_exceeded", "message": "llm_rate_limit_exceeded", "type": "rate_limit_error", "param": null } }
RequestID是每次API请求的唯一标识，当出现了无法自助解决的问题时，可以提供请求的RequestID，我们将协助进行故障排查。
RequestID格式为：20241211184452633DBFC9B5FB220BDEBF。
以下为获取requestID的几种方式：
响应体ResponseMetadata-RequestID，具体响应结构可以参见文档：API公共错误码
响应头X-Tt-Logid