# 星火X1 websocket 协议文档

上线时间：2025.04.15

X1模型进一步升级，在原来数学任务国内领先基础上，推理、文本生成、语言理解等通用任务实现效果对标OpenAI o1和DeepSeek R1。

# 1. 请求地址

深度推理模型Spark X1 已发布，可领取授权体验，立即领取>> (opens new window)

请求方式：POST

wss://spark-api.xf-yun.com/v1/x1

# 2.请求说明

# 2.1 请求示例

Python Demo (opens new window)

Java Demo (opens new window)

# 2.2 鉴权

鉴权说明： 鉴权所需的appid、apikey、apisecret信息在控制台 (opens new window)获取
鉴权协议： 参考通用ws鉴权 (opens new window)

# 2.3 请求体

{
    "header": {
        "uid": "user_id",
        "app_id": "4CC5779A"
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "user",
                    "content": "推荐两个适合自驾春游的景点"
                }
            ]
        }
    },
    "parameter": {
        "chat": {
            "domain": "x1",
            "max_tokens": 4096,
            "presence_penalty":1,
            "temperature":0,
            "frequency_penalty":0.02,
            "top_k":5,
            "tools": [               
                {                   
                    "type": "web_search",                   
                    "web_search": {                       
                        "enable": true,     
                        "search_mode": "normal"
                    }
                }
            ]
        }
    }
}

# 2.3请求参数

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

header部分

参数名称	类型	必传	参数要求	参数说明
app_id	string	是		应用appid，从开放平台控制台创建的应用中获取
uid	string	否		每个用户的id，非必传字段，用于后续扩展，"maxLength":32

parameter.chat部分

参数名称	类型	必传	参数要求	参数说明
domain	string	是	根据需要传参	x1
temperature	float	否	取值范围（0，2] ，默认值1.2	核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高。与top_p均可以控制生成文本的多样性，因此建议您只设置其中一个值
max_tokens	int	否	取值为[1,32768]，默认为32768	模型回答的tokens的最大长度
chat_id	string	否		会话id，建议都传
top_k	int	否	取值范围[1,6] ,默认为6	从k个候选中随机选择⼀个（⾮等概率）
top_p	float	否	取值范围(0,1]，默认值0.95	核采样的概率阈值，控制模型生成文本的多样性。top_p越高，生成的文本更多样。反之，生成的文本更确定。由于与temperature均可以控制生成文本的多样性，因此建议您只设置其中一个值。
presence_penalty	float	否	对应punish_value（repeat_punish），取值范围[-2,10]，默认2.01	提高该值，可以降低模型生成重复内容的概率
frequency_penalty	float	否	对应punish_scale（repeat_punish_scale ），取值范围[-2,10]，默认0.001	控制生成文本长度
tools	List
tools.type	string	是	取值范围：web_search	工具类型 web_search ：网页搜索
tools.web_search	object	否
tools.web_search.enable	bool	否	默认false	是否开启网络搜索
tools.web_search.search_mode	string	否	取值范围：deep、normal	deep：深度搜索，信源内容更详细丰富，prompt token会膨胀 normal：简要搜索

payload.message.text部分 注意： 1、请确保text下所有content内容累计的tokens数量在模型上下文长度的限制之内。具体可参考下文中content字段的参数要求。
2、**如果传入system参数，需要保证第一条是system；**多轮交互需要将之前的交互历史按照system-user-assistant-user-assistant进行拼接。

参数名称	类型	必传	参数要求	参数说明
role	string	是	取值为[system,user,assistant]	system用于设置对话背景 user表示是用户的问题， assistant表示AI的回复
content	string	是		用户和AI的对话内容

# 3.响应参数

# 3.1响应体

在不返回检索信源的情况下，大模型返回结构如下：

{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000cb087@dx18793cd421fb894542",
        "status": 2
    },
    "payload": {
        "security_suggest": {
            "action": "HIDE_CONTINUE"
        },
        "choices": {
            "status": 2,
            "seq": 0,
            "text": [
                {
                    "reasoning_content": "好的，用户让我推荐两个适合自驾春游的景点....", # 流式输出reasoning_content字段结束后，输出content内容
                    "content": "以下是两个适合春季自驾游的国内景点推荐，兼顾自然风光与人文体验，附上实用贴士....",
                    "role": "assistant",
                    "index": 0
                }
            ]
        },
        "usage": {
            "text": {
                "question_tokens": 4,
                "prompt_tokens": 5,
                "completion_tokens": 9,
                "total_tokens": 14
            }
        }
    }
}

# 3.2响应参数

接口返回字段分为两个部分，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的回答内容
reasoning_content	string	内容为 assistant 消息中在最终答案之前的推理内容，多轮不要回传
role	string	角色标识，固定为assistant，标识角色为AI
index	int	结果序号，取值为[0,10]; 当前为保留字段，开发者可忽略

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

字段名	类型	字段说明
question_tokens	int	保留字段，可忽略
prompt_tokens	int	包含历史问题的总tokens大小
search_prompt_tokens	int	网页搜索模式指定deep时膨胀的token
completion_tokens	int	回答的tokens大小
total_tokens	int	prompt_tokens和completion_tokens的和，也是本次交互计费的tokens大小

请求示例：

{
    "header": {
        "app_id": "12345",
        "uid": "12345",
        "protocol_type": "spark"
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "user",
                    "content": "推荐两个适合自驾春游的景点"
                }
            ]
        }
    },
    "parameter": {
        "chat": {
            "domain": "reasoner-x1",
            "auditing": "default",
            "max_tokens": 4096,
            "presence_penalty":1,
            "temperature":0.5,
            "frequency_penalty":0.02,
            "top_k":5,
            "chat_id": "667a281a-2c54-4293-9f67-5ba394d08668",
            "tools": [               
                {                   
                    "type": "web_search",                   
                    "web_search": {                       
                        "enable": true,   
                        "search_mode": "normal"
                    }
                }
            ]
        }
    }
}

# 4.错误码说明

错误码	错误信息
0	成功
10007	用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题）
10013	输入内容审核不通过，涉嫌违规，请重新调整输入内容
10014	输出内容涉及敏感信息，审核不通过，后续结果无法展示给用户
10019	表示本次会话内容有涉及违规信息的倾向；建议开发者收到此错误码后给用户一个输入涉及违规的提示
10907	token数量超过上限。对话历史+问题的字数太多，需要精简输入
11200	授权错误：该appId没有相关功能的授权或者业务量超过限制
11201	授权错误：日流控超限。超过当日最大访问量的限制
11202	授权错误：秒级流控超限。秒级并发超过授权路数限制
11203	授权错误：并发流控超限。并发路数超过授权路数限制

在这篇文章中：