多模态

更新时间：2025-04-21

注意：本文档已下线，内容不再更新，如需调用原生多模态相关API，请查看应用开发者中心-API参考-原生多模态调用说明。

本文介绍了多模态相关内容。

支持模型列表

支持模型列表请查看开始使用-模型列表-原生多模态。

在线调试

平台提供了 API在线调试平台-示例代码，用于帮助开发者调试接口，平台集成快速检索、查看开发文档、查看在线调用的请求内容和返回结果、复制和下载示例代码等功能，简单易用，更多内容请查看API在线调试介绍。

使用方法

输入

支持的输入模态：
输入多模态数据的方式

输入的图片、文件支持 Base64 编码与公网 URL 进行传入。以下示例代码均以传入公网 URL 为例，如果需要传入 Base64 编码，请参见图片Base 64 编码输入。

输出

当前支持以流式、非流式形式调用多模态模型。

注意：支持的输出模态当前仅支持文本输出；Llama 4仅支持文本输出，ERNIE 4.5 后续推出音频。

快速开始

您可以通过两种方式将图像传入模型：图像 URL 和 Base64 编码。与文本信息相同，图像信息也需要使用用户角色进行输入，即"role": "user"。

前提条件

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

文本输入

模型支持接收纯文本作为输入。

Bash

curl --location 'https://qianfan.bj.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data '{
    "model": "ernie-4.5-8k-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "介绍几个上海著名景点"
                }
            ]
        }
    ],
    "stream":false
}'

图片输入

模型支持接收纯图片作为输入。模型支持传入多张图片。对输入图片的要求如下：

单个图片文件的大小不超过10 MB;
图片数量受模型图文总 Token 上限（即最大输入）的限制，所有图片的总 Token 数必须小于模型的最大输入;

Bash

curl --location 'https://qianfan.bj.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data '{
    "model": "ernie-4.5-8k-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://testimage.bj.bcebos.com/image1.jpg"
                    }
                }
            ]
        }
    ],
    "stream": false
}'

图片+文本输入

模型支持接收图片+文本作为输入。模型支持传入多张图片。对输入图片的要求如下：

单个图片文件的大小不超过10 MB;
图片数量受模型图文总 Token 上限（即最大输入）的限制，所有图片的总 Token 数必须小于模型的最大输入;

Bash

curl --location 'https://qianfan.bj.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data '{
    "model": "ernie-4.5-8k-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What are in these images? Is there any difference between them?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://testimage.bj.bcebos.com/image1.jpg"
                    }
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://testimage.bj.bcebos.com/image2.png"
                    }
                }
            ]
        }
    ],
    "stream": false
}'

搜索增强

注意：只有ERNIE 4.5支持搜索增强。

Bash

curl --location 'https://qianfan.bj.baidubce.com/v2/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data '{
    "model": "ernie-4.5-8k-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "2024年奥运会乒乓球男单冠军是谁"
                }
            ]
        }
    ],
    "web_search": {
        "enable": true,
        "enable_trace": true
    },
    "stream": false,
    "max_tokens": 512
}'

图片Base 64 编码输入

如果您需要上传本地图像，可以将图像转成 Base 64 编码后输入。以下是一个兼容 OpenAI 接口规范的示例。

Python

from openai import OpenAI
import os
import base64

client = OpenAI(
    api_key = os.getenv("OPENAI_API_KEY"),  
    base_url="https://qianfan.baidubce.com/v2",  
)

# Function to encode the image
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")


# Path to your image
image_path = "image1.jpg"

# Getting the Base64 string
base64_image = encode_image(image_path)

response = client.chat.completions.create(
    model="ernie-4.5-8k-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image?",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{base64_image}"
                     },
                },
            ],
        }
    ],
    stream=True
)

for chunk in response:
  if chunk.choices[0].delta.content is not None:
    print(chunk.choices[0].delta.content, end="")

图像参数使用说明

（1）大模型每一次调用都是无状态的，您需要自行管理传入给模型的信息。如果需要模型多次理解同一张图像，请在每次请求时都传入该图。

（2）支持单图和多图，每一张图片大小不超过10MB，多张图片输入的总token不超过模型上下文长度。如ERNIE-4.5模型，不超过8K token的图片输入。

（3）图片格式：

a. 图片base64：JPG、JPEG、PNG和BMP类型，传入的格式需为：data:image/<图片格式>;base64,<Base64编码>

b. 图片公网url：支持JPG、JPEG、PNG、BMP和WEBP类型

（4）详细参数格式说明。

名称	类型	必填	描述
type	string	是	只有一个取值: image_url
image_url	object	是	输入的图片信息，说明：（1）支持多图，图片数量不限制，超过8K token会报token超限（2）单图最大不超过10MB（url下载后图片大小，或base64保存图片后大小）

image_url说明

名称	类型	必填	描述
url	string	是	图片的公网url或者base64，说明：（1）支持格式：base64：JPG、JPEG、PNG和BMP等类型url：支持JPG、JPEG、PNG、BMP和WEBP等类型（2）若为base64，传入的格式需为：data:image/<图片格式>;base64,<Base64编码>
detail	string	否	图像/分辨率质量，说明：low表示低分辨率，high表示高分辨率，默认值是high

token计算说明

说明：目前只提供ERNIE 4.5计算器。

千帆提供在线Token计算器用于计算模型token数量，包含文本token和图片token。

ERNIE 4.5-图像token 计算规则

与文本相同，模型会将图像输入转化为 tokens，并与文本信息一同作为模型输入的上下文信息进行计量计费。不同模型对图像 tokens 的转化方式不同，以下为千帆当前支持的视觉理解模型图像 tokens 计算规则。也可以使用千帆 token 计算器来估算对应输入的 token 数量。

输入：图片宽度(w)、图片高度(h)、detail（分辨率质量，"high" or "low")

说明：

detail 为 high 时，max_tile = 36, min_tile = 16
detail 为 low 时，max_tile = 9, min_tile = 4

获取tile数量

 `rowl, col = crop(w, h, detail)`

计算token数量

` (row * col + 1) * TOKEN_EACH_TILE + row * col + NUM_SPECIAL_TOKEN_EACH_IMAGE`

参数	值说明	说明
TOKEN_EACH_TILE	64	一个切片占用的token数量。
NUM_SPECIAL_TOKEN_EACH_IMAGE	9	每个图片其他特殊token数量
CROP_WIDTH	448	每个切图的宽度
CROP_HEIGHT	448	每个切图的高度
MAX_TILE	{"high": 36, "low": 9}	每张图最多允许的切图数量
MIN_TILE	{"high": 16, "low": 4}	每张图最少允许的切图数量

计算器说明：

ERNIE 4.5 支持的图片输入是448 x 448，adaptive_partition函数在保持每一个切片长宽尽可能地接近模型支持长宽(448 x 448)的情况下，将图片尽可能切为row x col片，并保证最小切片数不少于min_tile，不超过max_tile。
ERNIE-4.5 中每个切片占用65个token，包含视觉token和一些其他特殊token.

请求头域

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

请求参数

名称	类型	必填	描述
model	string	是	模型ID，可选值请参考开始使用-模型列表-原生多模态页，表格中model入参列
messages	List<message>	是	聊天上下文信息。说明： · messages成员不能为空，1个成员表示单轮对话，多个成员表示多轮对话； · 第一条message的role必须是user或system · 最后一条message的role必须是user · 除去第一个system的role后，role需要依次为user -> assistant -> user ... · message中的content总长度不能超过对应model的输入字符限制和输入tokens限制，请查看各模型上下文长度说明
stream	bool	否	是否以流式接口的形式返回数据，说明：默认false
stream_options	stream_options	否	流式响应的选项，当字段stream为true时，该字段生效
temperature	float	否	说明：（1）较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定（2）取值说明： · ERNIE 4.5：默认0.95，范围 (0, 1.0] · Llama-4-Maverick 或 Llama-4-Scout：默认0.6，范围 [0, 2.0]
top_p	float	否	说明：（1）影响输出文本的多样性，取值越大，生成文本的多样性越强（2）取值说明： · ERNIE 4.5：默认0.7，取值范围 [0, 1.0] · Llama-4-Maverick 或 Llama-4-Scout：默认0.9，取值范围 [0, 1.0]
penalty_score	float	否	通过对已生成的token增加惩罚，减少重复生成的现象。说明：（1）值越大表示惩罚越大（2）默认1.0，取值范围：[1.0, 2.0]
max_completion_tokens	int	否	指定模型最大输出token数，请查看开始使用-模型列表-原生多模态页，表格中最大输出(tokens)列说明
seed	int	否	说明：（1）取值范围: （0,2147483647‌），会由模型随机生成，默认值为空（2）如果指定，系统将尽最大努力进行确定性采样，以便使用相同seed和参数的重复请求返回相同的结果
stop	List<string>	否	生成停止标识，当模型生成结果以stop中某个元素结尾时，停止文本生成。说明：（1）每个元素长度不超过20字符（2）最多4个元素
user	string	否	表示最终用户的唯一标识符
web_search	web_search	否	搜索增强的选项，说明：（1）默认不传关闭（2）支持ERNIE 4.5
response_format	response_format	否	指定响应内容的格式
metadata	map<string,string>	否	说明：（1）元素个数最大支持16个（2）key和value必须都是string类型

响应头域

部分如下。

名称	描述
X-Ratelimit-Limit-Requests	一分钟内允许的最大请求次数
X-Ratelimit-Limit-Tokens	一分钟内允许的最大tokens消耗，包含输入tokens和输出tokens
X-Ratelimit-Remaining-Requests	达到RPM速率限制前，剩余可发送的请求数配额，如果配额用完，将会在0-60s后刷新
X-Ratelimit-Remaining-Tokens	达到TPM速率限制前，剩余可消耗的tokens数配额，如果配额用完，将会在0-60s后刷新

响应参数

名称	类型	描述
id	string	本次请求的唯一标识，可用于排查问题
object	string	回包类型
created	int	时间戳
model	string	模型
choices	choices	stream=false时，返回内容
choices	sse_choices	stream=true时，返回内容
usage	usage	token统计信息，说明：（1）同步请求默认返回（2）流式请求默认不返回，当开启stream_options.include_usage=true时，会在最后一个chunk返回实际内容，其他chunk返回null
search_results	search_results	搜索结果列表

错误码

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

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

更多相关错误码，请查看推理服务V2版本错误码说明。