Spark Character

[#](about:blank#%E5%BC%80%E6%BA%90%E5%A4%A7%E6%A8%A1%E5%9E%8Bweb-api%E6%96%87%E6%A1%A3) Web API文档
======================================================================================================

[#](about:blank#_1-%E8%AF%B7%E6%B1%82%E5%9C%B0%E5%9D%80) 1 请求地址
---------------------------------------------------------------

```
wss://maas-api.cn-huabei-1.xf-yun.com/v1.1/chat

```

[#](about:blank#_2-%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83) 2 接口鉴权
---------------------------------------------------------------

参考[通用URL鉴权文档](https://www.xfyun.cn/doc/spark/general_url_authentication.html)

[#](about:blank#_3-%E6%8E%A5%E5%8F%A3%E8%AF%B7%E6%B1%82) 3 接口请求
---------------------------------------------------------------

### [#](about:blank#%E8%AF%B7%E6%B1%82%E5%8F%82%E6%95%B0) 请求参数

```
{
        "header": {
            "app_id": "12345",
            "uid": "12345"
        },
        "parameter": {
            "chat": {
                "domain": "xaipersonality",
                "temperature": 0.5
            }
        },
        "payload": {
            "message": {
                # 如果想获取结合上下文的回答，需要开发者每次将历史问答信息一起传给服务端，如下示例
                # 注意：text里面的所有content内容加一起的tokens需要控制在8192以内，开发者如有较长对话需求，需要适当裁剪历史信息
                "text": [
                    {"role": "user", "content": "你是谁"} # 用户的历史问题
                    {"role": "assistant", "content": "....."}  # AI的历史回答结果
                    # ....... 省略的历史对话
                    {"role": "user", "content": "你会做什么"}  # 最新的一条问题，如无需上下文，可只传最新一条问题
                ]
        }
    }
}

```

接口请求字段由三个部分组成：header，parameter, payload。 字段解释如下

**header部分**

| 参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
| --- | --- | --- | --- | --- |
| app\_id | string | 是 |  | 应用appid，从开放平台控制台创建的应用中获取 |
| uid | string | 否 | 最大长度32 | 每个用户的id，用于区分不同用户 |

**parameter.chat部分**

| 参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
| --- | --- | --- | --- | --- |
| domain | string | 是 | 取值为用户服务的serviceId | xaipersonality |
| temperature | float | 否 | 取值为\[0,1\],默认为0.5 | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| top\_k | int | 否 | 取值为\[1，6\],默认为4 | 从k个候选中随机选择⼀个（⾮等概率） |
| chat\_id | string | 否 | 需要保障用户下的唯一性 | 用于关联用户会话 |

**payload.message.text部分**

_注：text下所有content累计内容 tokens需要控制在8192内_

| 参数名称 | 类型 | 必传 | 参数要求 | 参数说明 |
| --- | --- | --- | --- | --- |
| role | string | 是 | 取值为\[user,assistant\] | user表示是用户的问题，assistant表示AI的回复 |
| content | string | 是 | 所有content的累计tokens需控制8192以内 | 用户和AI的对话内容 |

[#](about:blank#_4-%E6%8E%A5%E5%8F%A3%E5%93%8D%E5%BA%94) 4 接口响应
---------------------------------------------------------------

```
# 接口为流式返回，此示例为最后一次返回结果，开发者需要将接口多次返回的结果进行拼接展示
{
    "header":{
        "code":0,
        "message":"Success",
        "sid":"olm000cb087@dx18793cd421fb894542",
        "status":2
    },
    "payload":{
        "choices":{
            "status":2,
            "seq":0,
            "text":[
                {
                    "content":"我可以帮助你的吗？",
                    "role":"assistant",
                    "index":0
                }
            ]
        },
        "usage":{
            "text":{
                "question_tokens":4,
                "prompt_tokens":5,
                "completion_tokens":9,
                "total_tokens":14
            }
        }
    }
}

```

接口返回字段分为两个部分，header，payload。字段解释如下

**header部分**

| 字段名 | 类型 | 字段说明 |
| --- | --- | --- |
| code | int | 错误码，0表示正常，非0表示出错；详细释义可在接口说明文档最后的错误码说明了解 |
| message | string | 会话是否成功的描述信息 |
| sid | string | 会话的唯一id，用于讯飞技术人员查询服务端会话日志使用,出现调用错误时建议留存该字段 |
| status | int | 会话状态，取值为\[0,1,2\]；0代表首次结果；1代表中间结果；2代表最后一个结果 |

**payload.choices部分**

| 字段名 | 类型 | 字段说明 |
| --- | --- | --- |
| status | int | 文本响应状态，取值为\[0,1,2\]; 0代表首个文本结果；1代表中间文本结果；2代表最后一个文本结果 |
| seq | int | 返回的数据序号，取值为\[0,9999999\] |
| content | string | AI的回答内容 |
| role | string | 角色标识，固定为assistant，标识角色为AI |
| index | int | 结果序号，取值为\[0,10\]; 当前为保留字段，开发者可忽略 |

**payload.usage部分(在最后一次结果返回)**

| 字段名 | 类型 | 字段说明 |
| --- | --- | --- |
| question\_tokens | int | 保留字段，可忽略 |
| prompt\_tokens | int | 包含历史问题的总tokens大小 |
| completion\_tokens | int | 回答的tokens大小 |
| total\_tokens | int | prompt\_tokens和completion\_tokens的和，也是本次交互计费的tokens大小 |

[#](about:blank#_5-%E9%94%99%E8%AF%AF%E7%A0%81%E5%88%97%E8%A1%A8) 5 错误码列表
-------------------------------------------------------------------------

| 错误码 | 错误信息 |
| --- | --- |
| 0 | 成功 |
| 10000 | 升级为ws出现错误 |
| 10001 | 通过ws读取用户的消息 出错 |
| 10002 | 通过ws向用户发送消息 出错 |
| 10003 | 用户的消息格式有错误 |
| 10004 | 用户数据的schema错误 |
| 10005 | 用户参数值有错误 |
| 10006 | 用户并发错误：当前用户已连接，同一用户不能多处同时连接。 |
| 10007 | 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题） |
| 10008 | 服务容量不足，联系服务商 |
| 10009 | 和引擎建立连接失败 |
| 10010 | 接收引擎数据的错误 |
| 10011 | 向引擎发送数据的错误 |
| 10012 | 引擎内部错误 |
| 10013 | 用户问题涉及敏感信息，审核不通过，拒绝处理此次请求。 |
| 10014 | 回复结果涉及到敏感信息，审核不通过，后续结果无法展示给用户。（建议清空当前结果，并给用户提示/警告：该答案涉及到敏感/政治/恐怖/色情/暴力等方面，不予显示/回复） |
| 10015 | appid在黑名单中 |
| 10016 | appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权 等等。 （联系我们开通授权或提高限制） |
| 10018 | 用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注 |
| 10019 | 该错误码表示返回结果疑似敏感，建议拒绝用户继续交互 |
| 10110 | 服务忙，请稍后再试。 |
| 10163 | 请求引擎的参数异常 引擎的schema 检查不通过 |
| 10222 | 引擎网络异常 |
| 10223 | LB找不到引擎节点 |
| 10907 | token数量超过上限。对话历史+问题的字数太多，需要精简输入。 |
| 11200 | 授权错误：该appId没有相关功能的授权 或者 业务量超过限制（联系我们开通授权或提高限制） |
| 11201 | 授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制） |
| 11202 | 授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制） |
| 11203 | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |