图像理解

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）messages的role说明：
· 第一条message的role必须user/system
· 除去第一个system之外，role依次为user -> assistant -> user ...
（3）最后一个message为当前请求的信息，前面的message为历史对话信息
（4）输入总长度不能超过对应model的输入字符限制和输入tokens限制，请查看各模型上下文长度说明

必选

显示子属性隐藏子属性

items object {3}

显示子属性隐藏子属性

role string

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

必选

name string

message名

可选

content array

图像相关信息

必选

显示子属性隐藏子属性

items object {3}

显示子属性隐藏子属性

type string

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

必选

text string

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

可选

image_url object {2}

图像url信息，当参数type为image_url时，必填

可选

显示子属性隐藏子属性

url string

图像url，说明：
（1）支持以下：
· 传入图片链接
· 图片的Base64编码，传入 Base64 编码格式时，传入的格式需为：data:image/<图片格式>;base64,<Base64编码>
（2）单个图像的大小不超过10MB

必选

detail string

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

可选

stream boolean

是否以流式接口的形式返回数据，说明：
· true：是
· false：否，默认false，beam search模型只能为false

可选

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

可选

max_tokens integer

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

可选

请求结构

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 参数

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

返回参数

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 {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

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

可选

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 {5}

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

函数参数

可选

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-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

支持模型列表

权限说明

请求参数

示例代码

返回响应

错误码