本文档介绍智能体API接口的输入输出参数。调用该接口可获取智能体的大模型回复、参考资料、多模态卡片数据，实现追问、引用角标、图文混排等高级产品功能，您可根据这些数据自定义UI效果。

提供APIKey接入和TOP网关接入两种方式，两种接入方式有不同的URL。

APIKey接入(推荐)

1. 获取API Key

   1. 打开并登录联网问答智能体-APIKey 管理。

   2. 单击创建API Key按钮。

   3. 在弹出的名称文本框中填写API Key 名称，单击创建。

   说明：请妥善保存好API Key，强烈建议您不要将其直接写入到调用模型的代码中。

2. 签名构造

API Key 签名鉴权方式要求在 HTTP 请求 header 中按如下方式添加 Authorization:

Authorization: Bearer <API_KEY>

火山引擎TOP网关接入

此接入方式基于火山引擎IAM的AK/SK鉴权，统一使用 ServiceName=volc_torchlight_api

1. 接口验签及请求公共参数逻辑遵循火山引擎官网的统一规范，详情请参见：签名方法--API签名调用指南-火山引擎；

2. 开通账号权限后，可获取AccessKey进行验签，详情请参见：Access Key(密钥)管理--API访问密钥(Access Key)-火山引擎。

注意：

1. 若使用主账号接入，可跳过此步骤，忽略此前提；(使用主账号有权限过大的风险，不建议直接使用)

2. 若使用子账号接入，需要首先登录控制台，开通接口访问权限；否则会报错100013:AccessDenied错误;

3. 开通接口权限步骤：

   1. 使用火山引擎控制台主账号，登录控制台；

   2. 点击用户头像进入访问控制模块，在用户模块点击管理按钮进入子账号权限管理界面；

   3. 切换到权限TAB，点击添加权限按钮，在搜索栏输入“TorchlightApiFullAccess”权限，并选中确认；

   4. 若有多个子账号访问平台，需对每个子账号进行相应权限配置。

4. 若使用火山引擎TOP网关接入，需要请求体整体长度不超过8M。

智能体会话

URL

请求体

ChatCompletionRequest

"knowledge":"当前正在驾驶问界M8增程MAX版，车内正在播放音乐《天黑黑》"

Message

"content": "You are a helpful assistant."

"content": [
  {
    "type": "text",
    "text": "What'\''s in this image?"
  },
  {
    "type": "image_url",
    "image_url": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
    }
  }
]

LocationInfo

响应体

ChatCompletionResponse

Choice

Reference

{
    "url": "https://xxx", // 封面图链接
    "width": 123, // 封面图宽，不保证提供
    "height": 123, // 封面图高，不保证提供
}

FollowUp

TokenUsage

请求示例

{
    "bot_id": "7429717161499017747",
    "stream": false,
    "messages": [
        {
            "role": "system",
            "content": "你是智能语音助手,你的名字是韩梅梅，请用普通话回复用户。" //Systemprompt
        },
        {
            "Role": "user",
            "content": "周杰伦有什么歌" //上下文
        },
        {
            "Role": "assistant",
            "content": "周杰伦唱过《稻香》《叶惠美》《东风破》《菊花台》"
        },
        {
            "Role": "user",
            "content": "荣耀手机的最新动态" //当前问题
        }
    ],
    "user_id": "hq53qh6683",
    "knowledge":"当前正在驾驶问界M8增程MAX版，车内正在播放音乐《天黑黑》",
    "location_info":{
        "province": "陕西省",
        "city": "西安市",
        "district": "未央区",
        "town": "玄武路",
        "longitude": 108.962354,
        "latitude": 34.303007
    }
}

响应示例

非流式响应

{
    "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]

引用角标

说明：在总结输出中插入引用标记，指示文本来源于哪个参考资料。
格式：[ref_x]，其中 x 为参考资料的编号。
生效场景：流式输出、非流式输出
开启方法： 控制台开启开关
注意事项：

• 客户端可根据需要自定义处理引用角标的展示效果

图文混排

说明：在输出内容中穿插图片，以Markdown格式呈现。
生效场景：仅支持流式输出
开启方法： 控制台开启开关
输出格式：

• 文本内容以常规方式输出

• 图片以Markdown语法输出：![image](url)

• 图片会作为独立帧返回

注意事项：

• 支持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![北京烤鸭](https://p3-search.byteimg.com/obj/tos-cn-i-qvj2lq49k0/1d9ee205d9554cc9bd4a473d2a33eeea)\n",
                "tool_calls": null
            },
            "message": null,
            "finish_reason": "",
            "index": 0
        }
    ],
    "created": 1741748006,
    "references": null
}

百科划线词

说明：在输出内容中，将自动识别百科词条并以下划线超链接形式在总结中呈现
生效场景：仅支持流式输出
开启方法： 控制台开启开关（控制台即将支持）
输出格式：

• 下划线词条以Markdown语法输出： [百科词条名](百科url)

注意事项：

• 支持Markdown渲染的客户端无需特殊处理

输出关键执行过程

说明： 执行过程中输出关键执行过程，提升端上交互效果
开启方法： 详情见扩展参数-其它控制参数
过程范围：

返回数据参考：

{
    "id": "202503271640468507AA4C950F0039CEA0",
    "object": "chat.completion.chunk",
    "choices": [
        {
            "delta": {
                "role": "assistant",
                "content": "",
                "tool_calls": null,
                "processing_state": {
                  "action": "planning",
                  "description": "正在理解问题"
                }
            },
            "message": null,
            "finish_reason": "",
            "index": 0
        }
    ],
    "created": 1743064848,
    "references": null
}

使用基本功能可不关注。 扩展参数是对于一些特殊场景提供的参数支持。这部分不具有通用性，一般是在特定场景下开白启用。不承诺扩展参数在随意传入情况下的接口稳定返回。

卡片参数

ChatCompletionRequest

ChatCompletionResponse

CardConfig

Card

ImageCard

VideoCard

{
    "url": "https://xxx", // 封面图链接
    "width": 123, // 封面图宽，不保证提供
    "height": 123, // 封面图高，不保证提供
}

WeatherCard

{
 "aqi": 95,
 "city_name": "杭州市",
 "co": "7.0",
 "coc": "0.7",
 "co_aqi": 7,
 "no2": "14.0",
 "no2_aqi": 14,
 "o3": "38.0",
 "o3c": "121.0",
 "o3_aqi": 38,
 "pm10": "67.0",
 "pm10c": "83.0",
 "pm10_aqi": 67,
 "pm25": "95.0",
 "pm25c": "71.0",
 "pm25_aqi": 95,
 "primary_pollutant": "PM2.5",
 "pub_time": "2025-01-22 15:00:00",
 "pubtime": "1737558000000",
 "quality_level": "良",
 "rank": "617/774",
 "so2": "3.0",
 "so2c": "8.0",
 "so2_aqi": 3,
 "value": "95"
}

[
  {
    "aqi": 146,
    "date": "2025-01-21",
    "forecast_time": "2025-01-21",
    "predict_time": "2025-01-21",
    "pub_time": "2025-01-21 00:00:00",
    "publish_time": "2025-01-21 00:00:00",
    "quality_level": "轻度",
    "value": "146"
  },
  ...
]

{
 "comfort": 57,
 "condition": "阴",
 "condition_id": "13",
 "dewpoint": 3,
 "get_time": "2025-01-22 15:45:03",
 "humidity": 43,
 "icon": 2,
 "mslp": 1013,
 "obs_time": "2025-01-22 16:00:08",
 "precip1h": 0,
 "pressure": "1013",
 "real_feel": "16.0",
 "real_feel_num": 16,
 "sunrise": "2025-01-22 06:55:00",
 "sunset": "2025-01-22 17:27:00",
 "sundown": "2025-01-22 17:27:00",
 "temp": 16,
 "tips": "略微偏凉，还是蛮舒适的。",
 "update_time": "2025-01-22 16:00:08",
 "uvi": 2,
 "vis": 6200,
 "weather": "阴",
 "weather_id": 13,
 "wind_degrees": "135",
 "wind_dir": "东南风",
 "wind_level": "1",
 "wind_speed": "0.69",
 "wind_dir_id": 6,
 "wspd": 0.69
}

[
 {
   "get_time": "2025-01-22 14:50:03",
   "humidity": 56,
   "icon_day": 1, //日间天气icon序号
   "icon_night": 31, //夜间天气icon序号
   "moon_down": "2025-01-22 11:20:00",
   "moon_phase": "Last",
   "moon_rise": "2025-01-22 00:16:00",
   "mslp": 1020,
   "pop": 0,
   "predict_date": "2025-01-22",
   "qpf": 0,
   "sun_down": "2025-01-22 17:27:00",
   "sun_rise": "2025-01-22 06:55:00",
   "temp_high": 19,
   "temp_low": 7,
   "update_time": "2025-01-22 13:00:00",
   "uvi": 4,
   "weather_day": "多云",
   "weather_id_day": 8,
   "weather_id_night": 8,
   "weather_night": "多云",
   "wind_degrees_day": 135,
   "wind_degrees_night": 315,
   "wind_dir_day": "东南风",
   "wind_dir_id_day": 8,
   "wind_dir_id_night": 15,
   "wind_dir_night": "西北风",
   "wind_level_day": "2",
   "wind_level_night": "1",
   "wspd_day": 2.4,
   "wspd_night": 0.9
},
...
]

{
    "city_id": "886",
    "country_code": "CN",
    "country_en_name": "中国",
    "country_name": "中国",
    "en_name": "Guangzhou",
    "iana_timezone": "Asia/Shanghai",
    "id": 886,
    "latitude": 23.129173,
    "longtitude": 113.264432,
    "name": "广州市",
    "parent_en_names": "Guangdong Province",
    "parent_names": "广东省",
    "region_en_name": "Asia",
    "region_name": "亚洲",
    "secondary_name": "广东省",
    "time_zone": 8,
    "time_zone_name": "Asia/Shanghai"
}

天气图标取值

MusicCard

{
    "url": "https://xxx", // 封面图链接
    "width": 123, // 封面图宽，不保证提供
    "height": 123, // 封面图高，不保证提供
}

其它控制参数

ChatCompletionRequest

ExtensionOptions

ChatCompletionResponse

错误码

网关错误：
此接口基于火山引擎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: 开头的数据块中返回。字段解释如下：

错误响应

// 认证错误
{
  "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
  }
}

如何获取logid

RequestID是每次API请求的唯一标识，当出现了无法自助解决的问题时，可以提供请求的RequestID，我们将协助进行故障排查。

• RequestID格式为：20241211184452633DBFC9B5FB220BDEBF。

• 以下为获取requestID的几种方式：

  • 响应体ResponseMetadata-RequestID，具体响应结构可以参见文档：API公共错误码

  • 响应头X-Tt-Logid