¶ 大模型标准调用接口
¶ 请求规范
host
headers
Content-Type: application/json
Authorization: Bearer {token}
token 获取
获取token，可以通过聆思大模型平台密钥管理页面生成。注意token生成完妥善保管。
¶ 模型对话调用 - chat.completion
POST /v1/chat/completions
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| model | string | 模型 | 否 | spark-general-1.5 | 可取值：spark-general-1.5: 基础模型v1.5版本;spark-general-2.0: 基础模型v2.0版本； spark-general-3.0: 基础模型v3.0版本；spark-general-3.5: 基础模型v3.5版本；spark-general-4.0: 基础模型v4.0版本；spark-children-chat-1.0: 儿童闲聊模型; spark-vision-preview-1.0: 多模态版本； |
| user | string | 用户id，一个代表你的最终用户的唯一标识符 | 否 | - | 字符串最大长度为32 |
| domain | string | 需要使用的领域 | 否 | general | 可取值： general |
| temperature | float | 核采样阈值。每次模型回复时，相同的提示词可能会产生不同的输出。温度为0.1时将始终产生相同的输出。温度越高随机性越大，创造力越丰富。 | 否 | 0.1 | 最小值是0.1，最大值是1 |
| top_k | int | 用于限制模型在生成每个单词时考虑的候选单词的数量。 | 否 | 4 | 最小值是1，最大值是6 |
| max_tokens | int | 输入输出tokens的最大长度 | 否 | 1024 | 最小值是1，v1.5版本最大值是4096，其余模型版本的最大值是8192 |
| stream | boolean | 是否支持流式 | 否 | false | 当为true时，返回采用server-sent events的协议进行回复 |
| search_plugin | boolean | 是否启动搜索插件 | 否 | false | 当为true时，会进行联网搜索，增强回复，仅在spark-general-1.5、spark-general-3.0、spark-general-3.5、spark-general-4.0支持 |
| messages | Array<message> | 会话和提问 | 是 | - | 需要自行拼接对话历史信息，数组最后是最新的用户提问 |
| message.role | string | 角色 | 是 | - | 可取值： user，assistant ；其中user表示用户的提问，assistant表示AI的回复 ; 若当前message为messages数组的最后一个元素，role的值需为字符串'user' 基础模型v3.5版本支持 system |
| message.content | string | 文本内容 | 是 | - | 该角色的对话内容 |
| functions | Array<function> | function列表 | 否 | - | 该参数只在3.0模型下生效 |
| function.name | string | 名称 | 是 | - | 输入命中后，会返回该名称 |
| function.description | string | 描述 | 是 | - | 用于辅助理解，越详细越有助于大模型理解该function |
| function.parameters | object | 参数 | 是 | - | 函数接受的参数，描述为 JSON Schema 对象 |
¶ function.parameters参数
| 名称 | 类型 | 说明 | 是否必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| type | string | 类型 | 是 | 是 | 参考 JSON Schema ，如： 'string', 'number', 'boolean' ... |
| properties | object | 参数 | 是 | - | 命中该function时需要返回哪些参数 |
| required | array | 必须返回的参数列表 | 是 | - | 命中该function时必须返回的参数字段 |
| properties.x.type | string | 参数类型 | 是 | - | 参考 JSON Schema 类型选项 |
| properties.x.description | string | 参数描述 | 是 | - | 参数的具体描述 |
重要说明:
messages的轮数，建议限制在12轮以内；token的输入输出总数total_tokens为8k，其中Prompt的最大tokens数为4k，Completion的最大tokens数为4k；- 计费包含接口输入输出内容；
- 1个
token约等于1.5个中文汉字或者0.8个英文单词。- 默认开通接口后QPS为10
返回参数
¶ stream为false时的返回参数
response header 中的 content-type 为 application/json
| 名称 | 类型 | 说明 | |
|---|---|---|---|
| id | string | 会话的唯一id | |
| choices | object | - | |
| choices.finish_reason | string | 完成原因 | |
| choices.index | number | - | |
| choices.messages | Array<message> | 模型生成的信息 | |
| message.role | string | 角色 | 固定返回assistant |
| message.content | string | 生成的文本内容 | |
| message.function_call | object | 当请求带functions时返回 | |
| message.function_call.arguments | string | 调用function的参数，由 JSON 格式的模型生成。 | |
| message.function_call.name | string | 调用function的名称。 | |
| created | string | 文本生成时间 | |
| object | string | 类型，固定为chat.completion | |
| usage | object | - | |
| usage.question_tokens | number | 保留字段，可忽略 | |
| usage.prompt_tokens | number | 包含历史问题的总tokens大小 | |
| usage.completion_tokens | number | 回答的tokens大小 | |
| usage.total_tokens | number | prompt_tokens和completion_tokens的和，也是本次交互计费的tokens大小 |
¶ stream为true时的返回参数
response header 中的 content-type 为 text/event-stream
- 采用Data-only的协议
- 每个Data均为json字符串
- 最后一个Data的chunk为字符串[DONE]作为结束
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | 会话的唯一id |
| choices | object | - |
| choices.finish_reason | string | 完成原因 |
| choices.index | number | - |
| choices.delta | Array<delta> | 模型生成的流式信息 |
| delta.content | string | 流式生成的文本内容 |
| delta.function_call | object | 当请求带functions时返回 |
| delta.function_call.arguments | string | 调用function的参数，由 JSON 格式的模型生成。 |
| delta.function_call.name | string | 调用function的名称。 |
| created | string | 文本生成时间 |
| object | string | 类型，固定为chat.completion.chunk |
| usage | object | 通常在最后一个chunk中的json返回 |
| usage.question_tokens | number | 保留字段，可忽略 |
| usage.prompt_tokens | number | 包含历史问题的总tokens大小 |
| usage.completion_tokens | number | 回答的tokens大小 |
| usage.total_tokens | number | prompt_tokens和completion_tokens的和，也是本次交互计费的tokens大小 |
调用示例
¶ 基础模型请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"temperature": 0.5,
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "广州有什么东西玩，十个字内回复"
}
]
}'
// response
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "广州有很多值得玩的地方，比如珠江夜游、白云山、荔枝湾等。此外，广州还有丰富的美食文化和购物场所，例如北京路步行街和天河城购物中心。",
"role": "assistant"
}
}
],
"created": 1683804700,
"id": "cht000d6b4f@dx1880a94b87ab894540",
"object": "chat.completion",
"usage": {
"completion_tokens": 44,
"prompt_tokens": 8,
"question_tokens": 7,
"total_tokens": 52
}
}
¶ 带上下文请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"messages": [
{ "role": "user", "content": "我发你一个数学题，等下帮我回答下？" },
{ "role": "assistant", "content": "当然可以，请随时提问。" },
{ "role": "user", "content": "一加一" }
]
}'
// response
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "一加一的解答过程非常简单。根据加法的定义，将两个数相加得到它们的和。在这个例子中，我们将数字1与数字1相加。\n\n1\n\n+1\n\n-----\n\n2\n\n所以，一加一等于2。",
"role": "assistant"
}
}
],
"created": 1691122989,
"id": "cht000b5caa@dx189bec8f1af9a4b540",
"object": "chat.completion",
"usage": {
"completion_tokens": 63,
"prompt_tokens": 81,
"question_tokens": 52,
"total_tokens": 144
}
}
¶ 流式请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"temperature": 0.5,
"max_tokens": 1024,
"stream": true,
"messages": [
{
"role": "user",
"content": "广州有什么东西玩，十个字内回复"
}
]
}'
// response:
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"广州"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"塔、"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"珠江夜游"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"、陈家祠"}}]}
data: {"usage":null,"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498008,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"、沙面岛、"}}]}
data: {"usage":{"total_tokens":31,"question_tokens":9,"prompt_tokens":10,"completion_tokens":21},"object":"chat.completion.chunk","id":"cht000c1896@dx18833e7c87b9a4b540","created":1684498009,"choices":[{"index":0,"finish_reason":null,"delta":{"content":"白云山公园等。"}}]}
data: [DONE]
¶ 交互模型请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"plugins": ["天气", "菜谱"],
"messages": [
{ "role": "user", "content": "今天天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "明天呢" }
],
"location": {
"latitude": 23.1200491021,
"longitude": 113.307649675
}
}'
//response:
{
"object": "chat.completion",
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "明天广州市全天雷阵雨转多云，出门记得带伞，气温28℃ ~ 34℃，有微风，气温较高，请尽量避免午后高温时段的户外活动。",
"role": "assistant"
}
}
],
"created": 1691121513,
"id": "ara5d64b39a@dx00011827c369a10d00",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 带functions的请求示例
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-general-3.0",
"stream": false,
"messages": [
{
"role": "user",
"content": "今天天气怎么样"
}
],
"functions": [
{
"name": "天气",
"description": "天气插件可以提供天气相关信息。你可以提供指定的地点信息、指定的时间点或者时间段信息，来检索诗词库，精准检索到天气信息。",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "地点，比如北京。"
},
"date": {
"type": "string",
"description": "日期。"
}
},
"required": [
"location"
]
}
}
]
}'
//response:
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "",
"function_call": {
"arguments": "{\"datetime\":\"今天\",\"location\":\"CURRENT_CITY\"}",
"name": "天气"
},
"role": "assistant"
}
}
],
"created": 1701401920,
"id": "cht000b6248@dx18c2374fd38b894550",
"object": "chat.completion",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 3,
"question_tokens": 3,
"total_tokens": 3
}
}
请求失败响应示例
{
"statusCode": 401,
"code": "FST_ERR_UNAUTHORIZED",
"error": "Unauthorized",
"message": "Authentication required. Please provide valid credentials."
}
{
"statusCode": 400,
"code": "FST_ERR_VALIDATION",
"error": "Bad Request",
"message": "body/stream must be boolean"
}
¶ 多模态模型请求示例
图片是链接请求：
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-vision-preview-1.0",
"temperature": 0.1,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "这是一只什么猫"
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.listenai.com/images/3983d40708dbc35b25999a8d46dce40a.jpeg"
}
}
]
}
]
}'
图片是base64请求：
curl --request POST \
--url https://api.listenai.com/v1/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-vision-preview-1.0",
"temperature": 0.1,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "这是一只什么猫"
},
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,xxxxx"
}
}
]
}
]
}'
// response
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "这是一只小猫，看起来像是长毛品种。不过，从这张图片中很难确定它的具体品种。如果你有更多关于这只猫的信息或者背景，我可能能提供更多帮助。",
"role": "assistant"
}
}
],
"created": 1721880287,
"id": "cht000bf8da@dx190e81013e8b81a550",
"object": "chat.completion",
"usage": {
"completion_tokens": 39,
"prompt_tokens": 282,
"question_tokens": 9,
"total_tokens": 321
}
}
¶ 向量计算调用 - embedding
POST /v1/embedding
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| input | string | query文本 | 是 | 不超过256个字符，超过会只截取前256个字符进行向量化 |
请求示例
curl --request POST \
--url https://api.listenai.com/v1/embedding \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"input": "洗衣机报U04错误"
}'
响应示例
- 请求成功
{
// json序列化后的单精度浮点数数组，共包含1024个浮点数
"data": [-0.17944336,...,0.115722656]
}
¶ 决策调用-makes
POST /v1/makes
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| model | string | 模型名称 | 是 | 可选值：spark-interface-1.0 |
| task | string | 执行任务 | 是 | 支持中英文， 可选值：rewrite: 改写 ；intent_split: 意图拆解 ；intent_domain: 意图落域 ；tidy: 语义规整 ；denial: 拒识 ； |
| messages | Array<message> | 会话和提问 | 是 | 需要自行拼接对话历史信息，数组最后是最新的用户提问 |
| message.role | string | 角色 | 是 | 取值为 user，assistant ；其中user表示用户的提问，assistant表示AI的回复 ; 若当前message为messages数组的最后一个元素，role的值需为字符串'user' |
| message.content | string | 文本内容 | 是 | 该角色的对话内容 |
¶ 改写请求
sequenceDiagram
User->>LLMservice: 调用改写能力
alt messages参数数组长度等于1
LLMservice-->>User: 不作改写,原文本返回
else messages参数数组长度大于1
LLMservice-->>LLMservice: 进行改写处理
LLMservice-->>User: 返回改写结果
end
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "rewrite",
"messages": [
{ "role": "user", "content": "今天广州天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "那明天呢" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"text": "那广州明天天气呢"
}
],
"created": 1691122044,
"id": "wgw000c1e65@dx189beba8ebb7824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 意图拆解
sequenceDiagram
User->>LLMservice: 调用意图拆解能力
alt messages参数数组长度等于1
LLMservice-->>LLMservice: 进行意图拆解处理
LLMservice-->>User: 返回意图拆解结果
else messages参数数组长度大于1
LLMservice-->>LLMservice: 进行改写处理
LLMservice-->>LLMservice: 改写结果进行意图拆解处理
LLMservice-->>User: 返回意图拆解结果
end
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "intent_split",
"messages": [
{ "role": "user", "content": "我要打开空调，然后调到18度，对了，再帮我加热下我的汉堡" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"intent": "打开空调"
},
{
"index": 1,
"intent": "空调调到18度"
},
{
"index": 2,
"intent": "加热我的汉堡"
}
],
"created": 1691122173,
"id": "wgw000c1e67@dx189bebc843c7824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 意图落域
sequenceDiagram
User->>LLMservice: 调用意图落域能力
alt messages参数数组长度等于1
LLMservice-->>LLMservice: 进行意图落域处理
LLMservice-->>User: 返回意图落域结果
else messages参数数组长度大于1
LLMservice-->>LLMservice: 进行改写
LLMservice-->>LLMservice: 改写结果进行意图落域处理
LLMservice-->>User: 返回意图落域结果
end
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "intent_domain",
"messages": [
{ "role": "user", "content": "今天广州天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "那明天呢" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"skill": "天气",
"intent": "查询天气温度"
}
],
"created": 1691122235,
"id": "wgw000c1e6d@dx189bebd77d27824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 拒识
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "denial",
"messages": [
{ "role": "user", "content": "今天广州天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "那明天天气" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"type": 1
}
],
"created": 1691122235,
"id": "wgw000c1e6d@dx189bebd77d27824532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 语义规整（改写+拆解）
调用示例
curl --request POST \
--url https://api.listenai.com/v1/makes \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"model": "spark-interface-1.0",
"task": "tidy",
"messages": [
{ "role": "user", "content": "今天广州天气怎么样" },
{ "role": "assistant", "content": "广州今天全天阴，气温27℃ ~ 35℃，空气质量优，有北风微风，酷热难耐，请做好防暑降温的工作。" },
{ "role": "user", "content": "那明天呢，顺便看下有什么地方推荐去玩" }
]
}'
{
"object": "makes",
"choices": [
{
"index": 0,
"intent": "明天广州天气怎么样"
},
{
"index": 1,
"intent": "推荐去玩的地方"
}
],
"created": 1711089082,
"id": "wgw000cce58@dx18e64db5e3ea14d532",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}
¶ 文生图 - images.generations
POST /v1/images/generations
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| prompt | string | 文本 | 是 | - |
| response_format | string | 生成图片类型 | 否 | 默认为url。 可选值：b64_json: 返回base64格式 ；url: 返回图片地址 |
调用示例
curl --request POST \
--url https://api.listenai.com/v1/images/generations \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"prompt": "帮我画一只猪",
"response_format": "url"
}'
{
"created": 1708673091,
"id": "cht000b119c@dx18dd4da3808b8f2550",
"data": [
{
"url": "https://cdn.iflyos.cn/llm/users/1846/images/5cc9f98d-97ca-4660-86f5-312a1b498bd1.png"
}
]
}