接口详情
鉴权
字段 | 传参方式 | 类型 | 必传 | 描述 | 示例值 |
Authorization | header | String | 是 | API-Key | Bearer d1**2a |
路由配置
备注：SDK已封装好路由关系，通过SDK调用接口，无需设置接口路由配置。
字段 | 传参方式 | 类型 | 必传 | 描述 | 示例值 |
x-fag-appcode | header | String | 是 | 应用表示，固定为 | |
x-fag-servicename | header | String | 是 | 请求路由标识，不同接口值不一样，映射管理参考 | aca-character-create |
x-fag-servicename 与接口映射关系
接口 | 路径 | x-fag-appcode |
对话（流式） | /v2/api/chat/send | aca-chat-send-sse |
对话（非流式） | /v2/api/chat/send | aca-chat-send |
创建角色 | /v2/api/character/create | aca-character-create |
更新角色 | /v2/api/character/update | aca-character-update |
角色详情 | /v2/api/character/details | aca-character-details |
删除角色 | /v2/api/character/delete | aca-character-delete |
角色查询 | /v2/api/character/search | aca-character-search |
对话消息查询 | /v2/api/chat/message/histories | aca-message-history |
对话消息评价 | /v2/api/chat/rating | aca-message-rating |
系统消息推送 | /v2/api/chat/reminder | aca-chat-reminder |
重置对话 | /v2/api/chat/reset | aca-chat-reset |
万相图片获取 | /v2/api/chat/polling/image | aca-message-history |
角色描述自动生成 | /v2/api/character/auto/desc | aca-polling-image |
kv对抽取 | /v2/api/extract/kv | aca-extract-memory-kv |
summary抽取 | /v2/api/extract/summary | aca-extract-memory-summary |
对话
注意：对话场景非为固定角色对话、非固定角色对话、和助手类对话，不用场景对话，入参有所不同，详细差异请参考接口说明-必填。
接口
POST /v2/api/chat/send
入参
请求头参数
字段 | 传参方式 | 类型 | 必传 | 描述 |
X-AcA-SSE | header | String | 否 | 是否开启流式对话- 开启 - |
请求体参数
参数 | 类型 | 必传 | 说明 |
model | string | 否 | 模型，采用角色已配置的模型，也可传入其他模型名称进行路由 |
parameters | object | 否 | 模型设置 |
parameters.seed | double | 否 | **当使用xingchen-plus-v2默认模型时，每次调用的seed必须不同。**seed生成时，随机数的种子，用于控制模型生成的随机性。如果使用相同的种子，每次运行生成的结果都将相同；当需要复现模型的生成结果时，可以使用相同的种子。seed参数支持无符号64位整数类型。默认值 1683806810 |
parameters.incrementalOutput | boolean | 否 | 是否增量输出，若为true，每次流式输出不包含已输出内容，只对流式接口的输出有效 |
input.messages | array | 是 | 对话历史（按时间正序），可支持自主拼接历史。list中的每个元素形式为{"role":角色, "content": 内容}。角色当前可选值：system、user、assistant，function，其中，仅messages[0]中支持role为system，user、assistant需要交替出现，最后一条为用户提问。 |
input.aca.botProfile | object | 是 | 角色设置 |
input.aca.botProfile.characterId | string | 是 | 固定角色必填 |
input.aca.userProfile | object | 是 | 用户设置 |
input.aca.userProfile.userId | string | 是 | 业务系统用户唯一标识，同一用户不能并行对话，必须待上次对话回复结束后才可发起下轮对话 |
input.aca.userProfile.userName | string | 否 | 对话用户名称 |
input.aca.userProfile.basicInfo | string | 否 | 用户基本信息 |
input.aca.scenario | object | 否 | 角色场景设置 |
input.aca.scenario.description | string | 否 | 场景描述，如当前对话时间为晚上 |
input.aca.context | object | 是 | 对话上下文设置 |
input.aca.context.useChatHistory | boolean | 是 | 必填，且必须为false，false代表不使用平台历史 |
input.aca.functionList | array | 否 | 函数列表 |
function.name | string | 是 | 函数名称，如weather |
function.description | string | 是 | 函数描述，如通过调用天气预报API获取当地天气预报信息 |
function.parameters | object | 是 | 函数参数描述，如 |
注意：模型参数parameters优先级从高到低可以通过接口传入、角色属性配置、和平台默认配置三个方式配置。
返回参数
流式调用返回
参数 | 类型 | 说明 |
requestId | string | 系统生成的标志本次调用的id。 |
success | boolean | 是否成功返回 |
errorCode | int | 错误码 |
errorName | string | 错误名称 |
httpStatusCode | int | http错误码 |
errorMessage | string | 错误消息 |
usage | object | |
usage.userTokens | int | 用户输入的token数 |
usage.inputTokens | int | 本次请求输入内容的 token 数目。在打开了搜索的情况下，输入的 token 数目因为还需要添加搜索相关内容支持，所以会超出客户在请求中的输入。 |
usage.outputTokens | int | 模型生成回复转换为Token后的长度。 |
choices | array | 消息体 |
choices[i].stopReason | string | 完成标识符，已完成为 stop，未完成为 “null” |
choices[i].messages | array | |
message.role | string | 模型role，固定为assistant |
message.content | string | 模型生成消息输出 |
message.meta | object | 消息属性 |
message.meta.hasRisk | boolean | 是否存在安全风险， |
message.functionCall | object | 模型function调用结果 |
message.functionCall.tought | string | 模型规划结果 |
message.functionCall.apiCallList | array | 模型生成的function接口调用信息 |
apiCall.apiName | string | 对应的function名 |
apiCall.parameter | object | 调用该function时应传入的参数 |
非流式调用返回
参数 | 类型 | 说明 |
requestId | string | 系统生成的标志本次调用的id。 |
success | boolean | 是否成功返回 |
errorCode | int | 错误码 |
errorName | string | 错误名称 |
httpStatusCode | int | http错误码 |
errorMessage | string | 错误消息 |
data | object | |
data.usage | object | |
usage.userTokens | int | 用户输入的token数 |
usage.inputTokens | int | 本次请求输入内容的 token 数目。在打开了搜索的情况下，输入的 token 数目因为还需要添加搜索相关内容支持，所以会超出客户在请求中的输入。 |
usage.outputTokens | int | 模型生成回复转换为Token后的长度。 |
data.choices | array | 消息体 |
choices[i].stopReason | string | 完成标识符，已完成为 stop，未完成为 null |
choices[i].messages | array | |
message.role | string | 模型role，固定为assistant |
message.content | string | 模型生成消息输出 |
message.meta | object | 消息属性 |
message.meta.hasRisk | boolean | 是否存在安全风险，true/false |
message.functionCall | object | 模型function调用结果 |
message.functionCall.tought | string | 模型规划结果 |
message.functionCall.apiCallList | array | 模型生成的function接口调用信息 |
apiCall.apiName | string | 对应的function名 |
apiCall.parameter | object | 调用该function时应传入的参数 |
角色管理
创建角色
接口
POST /v2/api/character/create
入参
名称 | 类型 | 是否必传 | 说明 |
name | string | 是 | 角色名称 |
avatar | object | 是 | 角色头像 |
introduction | string | 是 | 角色摘要 |
basicInformation | string | 是 | 角色基本信息，包含人设、经历 |
openingLine | string | 是 | 开场白 |
traits | string | 否 | 强制要求 |
chatExample | string | 否 | 对话示例 |
permConfig | object | 否 | 权限配置 |
permConfig.isPublic | int | 是 | 是否开放角色属性给其他星尘用户查看（1:是，0:否） 说明：当您接入自己的应用使用时，无须打开该开关；请谨慎选择 |
permConfig.allowChat | int | 是 | 开放角色与其他星尘用户聊天（1:是，0:否） 说明：指开放角色与其他星尘web端用户聊天，开启后需申请关闭权限，请谨慎选择 |
permConfig.allowApi | int | 是 | 开放角色API接口允许其他星尘用户调用（1:是，0:否） 说明：如您需要使用其它账号通过API接入该角色，请打开该开关； |
advancedConfig | object | 否 | 高级配置 |
advancedConfig.isRealInfo | boolean | 否 | 是否开启web检索 |
advancedConfig.searchKeyword | string | 否 | web检索关键词 |
advancedConfig.isRealTime | boolean | 否 | 是否使用真实时间 |
advancedConfig.longTermMemories | list | 否 | 长期记忆设置 |
advancedConfig.platformPlugins | list | 否 | 插件列表 |
advancedConfig.knowledgeBases | list | 否 | 知识库id列表 |
说明：卡牌库插件暂不支持API接入，创建角色时无需调用Function-call能力，在对话中使用
返回参数
名称 | 类型 | 说明 |
code | int | 返回码，正常返回200，异常返回空 |
success | bool | 正常返回 true，异常返回null |
requestId | string | |
data | object | 角色对象，CharacterKey |
data.characterId | string | 角色ID |
更新角色
接口
POST api/character/update
入参
名称 | 类型 | 是否必传 | 说明 |
characterId | string | 是 | 角色ID |
name | string | 否 | 角色名称 |
avatar | string | 否 | 角色头像 |
basicInformation | string | 否 | 角色基本信息，包含人设、经历 |
openingLine | string | 否 | 开场白 |
traits | string | 否 | 强制要求 |
chatExample | string | 否 | 对话示例 |
permConfig | object | 否 | 权限配置 |
advancedConfig | object | 否 | 高级配置 |
advancedConfig.longTermMemories | list | 否 | 长期记忆设置 |
advancedConfig.platformPlugins | list | 否 | 插件列表 |
advancedConfig.knowledgeBases | list | 否 | 知识库id列表 |
返回
名称 | 类型 | 说明 |
code | int | 返回码，正常返回200，异常返回空 |
success | bool | 正常返回 true，异常返回null |
requestId | string | |
data | boolean | 是否成功 |
查询角色
接口
POST api/character/search
入参
名称 | 类型 | 是否必传 | 说明 |
where | object | 是 | 搜索条件对象 |
where.scope | string | 是 | 查询范围- my - 只查询我创建的角色- public - 查询平台开放的角色- pre_configured - 预制角色 |
where.characterName | string | 否 | 角色名称，右匹配 |
pageNum | int | 是 | 页码 |
pageSize | int | 是 | 页大小 |
orderBy | list | 否 | 排序 |
返回
名称 | 类型 | 说明 |
code | int | 返回码，正常返回200，异常返回空 |
success | bool | 正常返回 true，异常返回null |
requestId | string | 请求唯一标识 |
data | object | |
data.list | object | 角色列表 |
data.page | int | 页码 |
data.pageSize | int | 分页大小 |
data.total | int | 角色总数 |
角色详情
接口
GET /v2/api/character/details
入参
名称 | 类型 | 是否必传 | 说明 |
characterId | string | 是 | 角色ID |
返回
角色对象CharacterDTO如下：
名称 | 类型 | 说明 |
characterId | string | 角色ID |
name | string | 角色名称 |
avatar | object | 角色头像 |
introduction | string | 角色摘要 |
basicInformation | string | 角色基本信息，包含人设、经历 |
openingLine | string | 开场白 |
traits | string | 强制要求 |
chatExample | string | 对话示例 |
roleTypes | list | 角色类型 用于星尘网页平台上公开角色分类 |
auditStatus | string | 审核状态 用于星尘平台的角色公开 审核中无法更新角色 - review更新审核中 - update更新中 - succcess审核成功 - refuse审核失败 |
configStatus | string | 上下架状态 下架状态的角色不能对话和更新 - out下架 - normal或null为上架状态 |
greenStatus | string | 绿网审核状态 用于人工绿网审核 审核中无法更新角色 - review审核中 - update更新审核中 - succcess审核成功 - refuse审核失败 |
permConfig | object | 权限配置 |
permConfig.isPublic | int | 是否开放角色属性给其他用户查看（1:是，0:否） |
permConfig.allowChat | int | 开放角色与其他用户聊天（1:是，0:否） |
permConfig.allowApi | int | 开放角色API接口允许其他用户调用（1:是，0:否） |
advancedConfig | object | 高级配置 |
advancedConfig.isRealInfo | boolean | 真实世界信息检索 |
advancedConfig.searchKeyword | string | 搜索关键字 |
advancedConfig.knowledgeBases | list | 否 |
注意：模型参数parameters优先级从高到低可以通过接口传入、角色属性配置）、和平台默认配置三个方式配置。
返回示例
{
"code": 200,
"data": {
"characterId": "178cad6d92dc4fbc9d50abed64809e2b", // 相同角色
"name": "满腔忠义的关云长",
"avatar": {
"fileSavePath": "oss-6400001-IAkXjMiqkajy9MCSywI4LD5K.png",
"filename": "关云长.png",
"fileUrl": "alifanyi-pixar-hz.oss-cn-hangzhou.aliyuncs.com/oss-6400001-IAkXjMiqkajy9MCSywI4LD5K.jpg?Expires=1688635588&OSSAccessKeyId=LTAIp4mkTgZD****&Signature=vitQVIB4GroVIZKbk%2BEWGL%2F6ifA%3D"
},
"basicInformation": "我们来玩一个角色扮演的游戏， 你是「满腔忠义的关云长」。",
"openingLine": "我是「关云长」，很高心与你玩游戏",
"traits": "请在对话时尽可能的展现你的性格、感情， 用文言文回答， 并使用古人的语气和用词。",
"chatExample": "{{user}}:敢问阁下尊姓大名。\n{{char}}:吾姓关名羽，字长生，后改云长，河东解良人也。",
"gmtCreate": "2023-07-14T02:02:19.000+00:00",
"gmtModified": "2023-07-14T02:04:05.000+00:00",
"userId": "abc",
"bizUserId": "xyz",
"manageable": true,
"permConfig": {
"isPublic": 0,
"allowApi": 0,
"allowChat": 0
}
"advancedConfig": {
"knowledgeBases":["d89f6dbb32c645688b01e976cf7ec08e"],
"isRealInfo": true,
"searchKeyword":"关云长"
}
},
"success": true
}对话历史
对话历史查询
接口
POST /v2/api/chat/message/histories
入参
名称 | 类型 | 是否必传 | 说明 |
where | object | 是 | 查询条件对象角色参考下表 |
where.characterId | string | 是 | 角色ID |
where.userId | string | 是 | 对话用户ID |
where.sessionId | string | 否 | 会话ID |
where.startTime | long | 否 | 开始时间戳精确到毫秒 |
where.endTime | long | 否 | 结束时间戳 |
where.messageIds | list | 否 | 消息ID列表 |
pageNum | int | 否（默认1） | 分页页码 |
pageSize | int | 否（默认10） | 分页大小 |
orderBy | list | 否（默认创建时间倒排） | 历史消息排序 |
返回
名称 | 类型 | 说明 |
messageId | string | 消息ID |
sessionId | string | 会话ID |
chatId | string | 一次对话ID，一问多答 chatId 相同 |
messageIssuer | object | 不同userType, userId 和 userName表示不同含义，userType 取值：- user - 用户，userId 和 userName 分别表示用户ID和用户名- character - 角色，userId 和 userName 分别表示角色ID和角色名 |
messageType | string | opening_remarks - 开场白sys_greetings - 系统问候user - 用户提问character - 角色回复chat_description - 对话提示 |
status | string | 历史消息状态normal：正常reset：被重置 |
content | string | json string |
对话历史评价
接口
POST /v2/api/chat/message/rating
入参
名称 | 类型 | 是否必传 | 说明 |
messageId | string | 是 | 消息ID |
rating | int | 是 | 评分 0为差评 5为好评 |
返回
名称 | 类型 | 说明 |
content | boolean | true成功、false失败 |
系统推荐
接口
POST v2/api/chat/message/reminder
入参
名称 | 类型 | 是否必传 | 说明 |
characterId | string | 是 | 角色的id 角色给用户主动发消息 |
bizUserId | string | 是 | 接收消息的用户bizUserId |
content | string | 是 | 提示消息 |
返回
名称 | 类型 | 说明 |
content | boolean | true成功、false失败 |
重置对话
在不使用平台对话历史的场景下，如果需要重置对话，则传入新的对话历史即可。
其他
万相图片轮询
接口
GET /v2/api/chat/polling/image
入参
名称 | 类型 | 是否必传 | 说明 |
messageId | String | 是 | 带有图片任务id的消息ID |
userId | String | 是 | paas端用户id |
返回
名称 | 类型 | 说明 |
taskId | string | 图片任务ID |
fileUrls | list | 图片链接列表 |
status | string | 图片生成状态，success，running，failure |
返回示例
{
"requestId": "210f470117126410644908058e6315",
"code": 200,
"data": {
"taskId": "342a02b4-2cb7-4219-a3d4-c7de90ab1ff8",
"fileUrls": [
"https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/1d/2d/20240409/723609ee/19311d8c-e3c2-4533-9a10-a7cb99865d98-1.png?Expires=1712727324&OSSAccessKeyId=LTAI5tQZd8AEcZX6KZV4****&Signature=fh4ix8VrpoUpSb3qOo67xGO9L6M%3D"
],
"status": "success"
},
"success": true
}角色描述自动生成
接口
POST /v2/api/character/auto/desc
入参
名称 | 类型 | 是否必传 | 说明 |
type | String | 是 | file或者text |
fileUrl | String | 否 | 外部文件链接 |
text | String | 否 | 文本内容 |
fileName | String | 否 | type是file时必填，带有文件类型后缀的文件名 |
返回
名称 | 类型 | 说明 |
content | string | 自动生成的内容 |
usage | object | token用量 |
usage.outputTokens | int | token输出用量 |
usage.inputTokens | int | token输入用量 |
返回示例
{
"requestId": "d8e90bd07474fd7d46c16e07408d5802",
"code": 200,
"data": {
"content": "【基本信息】\n关羽(?-220)，本字长生，后改字云长，汉族，出生于并州河东解（今山西运城）。\n\n【生平经历】\n关羽是中国东汉末年著名的将领。他从刘备于乡里聚众起兵开始便追随刘备，成为刘备最为信任的将领之一。\n\n【死后影响及地位】\n关羽去世后，其形象逐渐被后人神化，一直是历来民间祭祀的对象，被尊称为“关公”。又经历代朝廷褒封，清代时被奉为“忠义神武灵佑仁勇威显关圣大帝”，崇为“武圣”，与“文圣”孔子齐名。\n\n【文学作品中的形象】\n长篇历史小说《三国演义》对关羽的事迹多有描写和夸大，在《演义》中，关羽被描写为“五虎大将”之首。\n\n【其他相关】\n古代有地名关羽，但其确切位置不明。",
"usage": {
"outputTokens": 213,
"inputTokens": 230
}
},
"success": true
}kv对抽取
接口
POST /v2/api/extract/kv
入参
名称 | 类型 | 是否必传 | 说明 |
messages | list | 是 | 消息集合 |
messages[i].role | string | 是 | assistant或者user |
message[i].content | string | 是 | 消息内容 |
kvMemoryConfigs | list | 是 | 抽取条件设置集合 |
kvMemoryConfigs[i].kvMemoryConfig | object | 是 | 抽取条件设置 |
kvMemoryConfig.enabled | boolean | 是 | 是否启用 |
kvMemoryConfig.memoryText | String | 是 | 记忆文本 |
返回
名称 | 类型 | 说明 |
schemas | list | 抽取的内容集合 |
schemas[i].schema | object | 抽取的内容 |
schema.role | string | assistant或者user |
schema.key | string | 记忆文本 |
schema.value | list | 抽取的文本内容 |
usage | object | token用量 |
usage.outputTokens | int | token输出用量 |
usage.inputTokens | int | token输入用量 |
返回示例
{
"requestId": "cefaf145993be9e24fa5830fdf88aef2",
"code": 200,
"data": {
"schemas": [
{
"role": "user",
"key": "职业",
"value": [
"武术爱好者"
]
},
{
"role": "user",
"key": "喜欢",
"value": [
"武术"
]
}
],
"usage": {
"outputTokens": 74,
"inputTokens": 627
}
},
"success": true
}summary抽取
接口
POST /v2/api/extract/summary
入参
名称 | 类型 | 是否必传 | 说明 |
messages | list | 是 | 消息集合 |
messages[i].role | string | 是 | assistant或者user |
message[i].content | string | 是 | 消息内容 |
返回
名称 | 类型 | 说明 |
memoryResults | list | 抽取的内容集合 |
memoryResults[i].memoryResult | object | 抽取的内容 |
memoryResult.content | string | 抽取的文本内容 |
usage | object | token用量 |
usage.outputTokens | int | token输出用量 |
usage.inputTokens | int | token输入用量 |
返回示例
{
"requestId": "ca61f80aa865a2575863b8246dddd51f",
"code": 200,
"data": {
"memoryResults": [
{
"content": "user提议一起去打篮球"
},
{
"content": "assistant同意一起去打篮球"
},
{
"content": "user和assistant计划一起去打篮球，然后去吃火锅"
}
],
"usage": {
"outputTokens": 45,
"inputTokens": 590
}
},
"success": true
}excel转docx（文件上传接口）
接口
POST v2/api/common/file/asyn/upload
入参
名称 | 类型 | 是否必传 | 说明 |
sourceUrl | string | 是 | 公网可访问的文件url链接 注：文件类型要和type类型一致 |
type | string | 是 | 文件转换类型 excelToDocx（excle转doc） |
返回
名称 | 类型 | 说明 |
id | Long | 任务id 上传成功后生成 请记住此任务id 方便后续调用结果查询接口查询结果 |
status | String | 任务状态init初始化 success成功 failed失败 error异常 |
url | String | 转换后的结果文件url 此处为空 |
excel转docx（结果查询接口）
接口
GET v2/api/common/file/asyn/download
入参
名称 | 类型 | 是否必传 | 说明 |
taskId | Long | 是 | 任务id |
返回
名称 | 类型 | 说明 |
id | Long | 任务id |
status | String | 任务状态init初始化 success成功 failed失败 error异常 |
url | String | 任务处理成功后 此处是转换后的结果文件url 复制到浏览器即可下载结果文件 |