文本生成
调用本接口,发起一次对话请求。
支持模型列表
支持模型列表请查看开始使用-模型列表-文本生成。
权限说明
调用本文API,需使用API Key鉴权方式。使用API Key鉴权调用API流程,具体调用流程,请查看认证鉴权。
请求参数
模型ID,说明:
(1)预置服务,可选值请参考开始使用-模型列表-文本生成页,表格中model入参列
(2)平台训练模型或预置模型,可以通过查看服务详情获取该字段值,详情请查看千帆控制台-在线推理:model值为服务详情中对应的API名称,如下图所示:
聊天上下文信息。说明:
(1)messages成员不能为空,1个成员表示单轮对话,多个成员表示多轮对话,例如:
· 1个成员示例,"messages": [ {"role": "user","content": "你好"}]
· 3个成员示例,"messages": [ {"role": "user","content": "你好"},{"role":"assistant","content":"需要什么帮助"},{"role":"user","content":"自我介绍下"}]
(2) 最后一个message为当前请求的信息,前面的message为历史对话信息
(3)messages的role说明:
① 第一条message的role必须是user或system
② 最后一条message的role必须是user或tool,如果是ERNIE 4.5或ERNIE X1 Turbo系列,最后一条message的role必须是user
③ 如果未使用function call功能:
· 当第一条message的role为user,role值需要依次为user -> assistant -> user...,即奇数位message的role值必须为user或function,偶数位message的role值为assistant,例如:示例中message中的role值分别为user、assistant、user、assistant、user;奇数位(红框)message中的role值为user,即第1、3、5个message中的role值为user;偶数位(蓝框)值为assistant,即第2、4个message中的role值为assistant
· 当第一条message的role为system,role值需要依次为system -> user-> assistant -> user...
④ 如果使用function call功能
· 当第一条message的role为user,role值需要依次为user -> assistant -> user/tool ...
· 当第一条message的role为system,role值需要依次为system -> user/tool -> assistant -> user/tool ...
· 注意,支持连续多条role=tool的消息。当开启函数并行调用即parallel_tool_calls=true时,可能会返回多个tool_call,每个tool_call需要对应到一条role=tool的消息来提供函数调用结果。例如:示例中message中的role值分别为user、assistant、user、assistant、tool、tool;第4个message中的role值为assistant,触发了函数并行调用,返回了两个tool_call,需要连续两条role=tool的消息提供函数调用结果,即第5、6个消息message中的role值为tool
(4)message中的content总长度不能超过对应model的输入字符限制和输入tokens限制,请查看各模型上下文长度说明
显示子属性
隐藏子属性
显示子属性
隐藏子属性
当前支持以下:
· user
: 表示用户
· assistant
: 表示对话助手
· system
:表示人设,当模型为GLM-Z1-Rumination-32B-0414时,不支持该字段值
多选一,只需要符合下列任意一组子节点
对话内容,说明:
(1)不能为空
(2)最后一个message对应的content不能为blank字符,如空格、"\n"、“\r”、“\f”等
显示子属性
隐藏子属性
显示子属性
隐藏子属性
函数调用,function call场景下第一轮对话的返回,第二轮对话作为历史信息在message中传入
显示子属性
隐藏子属性
显示子属性
隐藏子属性
function call的唯一标识,由模型生成
固定值function
function call的具体内容
显示子属性
隐藏子属性
函数名称
函数参数
说明:
(1)当role为tool时,该字段必填
(2)模型生成的function call id,对应tool_calls中的tool_calls[].id
(3)调用方应该传递真实的、由模型生成id,否则效果有损
是否以流式接口的形式返回数据,说明:
(1)可选值:
· true
:是,按SSE协议逐块返回内容,以一条data: [DONE]
消息结束
· false
:否,默认false
(2)beam search模型只能为false
流式响应的选项,当字段stream为true
时,该字段生效
显示子属性
隐藏子属性
流式响应是否输出usage,说明:
· true
:是,设置为true
时,在最后一个chunk会输出一个字段,这个chunk上的usage字段显示整个请求的token统计信息
· false
:否,流式响应默认不输出usage
说明:
(1)较高的数值会使输出更加随机,而较低的数值会使其更加集中和确定
(2)取值范围:
· 当模型为DeepSeek-V3,即model值为deepseek-v3、deepseek-v3-241226,取值范围[0,2]
· 当模型为Llama-4-Maverick、Llama-4-Scout、GLM-Z1-32B-0414、Qianfan-8B或Qianfan-70B,取值范围[0,2],默认0.6
· 当模型为Qwen2.5、Qwen3(非思考模式)或Qianfan-Agent-Intent,取值范围[0,2],默认0.7
· 当模型为Qwen3(思考模式),取值范围[0,2],默认0.6
· 当模型为GLM-4-32B-0414或GLM-Z1-Rumination-32B-0414,取值范围[0,2],默认0.95
· 当模型为Qianfan-Sug,取值范围(0, 1.0],默认0.8
· 其他模型,默认1.0,范围 (0, 1.0],不能为0
(3)不支持以下模型:
· DeepSeek-Reasoner
· DeepSeek-R1-Distill系列
· QwQ-32B
· ERNIE X1 Turbo系列
说明:
(1)影响输出文本的多样性,取值越大,生成文本的多样性越强
(2)默认值:
· 当模型为GLM-Z1-32B-0414、Qianfan-8B或Qianfan-70B,取值范围[0, 1.0],默认0.95
· 当模型为Llama-4-Maverick或Llama-4-Scout,取值范围[0, 1.0],默认0.9
· 当模型为Qwen2.5、Qwen3(非思考模式)、Qianfan-Agent-Intent或Qianfan-Sug,取值范围[0,1.0],默认0.8
· 当模型为Qwen3(思考模式),取值范围[0,1.0],默认0.95
· 其他模型,取值范围[0,1.0],默认1.0
(3)不支持以下模型:
· DeepSeek-Reasoner
· DeepSeek-R1-Distill系列
· QwQ-32B
· ERNIE X1 Turbo系列
通过对已生成的token增加惩罚,减少重复生成的现象。说明:
(1)值越大表示惩罚越大
(2)默认1.0,取值范围:[1.0, 2.0]
(3)不支持以下模型:
· DeepSeek-V3
· DeepSeek-Reasoner
· DeepSeek-R1-Distill系列
· QwQ-32B
· ERNIE X1 Turbo系列
说明:
(1)取值范围: (0,2147483647),会由模型随机生成,默认值为空
(2)如果指定,系统将尽最大努力进行确定性采样,以便使用相同seed和参数的重复请求返回相同的结果
(3)不支持以下模型:
· ERNIE X1 Turbo系列
· Qwen2.5
· Qianfan-Agent-Intent
生成停止标识,当模型生成结果以stop中某个元素结尾时,停止文本生成。说明:
(1)每个元素长度不超过20字符
(2)最多4个元素
(3)不支持以下模型:ERNIE X1 Turbo系列
显示子属性
隐藏子属性
说明:
(1)正值根据迄今为止文本中的现有频率对新token进行惩罚,从而降低模型逐字重复同一行的可能性
(2)取值范围:[-2.0, 2.0],默认值0.0
(3)适用于以下模型:
· ernie-speed-8k
· ernie-speed-128k
· ernie-speed-pro-128k
· ernie-lite-8k
· ernie-lite-pro-128k
· ernie-tiny-8k
· ernie-char-8k
· ernie-char-fiction-8k
· Qwen3系列
说明:
(1)正值根据token记目前是否出现在文本中来对其进行惩罚,从而增加模型谈论新主题的可能性
(2)取值范围:[-2.0, 2.0],默认值0.0
(3)适用于以下模型:
· ernie-speed-8k
· ernie-speed-128k
· ernie-speed-pro-128k
· ernie-lite-8k
· ernie-lite-pro-128k
· ernie-tiny-8k
· ernie-char-8k
· ernie-char-fiction-8k
· Qwen3系列
说明:
(1)控制模型生成文本时连续序列中的重复度,提高repetition_penalty可以降低模型生成的重复度
(2)取值范围(0.0, 2.0],默认值1.0
(3)适用于Qwen3系列模型
一个可触发函数的描述列表,支持模型请参考开始使用-模型-Function calling-支持模型范围。
显示子属性
隐藏子属性
显示子属性
隐藏子属性
工具类型,取值function
函数说明
显示子属性
隐藏子属性
函数名
函数描述
多选一,只需要符合下列任意一组子节点
说明:
(1)支持模型请参考开始使用-模型-Function calling-支持模型范围
(2)string类型,可选值如下:
· none
:不希望模型调用任何function,只生成面向用户的文本消息
· auto
:模型会根据输入内容自动决定是否调用函数以及调用哪些function
· required
:希望模型总是调用一个或多个function
(3)当为tool_choice类型,指在函数调用场景下,提示大模型选择指定的函数,指定的函数名必须在tools中存在
显示子属性
隐藏子属性
说明:
· none
:不希望模型调用任何function,只生成面向用户的文本消息
· auto
:模型会根据输入内容自动决定是否调用函数以及调用哪些function
· required
:希望模型总是调用一个或多个function
tool_choice说明
显示子属性
隐藏子属性
指定工具类型,固定值function
指定要使用的函数
显示子属性
隐藏子属性
指定要使用的函数名
说明:
(1)支持模型请参考开始使用-模型-Function calling-支持模型范围
(2)可选值:
· true
:表示开启函数并行调用,默认开启
· false
:表示关闭函数并行调用
搜索增强的选项,说明:
(1)默认不传关闭
(2)支持模型请参考开始使用-模型-联网搜索-支持模型列表
显示子属性
隐藏子属性
是否开启实时搜索功能,说明:
(1)如果关闭实时搜索,角标和溯源信息都不会返回
(2)可选值:
· true
:开启
· false
:关闭,默认false
是否开启上角标返回,说明:
(1)enable为true
时生效
(2)可选值:
· true
:开启;如果开启,在触发了搜索增强的场景下,响应内容会附上角标,并带上角标对应的搜索溯源信息
· false
:未开启,默认false
(3)如果检索内容包含非公开网页,角标不生效
是否返回搜索溯源信息,说明:
(1)enable 为 true
时生效
(2)可选值:
· true
:返回;如果为true
,在触发了搜索增强的场景下,会返回搜索溯源信息search_results
· false
:不返回,默认false
(3)如果检索内容为非公开网页,即使触发搜索也不返回溯源信息
是否返回搜索信号,说明:
(1)enable 为 true
时生效
(2) 可选值:
· true
:返回;如果为true
触发搜索,会通过delta_tag:search_status
表示这一包是信号包。
· false
:不返回,默认false
指定响应内容的格式,说明:
(1)对于生成式人工智能大模型,可能会出现效果不满足的情况
(2)不支持以下模型:ERNIE X1 Turbo系列
显示子属性
隐藏子属性
指定响应内容的格式,可选值:
· json_object
:以json格式返回,可能出现不满足效果情况
· text
:以文本格式返回,默认为text
· json_schema
:以json_scheam规定的格式返回
给每条请求增加自定义标签,可以在日志挖掘环节精细化遴选推理日志;说明:
(1)元素个数最大支持16个
(2)key和value必须都是string类型
是否开启思考模式,说明:
(1)可选值:
· true
:开启
· false
:未开启,默认值为false
(2)适用于 Qwen3 系列模型
表示最终用户的唯一标识符
POST /v2/chat/completions HTTP/1.1
Host: qianfan.baidubce.com
Authorization: authorization string
{
"model": "ernie-3.5-8k",
"messages": [
{
"role": "system",
"content": "平台助手"
},
{
"role": "user",
"content": "你好"
}
]
}
示例代码
curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
--data '{
"model": "ernie-3.5-8k",
"messages": [
{
"role": "system",
"content": "平台助手"
},
{
"role": "user",
"content": "你好"
}
]
}'
import requests
import json
def main():
url = "https://qianfan.baidubce.com/v2/chat/completions"
payload = json.dumps({
"model": "ernie-3.5-8k",
"messages": [
{
"role": "system",
"content": "平台助手"
},
{
"role": "user",
"content": "你好"
}
]
})
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer bce-v3/ALTAK-*********/614fb**********'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
if __name__ == '__main__':
main()
curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
--header 'Authorization: Bearer bce-v3/ALTAK-CM0****SU/a8cfadb****8' \
--header 'Content-Type: application/json' \
--data '{
"model": "ernie-4.0-8k",
"messages": [{
"role": "user",
"content": "查一下上海和北京现在的天气"
}],
"tools": [{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "天气查询工具",
"parameters": {
"properties": {
"location": {
"description": "地理位置,精确到区县级别",
"type": "string"
},
"time": {
"description": "时间,格式为YYYY-MM-DD",
"type": "string"
}
},
"required": ["location", "time"],
"type": "object"
}
}
}],
"stream": false,
"tool_choice": "auto"
}'
curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
--header 'Authorization: Bearer bce-v3/ALTAK-CBb******U/a8cfa******a468' \
--header 'Content-Type: application/json' \
--data '{
"model": "ernie-4.0-8k",
"messages": [
{
"role": "user",
"content": "查一下上海和北京现在的天气"
},
{
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "19c443b42d3f3000",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\"location\": \"上海\", \"time\": \"2024-11-13\"}"
}
},
{
"id": "19c443b42d3f3001",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\"location\": \"北京\", \"time\": \"2024-11-13\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "19c443b42d3f3000",
"name": "get_current_weather",
"content": "{\"temperature\": \"25\", \"unit\": \"摄氏度\", \"description\": \"上海\"}"
},
{
"role": "tool",
"tool_call_id": "19c443b42d3f3001",
"name": "get_current_weather",
"content": "{\"temperature\": \"20\", \"unit\": \"摄氏度\", \"description\": \"北京\"}"
}
],
"tools": [{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "天气查询工具",
"parameters": {
"properties": {
"location": {
"description": "地理位置,精确到区县级别",
"type": "string"
},
"time": {
"description": "时间,格式为YYYY-MM-DD",
"type": "string"
}
},
"required": ["location", "time"],
"type": "object"
}
}
}],
"stream": false,
"tool_choice" : "auto"
}'
返回响应
一分钟内允许的最大tokens消耗,包含输入tokens和输出tokens
一分钟内允许的最大请求次数
达到TPM速率限制前,剩余可消耗的tokens数配额,如果配额用完,将会在0-60s后刷新
达到RPM速率限制前,剩余可发送的请求数配额,如果配额用完,将会在0-60s后刷新
本次请求的唯一标识,可用于排查问题
回包类型 chat.completion:多轮对话返回
时间戳
说明:
(1)如果是预置服务,返回模型ID
(2)如果是sft后部署的服务,该字段返回model:modelversionID,model与请求参数相同,是本次请求使用的大模型ID;modelversionID用于溯源
多选一,只需要符合下列任意一组子节点
显示子属性
隐藏子属性
stream=false时,返回该内容,返回类型为choices
显示子属性
隐藏子属性
choice列表中的序号
响应信息,当stream=false时返回
显示子属性
隐藏子属性
当前支持以下:
· user: 表示用户
· assistant: 表示对话助手
· system:表示人设
message名
对话内容
函数调用,function call场景下第一轮对话的返回,第二轮对话作为历史信息在message中传入
显示子属性
隐藏子属性
显示子属性
隐藏子属性
function call的唯一标识,由模型生成
固定值function
function call的具体内容
显示子属性
隐藏子属性
函数名称
函数参数
说明:
(1)当role=tool时,该字段必填
(2)模型生成的function call id,对应tool_calls中的tool_calls[].id
(3)调用方应该传递真实的、由模型生成id,否则效果有损
思维链内容,说明:只有当模型为DeepSeek-R1有效
输出内容标识,说明:
· stop:模型自然停止或命中提供的停止序列
· length:达到了最大的token数
· content_filter:输出内容被截断、兜底、替换为**等
· tool_calls:函数调用
安全细分类型,说明:
当stream=false,flag值含义如下:
· 0或不返回:安全
· 1:低危不安全场景,可以继续对话
· 2:禁聊:不允许继续对话,但是可以展示内容
· 3:禁止上屏:不允许继续对话且不能上屏展示
· 4:撤屏
当flag 不为 0 时,该字段会告知第几轮对话有敏感信息;如果是当前问题,ban_round = -1
stream=true时,返回该内容,返回类型为see_choices
显示子属性
隐藏子属性
choice列表中的序号
响应信息,当stream=true时返回
显示子属性
隐藏子属性
仅在流式第一帧返回
流式响应内容
由模型生成的函数调用,包含函数名称,和调用参数
显示子属性
隐藏子属性
显示子属性
隐藏子属性
function call的唯一标识,由模型生成
固定值function
function call的具体内容
显示子属性
隐藏子属性
函数名称
函数参数
响应信息标识,search_status:触发搜索信号
输出内容标识,说明:
· stop:模型自然停止或命中提供的停止序列
· length:达到了最大的token数
· content_filter:输出内容被截断、兜底、替换为**等
· tool_calls:函数调用
安全细分类型,说明:当stream=true时,返回flag表示触发安全
当flag 不为 0 时,该字段会告知第几轮对话有敏感信息;如果是当前问题,ban_round = -1
token统计信息,说明:
(1)同步请求默认返回
(2)流式请求默认不返回,当开启stream_options.include_usage=true时,会在最后一个chunk返回实际内容,其他chunk返回null
显示子属性
隐藏子属性
问题tokens数(包含历史QA)
问题token详情,说明:当调用对话Chat API返回此参数
显示子属性
隐藏子属性
触发检索增强以后膨胀的token;用户可以通过usage.prompt_tokens_details.search_tokens>0判断是否出发了检索增强,并且计算出发检索增强的次数
触发上下文缓存后,命中缓存的token数量;说明:
· 用户可通过usage.prompt_tokens_details.cached_tokens>0判断是否触发了上下文缓存,并且计算出触发缓存的数量
· 该字段仅支持模型版本为ERNIE-4.0-Turbo-8K
回答tokens数,说明:当调用对话Chat API返回此参数
总tokens数
搜索结果列表
显示子属性
隐藏子属性
序号
搜索结果URL
搜索结果标题
{
"id":"as-9ki4hm6kkp",
"object":"chat.completion",
"created":1731318503,
"model":"ernie-3.5-8k",
"choices":[
{
"index":0,
"message":{
"role":"assistant",
"content":"您好!很高兴与您交流。您提到的“平台助手”可能指的是多种不同的工具或应用程序,它们通常旨在帮助用户更有效地使用某个平台或完成特定任务。\n\n例如,在某些电商平台上,平台助手可能是一个提供自动化客服、订单管理、数据分析等功能的工具,旨在帮助卖家提高运营效率。在社交媒体平台上,平台助手可能是一个用于管理多个账号、发布内容、监测趋势等的工具。\n\n如果您对某个特定平台的助手有更具体的兴趣或问题,请提供更多上下文或详细信息,以便我能给出更准确的回答。\n\n此外,如果您是在寻找一个能够帮助您管理多个平台账号、整合不同平台信息的通用型助手,那么市场上确实存在一些这样的工具,它们通常被称为“社交媒体管理工具”、“多平台管理工具”等。这些工具可以帮助您节省时间和精力,提高工作效率。\n\n总之,“平台助手”是一个比较宽泛的概念,其具体含义和功能取决于您所指的特定平台和应用场景。如有需要,请随时向我提问。"
},
"finish_reason":"stop",
"flag":0
}
],
"usage":{
"prompt_tokens":1,
"completion_tokens":196,
"total_tokens":197
}
}
{
"id": "as-0zapnuh7b4",
"object": "chat.completion",
"created": 1731502789,
"model": "ernie-4.0-8k",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "",
"tool_calls": [{
"id": "19c443b42d3f3000",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\"location\": \"上海\", \"time\": \"2024-11-13\"}"
}
}, {
"id": "19c443b42d3f3001",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\"location\": \"北京\", \"time\": \"2024-11-13\"}"
}
}]
},
"finish_reason": "tool_calls",
"flag": 0
}],
"usage": {
"prompt_tokens": 5,
"completion_tokens": 52,
"total_tokens": 57
}
}
{
"id":"as-t7xfiqidm7",
"object":"chat.completion",
"created":1731502895,
"model":"ernie-4.0-8k",
"choices":[{
"index":0,
"message":
{
"role":"assistant",
"content":"根据您提供的信息,当前上海的天气温度为25摄氏度,而北京的天气温度为20摄氏度。如果您需要更详细的天气描述或其他相关信息,请随时告诉我。"
},
"finish_reason":"normal","flag":0
}],
"usage":{
"prompt_tokens":44,
"completion_tokens":33,
"total_tokens":77
}
}
错误码
如果请求错误,服务器返回的JSON文本包含以下参数。
名称 | 描述 |
---|---|
code | 错误码 |
message | 错误描述信息,帮助理解和解决发生的错误 |
type | 错误类型 |
更多相关错误码,请查看模型错误码说明。