开场白
接口说明
用户首次或者复访时,分身主动发送的欢迎语。创作者可选实现。
基本信息
- •接口路径:/avatar/serv/onboarding
- •接口方法:POST
请求参数
参数名称 | 参数类型 | 必须参数 | 备注 |
» biz_context | object(common/common_info.BizContext) | 选填 | 当前业务身份&场景参数,不需要关注,上游透传 |
»» biz_id | string | 选填 | 标记当前请求来自于C端场景, format:format im_single_chat:私信 |
» common_context | object(avatar_serv.CommonContext) | 选填 | 通参,上游透传 |
»» user_info | object(common/common_info.UserInfo) | 选填 | 用户信息 |
»»» open_id | string | 选填 | C端发起对话的抖音用户的ID,上游自动传入,不需要关注 |
»» avatar_info | object(common/common_info.AvatarInfo) | 选填 | 分身信息 |
»»» avatar_app_id | string | 选填 | 分身的抖音开放平台创建后的身份标识,app_id |
»» traffic_source | object(common/common_info.TrafficSource) | 选填 | 场景流量来源标记,上游自动传入,下游调用原子能力时,可能需要透传;开发者不关注具体值 |
»»» source | string | 选填 | 场景流量来源标记,上游自动传入,下游调用原子能力时,可能需要透传;开发者不关注具体值 |
»»» enter_from | string | 选填 | 场景流量来源标记,上游自动传入,下游调用原子能力时,可能需要透传;开发者不关注具体值 |
»»» traffic_type | string | 选填 | 场景流量来源标记,上游自动传入,下游调用原子能力时,可能需要透传;开发者不关注具体值 |
» message | object(avatar_serv.Message) | 选填 | 用户当前发送的 query |
»» conversation_id | string | 选填 | 当前会话ID,上游自动传入,不需要关注 |
»» message_id | string | 选填 | 用 户输入query的message_id;上游自动传入,不需要关注 |
»» role | enum(common/common_info.Role) | 选填 | 枚举值content.role system=1, user=2, assistant=3; |
»» content | object(avatar_serv.MessageContent) | 选填 | 用户当前发送的 内容 |
»»» content | string | 选填 | 用户当前发送的 内容的具体值 |
»»» type | enum(common/content.ContentType) | 选填 | 枚举值content.type 0表示纯文本,目前仅支持纯文本 |
» chat_context | object(avatar_serv.ChatContext) | 选填 | 用户和分身的聊天的上下文 |
»» message_context | list<avatar_serv.Message> | 选填 | 用户和分身的历史聊天,按照时间顺序传入,最 大20轮 |
»»» content | object(avatar_serv.MessageContent) | 选填 | |
»»»» type | enum(common/content.ContentType) | 选填 | 枚举值content.type 0表示纯文本;3表示开平卡片 |
»»»» content | string | 选填 | 消息的具体内容 |
»»» conversation_id | string | 选填 | 消息所属会话ID,上游自动传入,不需要关注 |
»»» message_id | string | 选填 | 消息的message_id;上游自动传入,不需要关注 |
»»» role | enum(common/common_info.Role) | 选填 | 枚举值content.role,发送当前消息的角色 |
» reply_message_id | string | 选填 | 本次用户query的回答的message_id,上游自动传入,不需要关注 |
请求示例
{ "message": { "conversation_id": "xb17Mth7hy", // 当前会话ID,上游自动传入,不需要关注 "message_id": "hIPrroEYEF", // 用户输入query的message_id;上游自动传入,不需要关注 "role": 1, // 枚举值content.role system=1, user=2, assistant=3; "content": { "type": 0, // 枚举值content.type 0表示纯文本;3表示开平卡片 "content": "z76ioP7uex" } }, "chat_context": { "message_context": [ // 用户和分身的历史聊天,按照时间顺序传入,最大20轮 { "conversation_id": "y5Zu76IcCk", // 消息的会话ID,上游自动传入,不需要关注 "message_id": "zPONEU9W4m", // 消息的message_id;上游自动传入,不需要关注 "role": 2, // 枚举值content.role system=1, user=2, assistant=3; "content": { "type": 0, "content": "S1klHSsHmy" }, "created_at": 4904873903809125974 } ] }, "reply_message_id": "fG3yPCUzB7", // 本次请求的回答的message_id,上游自动传入,不需要关注 "biz_context": { "biz_id": "bYPxF7HEAM" // 场景枚举值,可根据此标记,定制分身的差异化逻辑 }, // format、私信、ai搜、官方号 "common_context": { "user_info": { "open_id": "4106557274961385626", // C端发起对话的抖音用户的ID,上游自动传入,不需要关注 }, "avatar_info": { "avatar_app_id": "2186328463960574138" // 分身的开平app_id }, "traffic_source": { // 场景流量来源标记,上游自动传入,下游调用原子能力时,可能需要透传;开发者不关注具体值 "source": "nIpNzvSZY7", "enter_from": "RiPRNnnGTC", "traffic_type": "0spfr3Ravm" } } }
响应参数
参数名称 | 参数类型 | 必须参数 | 备注 |
» stream_finish | bool | 选填 | 在流式返回的最后一个chunk时,设置为true,表示请求已完成 |
» content | object(avatar_serv.CopilotContent) | 选填 | 本次请求返回的内容 |
»» type | enum(common/content.ContentType) | 选填 | 内容类型 枚举值,参考content.type, 1-纯文本;3-开平卡片; |
»» content | string | 选填 | 返回内容的具体值,不同类型不一样; |
»» role | enum(common/common_info.Role) | 选填 | 枚举值,发送当前回答的角色; 参考content.role; |
»» seg_finish | bool | 选填 | 当前分段是否回答完成,set_finish=true时表示当前分段结束,同一条消息的不同分段,客户端会分气泡展示 |
»» seg_type | enum(common/content.SegType) | 选填 | 参考枚举值:seg_type |
» trace_info | object(common/common_info.TraceInfo) | 选填 | debug信息 |
»» trace_info | string | 选填 | 仅在debug场景使用的调试信息,可选填充 |
响应示例
// 其中一个chunk的协议如下; { "data": { "stream_finish": true, // 在流式返回的最后一个chunk时,设置为true,表示请求已完成 "content": { "type": 1, // 枚举值,参考content.type, 1-纯文本;3-开平卡片;具体的卡片数据打包依赖开平; "content": "XIk8zUoXaC", "role": 0, // 枚举值,参考content.role; 0-unknown, 1-system, 2-user, 3-role "seg_finish": true, // 当前分段是否回答完成;针对每个seg,客户端会分开展示 "seg_type": 0, // 参考枚举值:seg_type }, "trace_info": { "trace_info": "4038savAxJ" // 仅在debug场景使用的调试信息,可选填充 } }, "err_no": 12, "err_msg": "模型请求失败", "log_id": "202410112208352E4817F01CFBCA1F842D" } // 流式返回举例如下: 0000d1 {"err_no":0,"err_msg":"success","data":{"stream_finish":false,"content":{"type":0,"content":"你好,","role":3,"seg_finish":false,"seg_type":1},"trace_info":{"trace_info":"{\"logid\":\"\"}"}}} 0000d0 {"err_no":0,"err_msg":"success","data":{"stream_finish":false,"content":{"type":0,"content":"我是","role":3,"seg_finish":false,"seg_type":1},"trace_info":{"trace_info":"{\"logid\":\"\"}"}}} 0000d6 {"err_no":0,"err_msg":"success","data":{"stream_finish":false,"content":{"type":0,"content":"赵小小,","role":3,"seg_finish":false,"seg_type":1},"trace_info":{"trace_info":"{\"logid\":\"\"}"}}} 0000e5
错误码
http_status=200
。错误码(err_no) | 错误消息(err_msg) | 说明 |
0 | 空 | err_no=0时表示当前请求正常,上游服务会解析data中的内容,并走正常逻辑进行业务处理 |
-1 | 业务可自行填充 | err_no=-1 是默认错误码;流式返回过程中,若某个chunk返回的err_no=-1,上游会认为当前请求异常,断开链接并给用户返回兜底回答 |
更多错误类型处理待开放... |
枚举值
content.type
取值 | 含义 | 说明 |
1 | 纯文本 | 模型返回的纯文本 |
2 | format协议 | 系统预制,开发者不需要感知 |
3 | 开平卡片 | 抖音开放平台后续会为开发者提供C端复杂卡片渲染 |
content.role
取值 | 含义 | 说明 |
0 | unknown | 非法值 |
1 | system | |
2 | user | |
3 | assistant | |
seg_type
取值 | 含义 | 说明 |
0 | 表示模型针对query的回答 | |
1 | 追问词 |