视觉理解

POST

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

调试

调用本接口，可根据用户输入的图像和文字，回答图像有关问题。

支持模型列表

支持模型列表请查看千帆ModelBuilder-模型列表-视觉理解。

权限说明

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

请求参数

Headers 参数

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

Body 参数

model string

大模型ID，说明：
（1）预置服务，可选值请参考千帆ModelBuilder-模型列表-视觉理解页，表格中model入参列
（2）平台训练模型或预置模型，可以通过查看服务详情获取该字段值，详情请查看千帆控制台-在线推理：model值为服务详情中对应的API名称，如下图所示：

必选

messages array

聊天历史信息列表，说明：
（1）messages成员不能为空，1个成员表示单轮对话，多个成员表示多轮对话
（2）输入总长度不能超过对应model的输入字符限制和输入tokens限制，请查看各模型上下文长度说明

必选

显示子属性隐藏子属性

items object {3}

显示子属性隐藏子属性

role string

当前支持以下：
· system：人设
· user：用户
· assistant：对话助手
· tool：函数

必选

name string

message名

可选

content anyOf {2}

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

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

可选

显示子属性隐藏子属性

content string

content array

显示子属性隐藏子属性

items object {4}

显示子属性隐藏子属性

type string

当前支持以下类型：
· text：文本
· image_url：图像url
· video_url：视频

可选

text string

文本信息，当参数type为text时，必填

可选

image_url object {2}

可选

显示子属性隐藏子属性

url string

图像url，说明：
（1）支持以下：
· 传入图片链接，输入为图像 URL 时，URL 链接在UTF-8编码下最大不超过1024个字节，超出限制后图片无法下载
· 图片的Base64编码，传入 Base64 编码格式时，传入的格式需为：data:image/<图片格式>;base64,<Base64编码>
（2）单个图像的大小不超过10MB

可选

detail string

说明：
（1）只支持ERNIE 4.5模型
（2）可选值：
· low：模型会采用 “低分辨率” 模式，可以节约 tokens 消耗量、提升处理速度。
· high：模型会采用 “高分辨率” 模式，理解图像中更多的细节，同时将消耗更多的 tokens，降低处理的速度。
· auto：默认值

可选

video_url object {2}

输入的视频信息，说明：当参数type为video_url时，必填

可选

显示子属性隐藏子属性

url string

视频数据的url或者base64，说明：
（1）单个视频最大为64MB
（2）支持以下模型：
· Ernie 4.5 Turbo VL系列
· Qwen2.5-VL系列
· ERNIE-4.5-VL-28B-A3B

可选

fps float

每秒钟从视频中抽取指定数量的图像，说明：
（1）取值范围：[0.2, 5]，默认值是2
（2）只支持Ernie 4.5 Turbo VL系列

可选

stream boolean

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

可选

stream_options object {1}

流式响应的选项，说明：
（1）当字段stream为true时，该字段生效
（2）支持以下模型：
· ERNIE 4.5 Turbo VL系列
· ERNIE 4.5系列的ERNIE-4.5-8K-Preview、ERNIE-4.5-VL-28B-A3B
· Llama-4-Maverick系列
· Llama-4-Scout系列

可选

显示子属性隐藏子属性

include_usage boolean

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

可选

temperature number

说明：
（1）较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定
（2）该参数支持模型及取值范围等，请参考千帆ModelBuilder-模型默认参数说明

可选

top_p number

说明：
（1）影响输出文本的多样性，取值越大，生成文本的多样性越强
（2）该参数支持模型及取值范围等，请参考千帆ModelBuilder-模型默认参数说明

可选

penalty_score float

通过对已生成的token增加惩罚，减少重复生成的现象。说明：
（1）值越大表示惩罚越大
（2）取值范围：[1.0, 2.0]
（3）默认值说明：
· 模型为Qianfan Llama VL，该字段默认值为1.05
· 其它模型默认1.0
（4）不支持以下模型：ERNIE-4.5-VL-28B-A3B

可选

max_tokens integer

指定模型最大输出token数，请查看千帆ModelBuilder-模型列表-视觉理解页，表格中最大输出(tokens)列说明。

可选

enable_thinking boolean

是否开启思考模式，说明：
（1）可选值：
· true：开启
· false：未开启，默认值为false
（2）更多内容请参考深度思考

可选

seed integer

说明：
（1）取值范围: （0,2147483647‌），会由模型随机生成，默认值为空
（2）如果指定，系统将尽最大努力进行确定性采样，以便使用相同seed和参数的重复请求返回相同的结果
（3）支持以下模型：
· ERNIE 4.5 Turbo VL系列
· ERNIE 4.5系列的ERNIE-4.5-8K-Preview、ERNIE-4.5-VL-28B-A3B
· Llama-4-Maverick系列
· Llama-4-Scout系列

可选

stop array

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

可选

显示子属性隐藏子属性

items string

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

user string

表示最终用户的唯一标识符，支持以下模型：
· ERNIE 4.5 Turbo VL系列
· ERNIE 4.5系列的ERNIE-4.5-8K-Preview、ERNIE-4.5-VL-28B-A3B
· Llama-4-Maverick系列
· Llama-4-Scout系列

可选

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}

指定响应内容的格式，支持以下模型：
· ERNIE 4.5 Turbo VL系列
· ERNIE 4.5系列的ERNIE-4.5-8K-Preview、ERNIE-4.5-VL-28B-A3B
· Llama-4-Maverick系列
· Llama-4-Scout系列

可选

显示子属性隐藏子属性

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类型
（3）支持以下模型：
· ERNIE 4.5 Turbo VL系列
· ERNIE 4.5系列的ERNIE-4.5-8K-Preview、ERNIE-4.5-VL-28B-A3B
· Llama-4-Maverick系列
· Llama-4-Scout系列

可选

请求结构

POST /v2/chat/completions HTTP/1.1
Host: qianfan.baidubce.com
Authorization: authorization string
Content-Type: application/json

{
  "model": "deepseek-vl2",
  "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "分别使用1句话描述以下3张图片的内容"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://aidp-qa***"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://qianfan-test***"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://aidp-***"
                    }
                }
            ]
        }
    ] 
}

示例代码

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": "deepseek-vl2",
  "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "分别使用1句话描述以下3张图片的内容"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://aidp-qa***"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://qianfan-test***"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://aidp-***"
                    }
                }
            ]
        }
    ] 
}'

import requests
import json


def main():
    url = "https://qianfan.baidubce.com/v2/chat/completions"

    payload = json.dumps({
        "model": "deepseek-vl2",
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "分别使用1句话描述以下3张图片的内容"
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": "https://aidp-qa***"
                        }
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": "https://qianfan-test***"
                        }
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": "https://aidp-***"
                        }
                    }
                ]
            }
        ]
    })
    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-Requests integer

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

可选

X-Ratelimit-Limit-Input-Tokens integer

一分钟内允许的最大输入tokens消耗

可选

X-Ratelimit-Limit-Output-Tokens integer

一分钟内允许的最大输出tokens消耗

可选

X-Ratelimit-Remaining-Tokens integer

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

可选

X-Ratelimit-Remaining-Input-Tokens integer

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

可选

X-Ratelimit-Remaining-Output-Tokens integer

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

可选

返回参数

id string

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

可选

object string

回包类型 chat.completion：多轮对话返回

可选

created integer

时间戳

可选

model string

说明：预置服务，返回模型ID

可选

choices anyOf {2}

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

可选

显示子属性隐藏子属性

choices object {5}

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

显示子属性隐藏子属性

index integer

choice列表中的序号

可选

message object {4}

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

可选

显示子属性隐藏子属性

role string

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

可选

name string

message名

可选

content 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 {2}

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

可选

显示子属性隐藏子属性

role string

仅在流式第一帧返回

可选

content 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详情

可选

completion_tokens integer

回答tokens数

可选

total_tokens integer

总tokens数

可选

search_results object {3}

搜索结果列表

可选

显示子属性隐藏子属性

index integer

序号

可选

url string

搜索结果URL

可选

title string

搜索结果标题

可选

响应示例

{
    "id": "as-7u9f6065tq",
    "object": "chat.completion",
    "created": 1736413890,
    "model": "deepseek-vl2",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "第一张图片：一个蓝色圆形，中间有一个黑色的比特币符号。\n第二张图片：一个蓝色圆形，中间有一个黑色的比特币符号。\n第三张图片：一个蓝色圆形，中间有一个黑色的比特币符号。"
            },
            "finish_reason": "stop",
            "flag": 0
        }
    ],
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 41,
        "total_tokens": 51
    }
}

错误码

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

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

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

百度智能云

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

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

支持模型列表

权限说明

请求参数

示例代码

返回响应

错误码