创建文本生成请求
本接口为融云提供的智能对话生成接口,基于多轮对话历史生成符合语境的 AI 回复,适用于构建聊天机器人、智能客服、对话式助手等场景。 您可调用平台提供的 LLM(大语言模型)或 VLM(视觉语言模型),利用丰富的参数配置控制生成内容的风格、随机性及结构化输出。
请求方法
POST: <ai-api-base-url>/llm/v1/chat/completions
其中,<ai-api-base-url>
为您的 API Key 所属数据中心的域名。目前仅支持北京数据中心的域名:https://ai.rong-api.com
。
请求头参数
参数名 | 类型 | 必传 | 默认值 | 说明 |
---|---|---|---|---|
Authorization | string | 是 | - | 身份认证令牌,格式为 Bearer <your API key> ,需替换为实际 API Key,用于验证用户权限。 |
正文参数
- LLM
- VLM
参数名 | 类型 | 必传 | 默认值 | 说明 |
---|---|---|---|---|
model | enum<string> | 是 | - | 选择调用的模型名称,仅支持融云官方发布模型,传入非平台模型将返回错误:“暂不支持此种模型”。平台将定期更新可用模型列表。 |
messages | object[] | 是 | - | 对话历史消息列表,包含当前对话的上下文,用于构建上下文语境,支持多轮对话追溯。长度为 1-10 个元素。 |
stream | boolean | 否 | true | 是否启用流式返回。
|
max_tokens | integer | 否 | 512 | 生成内容的最大 token 数,范围为 1 ≤ x ≤ 16384。 |
enable_thinking | boolean | 否 | true | (仅适用于 Qwen3 系列模型) 思考模式开关:
|
thinking_budget | integer | 否 | 4096 | (仅适用于 Qwen3 模型) 指定思考过程(链式推理)的最大 token 预算,范围为 1 ≤ x ≤ 32768。 |
min_p | number | 否 | 0.05 | (仅适用于 Qwen3 模型) 动态过滤阈值,基于 token 概率调整生成内容的随机性,范围为 0 ≤ x ≤ 1。 |
stop | string[] | null | 否 | null | 终止生成的触发序列(最多 4 个),生成的文本不包含这些序列。长度为 1 - 4 个元素。 |
temperature | number | 否 | 0.7 | 控制生成内容的随机性,值越高(如1.0)随机性越强,适合创造性内容,值越低(如0.1)越确定,适合事实性回答。 |
top_p | number | 否 | 0.7 | 核采样参数,通过累积概率动态调整 token 选择范围,与 temperature 共同控制随机性。 |
top_k | number | 否 | 50 | 限制每次预测时仅考虑概率最高的 top_k 个 token,减少随机性,范围通常为正数。 |
frequency_penalty | number | 否 | 0.5 | 频率惩罚,抑制重复 token 的生成概率,避免内容冗余。 |
n | integer | 否 | 1 | 生成结果的数量,返回多个结果时需去重或筛选。 |
response_format | object | 否 | - | 指定模型输出的格式,用于规范生成内容的结构。如通过{"type": "json_object"} 来指定输出 JSON 结构,{"type": "text"} 指定返回为纯文本。 |
tools | object[] | 否 | - | 允许模型调用的工具列表(目前仅支持函数),最多 128 个函数,用于实现工具调用能力(如查询数据、执行计算等)。 |
messages
参数说明:
字段 | 类型 | 必传 | 说明 |
---|---|---|---|
role | enum<string> | 是 | 消息作者的角色。可选值为:system (系统)、user (用户)或assistant (助手)。示例: user |
content | string | 是 | 消息的内容。 示例:“如何使用融云 AI 平台 ?” |
tools
参 数说明:
字段 | 类型 | 必传 | 说明 |
---|---|---|---|
type | enum<string> | 是 | 工具类型。目前仅支持 function 。可选值: function 。 |
function | object | 是 | 函数相关配置对象。 |
function
子属性:
字段 | 类型 | 必传 | 说明 |
---|---|---|---|
function.name | string | 是 | 要调用的函数名称。必须由字母(a-z、A-Z)、数字(0-9)、下划线或短横线组成,最长 64 字符。 |
function.description | string | 否 | 函数功能描述,用于模型判断何时及如何调用该函数。 |
function.parameters | object | 否 | 函数接受的参数,以 JSON Schema 对象描述。 示例:参见指南; 格式说明:参见 JSON Schema 文档。 注意:若省略此参数,则函数参数列表为空。 |
function.strict | boolean/null | 否 | 生成函数调用时是否启用严格模式验证模式。
|
参数名 | 类型 | 必传 | 默认值 | 说明 |
---|---|---|---|---|
model | enum<string> | 是 | Qwen/Qwen2.5-VL-72B-Instruct | 选择调用的模型名称,仅支持融云官方发布模型,传入非平台模型将返回错误:“暂不支持此种模 型”。平台将定期更新可用模型列表。 |
messages | object[] | 是 | 无 | 对话历史消息列表,包含当前对话的上下文,用于构建上下文语境,支持多轮对话追溯。长度为 1-10 个元素。 |
stream | boolean | 否 | false | 是否启用流式返回。
|
max_tokens | integer | 否 | 512 | 生成内容的最大 token 数,范围为 1 ≤ x ≤ 4096。 |
stop | string[] | null | 否 | 无 |
temperature | number | 否 | 0.7 | 控制生成内容的随机性,值越高(如1.0)随机性越强,适合创造性内容,值越低(如0.1)越确定,适合事实性回答。 |
top_p | number | 否 | 0.7 | 核采样参数,通过累积概率动态调整 token 选择范围,与 temperature 共同控制随机性。 |
top_k | number | 否 | 50 | 限制每次预测时仅考虑概率最高的 top_k 个 token,减少随机性,范围通常为正数。 |
frequency_penalty | number | 否 | 0.5 | 频率惩罚,抑制重复 token 的生成概率,避免内容冗余。 |
n | integer | 否 | 1 | 生成结果的数量,返回多个结果时需去重或筛选。 |
response_format | object | 否 | 无 | 指定模型输出的格式,用于规范生成内容的结构。如通过{"type": "json_object"} 来指定输出 JSON 结构,{"type": "text"} 指定返 回为纯文本。 |
messages
参数说明:
字段 | 类型 | 必传 | 说明 |
---|---|---|---|
role | enum<string> | 是 | 消息作者的角色。可选值为:system (系统)、user (用户)或assistant (助手)。示例: user |
content | object[] | 是 | 对话中的内容部分。数组最小长度为 1。每个数组元素必须指定 type 字段,类型可以是 text (文本)或 image_url (图片链接)。 |
content
参数详细说明:
字段 | 类型 | 必传 | 说明 |
---|---|---|---|
type | enum<string> | 是 | 对话内容部分的类型,可选值:text (表示内容为文本)或 image_url (表示内容为图片链接或 Base64 数据)。 |
text | string | 否 | 当 type 为 text 时,表示文本内容。默认值为 "Describe this picture." 。 |
image_url | object | 否 | 当 type 为 image_url 时,表示图片内容。包含以下字段:
|
请求 示例
- cURL
- Python
- JavaScript
bash
curl --location '<ai-api-base-url>/llm/v1/chat/completions' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "Pro/Qwen/Qwen2.5-7B-Instruct",
"messages": [
{
"role": "system",
"content": "请介绍一下融云 AI API 服务。"
}
],
"stream": false,
"temperature": 1.0,
"frequency_penalty": 0.0,
"presence_penalty": 0.0,
"top_p": 0.7
}'
python
import requests
url = "<ai-api-base-url>/llm/v1/chat/completions"
payload = {
"model": "Pro/Qwen/Qwen2.5-7B-Instruct",
"messages": [
{
"role": "user",
"content": "请介绍一下融云 AI API 服务。"
}
],
"stream": False,
"temperature": 1.0,
"frequency_penalty": 0.0,
"presence_penalty": 0.0,
"top_p": 0.7
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
JavaScript
const options = {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"model": "Qwen/Qwen2.5-14B-Instruct",
"messages": [{"role": "user", "content": "请介绍一下融云 AI API 服务。"}],
"stream": false,
"max_tokens": 512,
"enable_thinking": false,
"thinking_budget": 4096,
"min_p": 0.05,
"stop": null,
"temperature": 0.7,
"top_p": 0.7,
"top_k": 50,
"frequency_penalty": 0.5,
"n": 1,
"response_format": {"type": "text"}
})
};
fetch('<ai-api-base-url>/llm/v1/chat/completions', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
返回结果
参数名 | 类型 | 说明 |
---|---|---|
id | string | 本次请求的唯一标识符,用于追踪和调试。 |
choices | object[] | 生成的回复列表,每个元素包含:
|
usage | object | 资源使用统计信息,包含:
|
created | integer | 时间戳,表示响应生成的 Unix 时间。 |
model | string | 实际调用的模型名称,可能与入参中的模型一致或因平台调整而变化。 |
object | enum | 响应类型,固定为 chat.completion ,标识为聊天完成响应。 |
返回结果示例
JSON
{
"id": "<string>",
"choices": [
{
"message": {
"role": "assistant",
"content": "<string>",
"reasoning_content": "<string>",
"tool_calls": [
{
"id": "<string>",
"type": "function",
"function": {
"name": "<string>",
"arguments": "<string>"
}
}
]
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 123,
"completion_tokens": 123,
"total_tokens": 123
},
"created": 123,
"model": "<string>",
"object": "chat.completion"
}