Spark http调用文档

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_1-%E6%8E%A5%E5%8F%A3%E8%AF%B4%E6%98%8E)1. 接口说明

**注意： 该接口可以正式使用。如您需要申请使用，请点击前往[产品页面](https://xinghuo.xfyun.cn/sparkapi?scr=price) 领取免费额度。**

**Tips：  
**1. 计费包含接口的输入和输出内容；  
**2. 1 token约等于1.5个中文汉字 或者 0.8个英文单词；  
**3. 仅Spark Pro, Spark Max和Spark 4.0Ultra支持[搜索]、[天气]、[日期]、[诗词]、[字词]、[股票]等内置插件；
**4. Spark 4.0Ultra、Max现已支持system、Function Call功能；
**5. 当前仅Spark 4.0Ultra、Max版本支持返回联网检索的信源标题及地址。

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_2-%E8%AF%B7%E6%B1%82%E5%9C%B0%E5%9D%80)2. 请求地址

### [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_2-1-%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B)2.1 语言模型

**星火当前有Lite、Pro、Pro-128K、Max、Max-32K和4.0 Ultra六个版本的语言模型，各版本独立计量tokens。**  
**面向公司内专用入口:**

```
https://spark-api-open-inner.xf-yun.com/v1
```

**面向外部开发者入口:**

```
https://spark-api-open.xf-yun.com/v1/chat/completions
```

**兼容openAI SDK:**

```
base_url 需要配置为:https://spark-api-open.xf-yun.com/v1/
```

| 语言模型版本 | 4.0Ultra | Max | Pro | Lite |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 模型介绍 | **最强大的星火大模型** 在文本生成、语言理解、知识问答等七大维度全面对标GPT 4-Turbo | **旗舰级大语言模型** 在结构化抽取、逻辑推理等场景表现优异 | **专业级大语言模型** 适用于文本、智能问答等对性能和响应速度有更高要求的业务场景 | **轻量级大语言模型** 具有更高的响应速度,支持**免费使用** |
| 最大输入长度 | 32K | 8K\32K | 8K\128K | 8K |
| 最大输出长度 | 32K | 8K\8K | 8K\4K | 4K |

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_3-%E8%AF%B7%E6%B1%82%E8%AF%B4%E6%98%8E)3. 请求说明

### [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_3-1-%E8%B0%83%E7%94%A8%E7%A4%BA%E4%BE%8B)3.1 调用示例

[**Python 调用示例**](https://openres.xfyun.cn/xfyundoc/2025-05-09/9b7fe133-d9fa-41e1-b657-898805df3ab3/1746764431460/http_demo.zip)

[**Java 调用示例**](https://openres.xfyun.cn/xfyundoc/2025-05-09/6a64a22b-9e00-4641-89d7-1f7f33894dc8/1746773469674/http_demo.zip)

[PYTHON-SDK-DEMO](https://github.com/iFLYTEK-OP/websdk-python-demo)

[JAVA-SDK-DEMO](https://github.com/iFLYTEK-OP/websdk-java-demo)

### [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_3-2-%E8%AF%B7%E6%B1%82%E5%A4%B4)3.2 请求头

请到[**控制台**](https://console.xfyun.cn/services/cbm) 对应版本页面，获取http服务接口认证信息中的APIPassword ,假如获取到的值为123456，则请求头如下：

```
Content-Type: application/json
Authorization: Bearer 123456
```

利用上方的请求头发起请求示例如下：

```
curl -i -k -X POST 'https://spark-api-open.xf-yun.com/v1/chat/completions' \
--header 'Authorization: Bearer 123456' \#注意此处把“123456”替换为自己的APIPassword
--header 'Content-Type: application/json' \
--data '{
    "model":"generalv3.5",
    "messages": [
        {
            "role": "user",
            "content": "来一个只有程序员能听懂的笑话"
        }
    ],
    "stream": true
}'
```

### [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_3-3-%E8%AF%B7%E6%B1%82%E5%8F%82%E6%95%B0)3.3 请求参数

```
{
    "model": "generalv3.5",
    "user": "用户唯一id",
    "messages": [
        {
            "role": "system",
            "content": "你是知识渊博的助理"
        },
        {
            "role": "user",
            "content": "你好，讯飞星火"
        }
    ],
    // 下面是可选参数
    "temperature": 0.5,
    "top_k": 4,
    "stream": false,
    "max_tokens": 1024,
    "presence_penalty": 1,
    "frequency_penalty": 1,
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "str2int",
                "description": "将字符串类型转为 int 类型",
                "parameters": {...} // 需要符合 json schema 格式
            }
        },
        {
            "type": "web_search",
            "web_search": {
                "enable": true
                "show_ref_label":true
                "search_mode":"deep" // deep:深度搜索 / normal:标准搜索,不同的搜索策略，效果不同，并且token消耗也有差异
            }
        }
    ],
    "response_format": {
        "type": "json_object"
    },
    "suppress_plugin": [
        "knowledge"
    ]
}
```

**FunctionCall非流式请求示例**

```
{
		"user": "user-1234",
    "model": "4.0Ultra",
    "stream": false,
    "tool_choice": "auto",
    "messages": [
        {
            "role": "user",
            "content": "合肥和上海的天气"
        }
    ],
    "model": "4.0Ultra",
    "stream": false,
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "当你想查询指定城市的天气时使用此工具",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "城市或县区，比如北京市、合肥市、蜀山区等。"
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        }
    ]
}
```

**FunctionCall模型返回调用信息**

```
 {
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "Call_000dc56c@dx19a51f9d700b81a132",
            "function": {
              "arguments": "{\"location\":\"合肥市\"}",
              "name": "get_weather"
            },
            "type": "function"
          },
          {
            "id": "Call_000dc571@dx19a51f9da42b81a132",
            "function": {
              "arguments": "{\"location\":\"上海市\"}",
              "name": "get_weather"
            },
            "type": "function"
          }
        ]
      }
    }
  ],
  "usage": {
    "completion_tokens": 42,
    "prompt_tokens": 5,
    "total_tokens": 47
  },
  "code": 0,
  "message": "Success",
  "sid": "cha000c32cc@dx19a51f9cec7b8f3812"
}
```

**FunctionCall工具调用结果回传**

```
{
    "user": "user-1234",
    "model": "4.0Ultra",
    "stream": false,
    "tool_choice": "auto",
    "messages":
    [
        {
            "role": "user",
            "content": "合肥和上海的天气"
        },
        {
            "content": "",
            "role": "assistant",
            "tool_calls":
            [
                {
                    "id": "Call_000dc56c@dx19a51f9d700b81a132",
                    "function":
                    {
                        "arguments": "{\"location\":\"合肥市\"}",
                        "name": "get_weather"
                    },
                    "type": "function"
                },
                {
                    "id": "Call_000dc571@dx19a51f9da42b81a132",
                    "function":
                    {
                        "arguments": "{\"location\":\"上海市\"}",
                        "name": "get_weather"
                    },
                    "type": "function"
                }
            ]
        },
        {
            "role": "tool",
            "tool_call_id": "Call_000dc56c@dx19a51f9d700b81a132",
            "content": "合肥市今天是晴天。"
        },
        {
            "role": "tool",
            "tool_call_id": "Call_000dc571@dx19a51f9da42b81a132",
            "content": "上海市今天是多云。"
        }
    ],
    "tools":
    [
        {
            "type": "function",
            "function":
            {
                "name": "get_weather",
                "description": "当你想查询指定城市的天气时使用此工具",
                "parameters":
                {
                    "type": "object",
                    "properties":
                    {
                        "location":
                        {
                            "type": "string",
                            "description": "城市或县区，比如北京市、合肥市、蜀山区等。"
                        }
                    },
                    "required":
                    [
                        "location"
                    ]
                }
            }
        }
    ]
}
```

**Functioncall使用OpenAI SDK请求示例**

```
client = OpenAI(
        api_key="控制台获取的APIPassword", 
        base_url = 'https://spark-api-open.xf-yun.com/v1' # 指向讯飞星火的请求地址
    )

stream_res = True
# stream_res = False

# 用户问题
USER_QUESTION = "合肥和上海的天气"
model = "4.0Ultra"

# 定义工具列表
tools = [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "当你想查询指定城市的天气时使用此工具",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市或县区，比如北京市、合肥市、蜀山区等。"
            }
          },
          "required": [
            "location"
          ]
        }
      }
    }
]

# 模拟天气查询工具
def get_weather(arguments):
    weather_conditions = ["晴天", "多云", "雨天"]
    random_weather = random.choice(weather_conditions)
    location = arguments["location"]
    return f"{location}今天是{random_weather}。"

# 封装模型响应函数
def get_response(messages):
    completion = client.chat.completions.create(
        model=model,
        messages=messages,
        stream=stream_res,
        tools=tools
    )
    return completion

messages = [{"role": "user", "content": USER_QUESTION}]
response = get_response(messages)
print("responseRaw: \n",response)
print("responseReadable: \n",response.to_json())

assistant_output = response.choices[0].message
if assistant_output.content is None:
    assistant_output.content = ""
# 保存工具调用信息
messages.append(assistant_output)

# 不需要调用工具，直接输出内容
if assistant_output.tool_calls is None:
    print(f"无需调用工具，直接回复：{assistant_output.content}")
else:
    # 进入工具调用
    for tool_call in assistant_output.tool_calls:
        tool_call_id = tool_call.id
        func_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        print(f"正在调用工具 [{func_name}]，参数：{arguments}")
        # 执行工具
        tool_result = get_weather(arguments)
        # 构造工具返回信息
        tool_message = {
            "role": "tool",
            "tool_call_id": tool_call_id,
            "content": tool_result,  # 保持原始工具输出
        }
        print(f"工具返回：{tool_message['content']}")
        messages.append(tool_message)
    # 再次调用模型，获取总结后的自然语言回复
    response = get_response(messages)
    assistant_output = response.choices[0].message

print(f"模型最终回答：{assistant_output.content}")

```

| 参数名称 | 类型 | 是否必传 | 取值范围 | 描述 |
| ------------------------------- | ------------------------- | ---------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| model | string | 是 | 4.0Ultra generalv3.5 max-32k generalv3 pro-128k lite | 指定访问的模型版本: 4.0Ultra指向4.0 Ultra版本; generalv3.5指向Max版本; max-32k指向Max-32K版本; generalv3指向Pro版本; pro-128k指向Pro-128K版本; lite指向Lite版本; |
| user | string | 否 | 自定义 | 用户的唯一id，表示一个用户，user_123456 |
| messages | array | 是 | | 输入数组 |
| messages.role | string | 是 | user assistant system tool | 角色:user表示用户，assistant表示大模型，system表示命令，tool代表function call执行结果 |
| messages.content | string | 是 | | 角色对应的文本内容 |
| messages.tool_call_id | string | 否 | | 工具函数调用的 ID |
| temperature | float | 否 | 取值范围[0, 2] 默认值1.0 | 核采样阈值，数学、推理、代码等任务建议调为1.2 |
| top_p | int | 否 | 取值范围(0, 1] 默认值1 | 生成过程中核采样方法概率阈值，例如，取值为0.8时，仅保留概率加起来大于等于0.8的最可能token的最小集合作为候选集。取值越大，生成的随机性越高；取值越低，生成的确定性越高。 |
| top_k | int | 否 | 取值范围[1, 6] 默认值4 | 从k个中随机选择一个(非等概率) |
| presence_penalty | float | 否 | 取值范围[0,2] 默认1.2 | 重复词的惩罚值 |
| frequency_penalty | float | 否 | 取值范围[0,1] 默认0.02 | 频率惩罚值 |
| stream | bool | 否 | true false | 是否流式返回结果。默认是false 表示非流式。 如果使用流式，服务端使用SSE的方式推送结果，客户端自己适配处理结果。 |
| max_tokens | int | 否 | 4.0 Ultra 取值为[1,32768]，默认为32768 Max-32K取值为[1,32768]，默认为4096 Max取值为[1,8192]，默认为4096 Pro 取值为[1,8192]，默认为4096 Pro-128K取值为[1,131072]，默认为4096 Lite取值为[1,4096]，默认为4096 | 模型回答的tokens的最大长度 |
| response_format | object | 否 | | 指定模型的输出格式 |
| response_format.type | string | 否 | text json_object | { "type": "json_object" } 指定模型输出json格式 使用 JSON 模式时，请始终指示模型通过对话中的某些消息（例如通过系统或用户消息）生成 JSON |
| tools | array | 否 | 在这里用户可以控制联网搜索工具或者自定义各类function | 工具列表 |
| tools.web_search | object | 否，默认表示开启 | {   "type": "web_search",   "web_search": {   "enable": true,   "show_ref_label": true,   "search_mode": "deep"   }  } | **仅Ultra、Max、Pro系列模型支持此参数** |
| tools.web_search.enable | bool | 否，X1默认关闭，其他模型默认开启（true） | true or false | enable：是否开启搜索功能，设置为true,模型会根据用户输入判断是否触发联网搜索，false则完全不触发； |
| tools.web_search.show_ref_label | bool | 否，默认关闭（false） | true or false | show_ref_label 开关控制触发联网搜索时是否返回信源信息（仅在enable为true时生效） 如果开启，则先返回搜索结果，之后再返回模型回复内容 |
| tools.web_search.search_mode | string | 否，默认标准搜索（normal） | deep/normal | search_mode 控制联网搜索策略（仅在enable为true时生效） normal：标准搜索模式，模型引用搜索返回的摘要内容回答问题 deep：深度搜索模式，模型引用搜索返回的全文内容，回复的更准确；同时会带来额外的token消耗（返回search_prompt字段） |
| tools.function | object | 否 | 示例： {"type":"function", "function":{"name": "my_function", "description": "xxx", "parameters": {...}}} | **当前仅Max、Ultra版本支持** |
| tools.function.name | string | 是 | 用户自定义，长度不超过32 | 工具函数的名称，必须是字母、数字，可以包含下划线 |
| tools.function.description | string | 是 | 用户自定义 | 工具函数的描述，供模型选择何时调用该工具 |
| tools.function.parameters | string | 是 | 用户自定义 | 工具的参数描述，需要是一个合法的JSON Schema |
| tool_choice | string or object Optional | 否 | | 设置模型自动选择调用的函数： auto：传了tool时默认为auto，模型自动选择调用的函数 "tool_choice": "auto" none：模型禁用函数调用 "tool_choice": "none" required：模型始终选择一个或多个函数进行调用 "tool_choice": "required" force：强制模型调用某一个工具（和模型效果相关，不一定有效） "tool_choice": {"type": "function", "name": "get_current_weather"} allowed_tools: 模型可以选择 tools 列表中一个或者多个函数进行调用 "tool_choice": { "type": "allowed_tools", "mode": "auto", "tools": [ { "type": "function", "name": "get_current_weather" }, { "type": "function", "name": "search_docs" } ] } } |

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_4-%E5%93%8D%E5%BA%94%E5%8F%82%E6%95%B0)4. 响应参数

### [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_4-1%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B%E5%93%8D%E5%BA%94%E7%A4%BA%E4%BE%8B)4.1语言模型响应示例

**非流式请求成功时的响应格式：**

```
{
    "code": 0,
    "message": "Success",
    "sid": "cha000b0003@dx1905cd86d6bb86d552",
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "你好，我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方，请随时告诉我！我会尽力为你提供解答和支持。请问有什么可以帮到你的吗？"
            },
            "index": 0
        }
    ],
    "usage": {
        "prompt_tokens": 6,
        "completion_tokens": 42,
        "total_tokens": 48
    }
}
```

**非流式请求调用函数成功时的响应格式**

```
 {
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "Call_000dc56c@dx19a51f9d700b81a132",
            "function": {
              "arguments": "{\"location\":\"合肥市\"}",
              "name": "get_weather"
            },
            "type": "function"
          },
          {
            "id": "Call_000dc571@dx19a51f9da42b81a132",
            "function": {
              "arguments": "{\"location\":\"上海市\"}",
              "name": "get_weather"
            },
            "type": "function"
          }
        ]
      }
    }
  ],
  "usage": {
    "completion_tokens": 42,
    "prompt_tokens": 5,
    "total_tokens": 47
  },
  "code": 0,
  "message": "Success",
  "sid": "cha000c32cc@dx19a51f9cec7b8f3812"
}
```

**响应的参数说明：**

| 参数名称                                       | 类型   | 描述                               |
| ---------------------------------------------- | ------ | ---------------------------------- |
| code                                           | int    | 错误码：0表示成功，非0表示错误     |
| message                                        | string | 错误码的描述信息                   |
| sid                                            | string | 本次请求的唯一id                   |
| choices                                        | array  | 大模型结果的数组                   |
| choices.message                                | object | 大模型结果                         |
| choices.message.role                           | string | 大模型的角色                       |
| choices.message.content                        | string | 大模型输出的内容                   |
| choices.message.tool_calls                     | array  | 工具函数调用的数组                 |
| choices.message.tool_calls.id                  | string | 工具函数调用的 ID                  |
| choices.message.tool_calls.type                | string | 工具函数调用的类型，“function"     |
| choices.message.tool_calls.functions           | object | 工具函数调用的具体内容             |
| choices.message.tool_calls.functions.name      | string | 被调用的工具函数名称               |
| choices.message.tool_calls.functions.arguments | string | 工具函数调用的入参                 |
| choices.index                                  | int    | 大模型的结果序号，在多候选中使用   |
| usage                                          | object | 本次请求消耗的token数量            |
| usage.prompt_tokens                            | int    | 用户输入信息，消耗的token数量      |
| usage.completion_tokens                        | int    | 大模型输出信息，消耗的token数量    |
| usage.total_tokens                             | int    | 用户输入+大模型输出，总的token数量 |

_流式请求成功时的响应格式：_*

```
data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546385,"choices":[{"delta":{"role":"assistant","content":"你好"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546385,"choices":[{"delta":{"role":"assistant","content":"，很高兴"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546385,"choices":[{"delta":{"role":"assistant","content":"为你解答问题"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546385,"choices":[{"delta":{"role":"assistant","content":"。\n"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546387,"choices":[{"delta":{"role":"assistant","content":"我是讯飞星火认知大模型，由科大讯飞构建的认知智能系统。"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546388,"choices":[{"delta":{"role":"assistant","content":"我具备与人类进行自然交流的能力，可以高效地满足各领域的认知智能需求。"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546389,"choices":[{"delta":{"role":"assistant","content":"无论你有什么问题或者需要帮助的地方，我都将尽我所能提供支持和解决方案。请随时告诉我你的需求！"},"index":0}]}

data:{"code":0,"message":"Success","sid":"cha000b000c@dx1905cf38fc8b86d552","id":"cha000b000c@dx1905cf38fc8b86d552","created":1719546389,"choices":[{"delta":{"role":"assistant","content":""},"index":0}],"usage":{"prompt_tokens":6,"completion_tokens":68,"total_tokens":74}}

data:[DONE]

```

_流式请求调用工具函数成功时的响应格式：_*

```
data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1664db030f0c0a00_0","type":"function","function":{"name":"get_weather","arguments":""},"index":0}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1664db030f0c0a00_0","type":"function","function":{"name":"","arguments":"{\"location"},"index":0}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1664db030f0c0a00_0","type":"function","function":{"name":"","arguments":"\":\""},"index":0}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1664db030f0c0a00_0","type":"function","function":{"name":"","arguments":"上海市"},"index":0}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1664db030f0c0a00_0","type":"function","function":{"name":"","arguments":"\"}"},"index":0}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1665090314840a01_1","type":"function","function":{"name":"get_weather","arguments":""},"index":1}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1665090314840a01_1","type":"function","function":{"name":"","arguments":"{\"location"},"index":1}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1665090314840a01_1","type":"function","function":{"name":"","arguments":"\":\""},"index":1}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1665090314840a01_1","type":"function","function":{"name":"","arguments":"合肥市"},"index":1}]},"index":0}]}

data: {"code":0,"message":"Success","sid":"cha000a002f@dx19a4f1654d43b4e552","id":"cha000a002f@dx19a4f1654d43b4e552","created":1762263459,"choices":[{"delta":{"role":"assistant","tool_calls":[{"id":"Call_1665090314840a01_1","type":"function","function":{"name":"","arguments":"\"}"},"index":1}]},"index":0}],"usage":{"prompt_tokens":5,"completion_tokens":46,"total_tokens":51}}

data: [DONE]

```

**响应的参数说明：**

| 参数名称                                    | 类型   | 描述                                                |
| ------------------------------------------- | ------ | --------------------------------------------------- |
| code                                        | int    | 错误码：0表示成功，非0表示错误                      |
| message                                     | string | 错误码的描述信息                                    |
| sid                                         | string | 本次请求的唯一id                                    |
| choices                                     | array  | 大模型结果的数组                                    |
| choices.delta                               | object | 大模型结果                                          |
| choices.delta.role                          | string | 大模型的角色                                        |
| choices.delta.content                       | string | 大模型输出的内容                                    |
| choices.delta.tool_calls                    | array  | 工具函数调用的数组                                  |
| choices.delta.tool_calls.id                 | string | 工具函数调用的 ID                                   |
| choices.delta.tool_calls.type               | string | 工具函数调用的类型，“function"                      |
| choices.delta.tool_calls.function           | object | 工具函数调用的具体内容                              |
| choices.delta.tool_calls.function.name      | string | 被调用的工具函数名称                                |
| choices.delta.tool_calls.function.arguments | string | 工具函数调用的入参，需要根据 choices.index 进行拼接 |
| choices.delta.tool_calls.index              | int    | 工具函数调用的 index                                |
| choices.index                               | int    | 大模型的结果序号，在多候选中使用                    |
| usage                                       | object | 本次请求消耗的token数量                             |
| usage.prompt_tokens                         | int    | 用户输入信息，消耗的token数量                       |
| usage.completion_tokens                     | int    | 大模型输出信息，消耗的token数量                     |
| usage.total_tokens                          | int    | 用户输入+大模型输出，总的token数量                  |

### [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_4-2%E8%AF%B7%E6%B1%82%E9%94%99%E8%AF%AF%E5%93%8D%E5%BA%94)4.2请求错误响应

API

```
{
    "error": {
        "message": "invalid user",
        "type": "api_error",
        "param": null,
        "code": null
    }
}

```

SDK

```
openai.AuthenticationError: Error code: 401 - {'error': {'message': 'invalid user', 'type': 'api_error', 'param': None, 'code': None}}
```

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_6-http%E6%B5%81%E5%BC%8F%E8%AF%B7%E6%B1%82%E7%A4%BA%E4%BE%8B)5. HTTP流式请求示例

```
import requests

url = "https://spark-api-open.xf-yun.com/v1/chat/completions"
data = {
        "model": "generalv3.5", # 指定请求的模型
        "messages": [
            {
                "role": "user",
                "content": "你是谁"
            }
        ],
   		"stream": True
    }
header = {
    "Authorization": "Bearer 123456" # 注意此处把“123456”替换为自己的APIPassword
}
response = requests.post(url, headers=header, json=data, stream=True)

# 流式响应解析示例
response.encoding = "utf-8"
for line in response.iter_lines(decode_unicode="utf-8"):
    print(line)
```

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_7-%E4%BD%BF%E7%94%A8openai-sdk%E8%AF%B7%E6%B1%82%E7%A4%BA%E4%BE%8B)6. 使用OpenAI SDK请求示例

```
# 安装openai SDK 
pip install openai
```

```
# 导入SDK，发起请求
from openai import OpenAI
client = OpenAI(
        api_key="控制台获取的APIPassword", 
        base_url = 'https://spark-api-open.xf-yun.com/v1' # 指向讯飞星火的请求地址
    )
completion = client.chat.completions.create(
    model='generalv3.5', # 指定请求的版本
    messages=[
        {
            "role": "user",
            "content": '说一个程序员才懂的笑话'
        }
    ]
)
print(completion.choices[0].message)
```

## [#](https://www.xfyun.cn/doc/spark/HTTP%E8%B0%83%E7%94%A8%E6%96%87%E6%A1%A3.html#_8-%E9%94%99%E8%AF%AF%E7%A0%81%E8%AF%B4%E6%98%8E)7. 错误码说明

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