Spark http调用文档

[#](about:blank#_1-%E6%8E%A5%E5%8F%A3%E8%AF%B4%E6%98%8E) 1. 接口说明
----------------------------------------------------------------

**Tips：**

1.  计费包含接口的输入和输出内容
2.  1tokens 约等于1.5个中文汉字 或者 0.8个英文单词
3.  Spark Lite支持\[搜索\]内置插件；Spark Pro和Spark Max支持\[搜索\]、\[天气\]、\[日期\]、\[诗词\]、\[字词\]、\[股票\]六个内置插件
4.  Spark Max现已支持system、Function Calling 功能。

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

**Tips: 星火大模型API当前有Lite、Pro、Max和4.0 Ultra四个版本，各版本独立计量tokens。**

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

```

鉴权方案：[鉴权方式使用说明](https://docs.iflyaicloud.com/doc/227/ "鉴权方式使用说明")

[#](about:blank#_3-%E8%AF%B7%E6%B1%82%E8%AF%B4%E6%98%8E) 3. 请求说明
----------------------------------------------------------------

### [#](about:blank#_3-1-%E8%AF%B7%E6%B1%82%E5%A4%B4) 3.1. 请求头

请到控制台获取APIKey（假使APIKey是key123456）和APISecret（假使APISecret是secret123456），则请求头如下：

```
Content-Type: application/json
Authorization: Bearer key123456:secret123456

```

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

```
curl -i -k -X POST 'https://spark-api-open.xf-yun.com/v1/chat/completions' \
--header 'Authorization: Bearer key123456:secret123456' \
--header 'Content-Type: application/json' \
--data '{
    "model":"generalv3.5",
    "messages": [
        {
            "role": "user",
            "content": "来一个只有程序员能听懂的笑话"
        }
    ]
}'

```

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

| 参数名称 | 类型 | 是否必填 | 参数要求 | 参数说明 |
| --- | --- | --- | --- | --- |
| model | String | 是 | 取值为\[general,generalv3,generalv3.5,4.0Ultra\] | 选择请求的模型版本  general指向Lite版本；generalv3指向Pro版本；generalv3.5指向Max版本；4.0Ultra指向4.0 Ultra版本； |
| stream | Boolean | 否 | 默认False, | 是否开启流式传输 |
| temperature | Float | 否 | 取值范围 (0，1\] ，默认值0.5 | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max\_tokens | Int | 否 | 取值为\[1,8192\]，默认为4096。 | 模型回答的tokens的最大长度 |
| top\_k | Int | 否 | 取值为\[1，6\],默认为4 | 从k个候选中随机选择⼀个（⾮等概率） |

#### [#](about:blank#_3-2-1-message%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E) 3.2.1 message字段说明

| 参数名称 | 类型 | 是否必填 | 参数要求 | 参数说明 |
| --- | --- | --- | --- | --- |
| role | String | 是 | 取值为\[system,user,assistant\] | system用于设置对话背景，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. 接口响应
----------------------------------------------------------------

公共响应内容

| 参数名称 | 类型 | 参数说明 |
| --- | --- | --- |
| code | Int | 错误码，0表示正常，非0表示出错；详细释义可在接口说明文档最后的错误码说明了解 |
| message | String | 会话是否成功的描述信息 |
| sid | string | 会话的唯一id，用于讯飞技术人员查询服务端会话日志使用,出现调用错误时建议留存该字段 |

非流式响应内容choices模块

| 参数名称 | 类型 | 参数说明 |
| --- | --- | --- |
| message.role | String | 角色标识，固定为assistant，标识角色为AI |
| message.content | String | AI的回答内容 |
| index | Int | 结果序号，取值为\[0,10\]; 当前为保留字段，开发者可忽略 |
| usage.prompt\_tokens | Int | 历史问题消耗的tokens |
| usage.completion\_tokens | Int | AI回答消耗的tokens |
| usage.total\_tokens | Int | prompt\_tokens和completion\_tokens的和，也是本次交互一共消耗的tokens |

流式响应内容choices模块

| 参数名称 | 类型 | 参数说明 |
| --- | --- | --- |
| delta.role | String | 角色标识，固定为assistant，标识角色为AI |
| delta.content | String | AI的回答内容 |
| index | Int | 结果序号，取值为\[0,10\]; 当前为保留字段，开发者可忽略 |
| usage.prompt\_tokens | Int | 历史问题消耗的tokens, 仅最后一帧结果返回 |
| usage.completion\_tokens | Int | AI回答消耗的tokens, 仅最后一帧结果返回 |
| usage.total\_tokens | Int | prompt\_tokens和completion\_tokens的和，也是本次交互一共消耗的tokens, 仅最后一帧结果返回 |

[#](about:blank#_5-http%E9%9D%9E%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": "你是谁"
            }
        ]
    }
header = {
    "Authorization": "Bearer key123456:secret123456" # 注意此处替换自己的key和secret
}
response = requests.post(url, headers=header, json=data)
print(response.text)

```

[#](about:blank#_6-http%E6%B5%81%E5%BC%8F%E8%AF%B7%E6%B1%82%E7%A4%BA%E4%BE%8B) 6. 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 key123456:secret123456" # 注意此处替换自己的key和secret
}
response = requests.post(url, headers=header, json=data, stream=True)

# 流式响应解析示例
response.encoding = "utf-8"
for line in response.iter_lines(decode_unicode="utf-8"):
    line = line[5:]
    if line:
        print(json.loads(line)['choices'][0]["delta"]["content"])

```

[#](about:blank#_7-%E4%BD%BF%E7%94%A8openai-sdk%E8%AF%B7%E6%B1%82%E7%A4%BA%E4%BE%8B) 7. 使用OpenAI SDK请求示例
--------------------------------------------------------------------------------------------------------

```
# 安装openai SDK 
pip install openai

```

```
# 导入SDK，发起请求
from openai import OpenAI
client = OpenAI(
				# 控制台获取key和secret拼接，假使APIKey是key123456，APISecret是secret123456
        api_key="key123456:secret123456", 
        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)

```

[#](about:blank#_8-%E9%94%99%E8%AF%AF%E7%A0%81%E8%AF%B4%E6%98%8E) 8. 错误码说明
--------------------------------------------------------------------------

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