原生多模态

POST

https://qianfan.baidubce.com/v2/chat/completions

调试

本文介绍了多模态API相关接口使用说明。

支持模型列表

支持模型列表请查看千帆ModelBuilder-模型列表-原生多模态。

权限说明

调用本文API，需使用API Key鉴权方式。使用API Key鉴权调用API流程，具体调用流程，请查看认证鉴权。

请求参数

Headers 参数

除公共头域外，无其它特殊头域

Body 参数

model string

模型ID，可选值请参考千帆ModelBuilder-模型列表-原生多模态页，表格中model入参列

必选

messages array

聊天上下文信息。说明：
（1） messages成员不能为空，1个成员表示单轮对话，多个成员表示多轮对话；
（2）第一条message的role必须是user或system
（3）最后一条message的role必须是user
· 除去第一个system的role后，role需要依次为user -> assistant -> user ...
（4）message中的content总长度不能超过对应model的输入字符限制和输入tokens限制，请查看各模型上下文长度说明

必选

显示子属性隐藏子属性

items object {5}

显示子属性隐藏子属性

role string

当前支持以下：
· user: 表示用户
· assistant: 表示对话助手
· system：表示人设

必选

name string

可选

content anyOf {2}

多选一，只需要符合下列任意一组子节点

对话内容，说明：
（1）不能为空
（2）最后一个message对应的content不能为blank字符，如空格、"\n"、“\r”、“\f”等

必选

显示子属性隐藏子属性

content string

content array

显示子属性隐藏子属性

items string

tool_calls array

函数调用，function call场景下第一轮对话的返回，第二轮对话作为历史信息在message中传入

可选

显示子属性隐藏子属性

items object {3}

显示子属性隐藏子属性

id string

function call的唯一标识，由模型生成

必选

type string

固定值function

必选

function object {2}

function call的具体内容

可选

显示子属性隐藏子属性

name string

函数名称

可选

arguments string

函数参数

可选

tool_call_id string

说明：
（1）当role=tool时，该字段必填
（2）模型生成的function call id，对应tool_calls中的tool_calls[].id
（3）调用方应该传递真实的、由模型生成id，否则效果有损

可选

stream boolean

是否以流式接口的形式返回数据，说明：默认false

可选

stream_options object {1}

流式响应的选项，当字段stream为true时，该字段生效

可选

显示子属性隐藏子属性

include_usage boolean

流式响应是否输出usage，说明：
· true：是，设置为true时，在最后一个chunk会输出一个字段，这个chunk上的usage字段显示整个请求的token统计信息
· false：否，流式响应默认不输出usage

可选

temperature number

说明：
（1）较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定
（2）取值范围：
· ERNIE 4.5 或 ERNIE-4.5-Turbo-VL-32K：默认0.95，范围 (0, 1.0]
· Llama-4-Maverick 或 Llama-4-Scout：默认0.6，范围 [0, 2.0]

可选

top_p number

说明：
（1）影响输出文本的多样性，取值越大，生成文本的多样性越强
（2）取值说明：
· ERNIE 4.5 或 ERNIE-4.5-Turbo-VL-32K：默认0.7，取值范围 [0, 1.0]
· Llama-4-Maverick 或 Llama-4-Scout：默认0.9，取值范围 [0, 1.0]

可选

penalty_score number

通过对已生成的token增加惩罚，减少重复生成的现象。说明：
（1）值越大表示惩罚越大
（2）默认1.0，取值范围：[1.0, 2.0]

可选

max_tokens integer

指定模型最大输出token数，请查看千帆ModelBuilder-模型列表-原生多模态页，表格中最大输出(tokens)列说明。

可选

seed integer

说明：
（1）取值范围: （0,2147483647‌），会由模型随机生成，默认值为空
（2）如果指定，系统将尽最大努力进行确定性采样，以便使用相同seed和参数的重复请求返回相同的结果

可选

stop array

生成停止标识，当模型生成结果以stop中某个元素结尾时，停止文本生成。说明：
（1）每个元素长度不超过20字符
（2）最多4个元素

可选

显示子属性隐藏子属性

items string

停止标识，长度不超过20字符

user string

表示最终用户的唯一标识符

可选

web_search object {4}

搜索增强的选项，说明：
（1）默认不传关闭
（2）支持模型请参考开始使用-模型-联网搜索-支持模型列表。

可选

显示子属性隐藏子属性

enable boolean

是否开启实时搜索功能，说明：
（1）如果关闭实时搜索，角标和溯源信息都不会返回
（2）可选值：
· true：开启
· false：关闭，默认false

可选

enable_citation boolean

是否开启上角标返回，说明：
（1）enable为true时生效
（2）可选值：
· true：开启；如果开启，在触发了搜索增强的场景下，响应内容会附上角标，并带上角标对应的搜索溯源信息
· false：未开启，默认false
（3）如果检索内容包含非公开网页，角标不生效

可选

enable_trace boolean

是否返回搜索溯源信息，说明：
（1）enable 为 true时生效
（2）可选值：
· true：返回；如果为true，在触发了搜索增强的场景下，会返回搜索溯源信息search_results
· false：不返回，默认false
（3）如果检索内容为非公开网页，即使触发搜索也不返回溯源信息

可选

enable_status boolean

是否返回搜索信号，说明：
（1）enable 为 true时生效。
（2）可选值：
· true：返回；如果为true触发搜索，会通过delta_tag:search_status表示这一包是信号包。
· false：不返回，默认false

可选

response_format object {2}

指定响应内容的格式

可选

显示子属性隐藏子属性

type string

指定响应内容的格式，可选值：
· json_object：以json格式返回，可能出现不满足效果情况
· text：以文本格式返回，默认为text
· json_schema：以json_scheam规定的格式返回

可选

json_schema object {0}

json_schema格式，请参考JSON Schema描述；当type为json_schema时，该参数必填

可选

显示子属性隐藏子属性

暂无参数

metadata map<string,string>

说明：
（1）元素个数最大支持16个
（2）key和value必须都是string类型

可选

请求结构

POST /v2/chat/completions HTTP/1.1
Host: qianfan.baidubce.com
Authorization: authorization string
{
    "model": "ernie-4.5-8k-preview",
    "messages": [
        {
            "role": "system",
            "content": "平台助手"
        },
        {
            "role": "user",
            "content": "你好"
        }
    ]
}

示例代码

Shell

Python

curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
--data '{
    "model": "ernie-4.5-8k-preview",
    "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-4.5-8k-preview",
        "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()

返回响应

Headers 参数

除公共头域外，还包含以下特殊头域

X-Ratelimit-Limit-Tokens integer

一分钟内允许的最大tokens消耗，包含输入tokens和输出tokens

可选

X-Ratelimit-Limit-Requests integer

一分钟内允许的最大请求次数

可选

X-Ratelimit-Remaining-Tokens integer

达到TPM速率限制前，剩余可消耗的tokens数配额，如果配额用完，将会在0-60s后刷新

可选

X-Ratelimit-Remaining-Requests integer

达到RPM速率限制前，剩余可发送的请求数配额，如果配额用完，将会在0-60s后刷新

可选

返回参数

id string

本次请求的唯一标识，可用于排查问题

可选

object string

回包类型

可选

created integer

时间戳

可选

model string

模型

可选

choices anyOf {2}

多选一，只需要符合下列任意一组子节点

可选

显示子属性隐藏子属性

choices object {5}

stream=false时，返回该内容，返回类型为choices

显示子属性隐藏子属性

index integer

choice列表中的序号

可选

message object {6}

响应信息，当stream=false时返回

可选

显示子属性隐藏子属性

role string

当前支持以下：
· user: 表示用户
· assistant: 表示对话助手
· system：表示人设

可选

name string

message名

可选

content string

对话内容

可选

tool_calls array

函数调用，function call场景下第一轮对话的返回，第二轮对话作为历史信息在message中传入

可选

显示子属性隐藏子属性

items object {3}

显示子属性隐藏子属性

id string

function call的唯一标识，由模型生成

可选

type string

固定值function

可选

function object {2}

function call的具体内容

可选

显示子属性隐藏子属性

name string

函数名称

可选

arguments string

函数参数

可选

tool_call_id string

可选

reasoning_content string

思维链内容，说明：只有当模型为DeepSeek-R1有效

可选

finish_reason string

输出内容标识，说明：
· stop：模型自然停止或命中提供的停止序列
· length：达到了最大的token数
· content_filter：输出内容被截断、兜底、替换为**等
· tool_calls：函数调用

可选

flag integer

安全细分类型，说明：
当stream=false，flag值含义如下：
· 0或不返回：安全
· 1：低危不安全场景，可以继续对话
· 2：禁聊：不允许继续对话，但是可以展示内容
· 3：禁止上屏：不允许继续对话且不能上屏展示
· 4：撤屏

可选

ban_round integer

当flag 不为 0 时，该字段会告知第几轮对话有敏感信息；如果是当前问题，ban_round = -1

可选

choices object {6}

stream=true时，返回该内容，返回类型为sse_choices

显示子属性隐藏子属性

index integer

choice列表中的序号

可选

delta object {3}

响应信息，当stream=true时返回

可选

显示子属性隐藏子属性

role string

仅在流式第一帧返回

可选

content string

流式响应内容

可选

tool_calls array

由模型生成的函数调用，包含函数名称，和调用参数

可选

显示子属性隐藏子属性

items object {3}

显示子属性隐藏子属性

id string

function call的唯一标识，由模型生成

可选

type string

固定值function

可选

function object {2}

function call的具体内容

可选

显示子属性隐藏子属性

name string

函数名称

可选

arguments string

函数参数

可选

delta_tag string

响应信息标识，search_status：触发搜索信号

可选

finish_reason string

可选

flag integer

安全细分类型，说明：当stream=true时，返回flag表示触发安全

可选

ban_round integer

当flag 不为 0 时，该字段会告知第几轮对话有敏感信息；如果是当前问题，ban_round = -1

可选

usage object {4}

token统计信息，说明：
（1）同步请求默认返回
（2）流式请求默认不返回，当开启stream_options.include_usage=true时，会在最后一个chunk返回实际内容，其他chunk返回null

可选

显示子属性隐藏子属性

prompt_tokens integer

问题tokens数（包含历史QA）

可选

prompt_tokens_details integer

问题token详情，说明：当调用对话Chat API返回此参数

可选

completion_tokens integer

回答tokens数，说明：当调用对话Chat API返回此参数

可选

total_tokens integer

总tokens数

可选

search_results object {3}

搜索结果列表

可选

显示子属性隐藏子属性

index integer

序号

可选

url string

搜索结果URL

可选

title string

搜索结果标题

可选

响应示例

{
	"id": "as-mbu5gexpk8",
	"object": "chat.completion",
	"created": 1744179859,
	"model": "ernie-4.5-8k-preview",
	"choices": [{
		"index": 0,
		"message": {
			"role": "assistant",
			"content": "你好呀！有什么我可以帮你的吗？无论是问题解答、学习建议，还是日常闲聊，我都在这里呢～"
		},
		"finish_reason": "stop",
		"flag": 0
	}],
	"usage": {
		"prompt_tokens": 3,
		"completion_tokens": 26,
		"total_tokens": 29
	}
}

错误码

如果请求错误，服务器返回的JSON文本包含以下参数。

名称	描述
code	错误码
message	错误描述信息，帮助理解和解决发生的错误
type	错误类型

更多相关错误码，请查看模型错误码说明。

百度智能云

千帆AI应用开发者中心-API参考 qianfan-api

千帆AI应用开发者中心-API参考 qianfan-api

支持模型列表

权限说明

请求参数

示例代码

返回响应

错误码