Skip to main content
阿里云百炼 home page阿里云百炼
视觉理解

图像与视频理解

视觉理解模型可以根据您传入的图片或视频进行回答，支持单图或多图的输入，适用于图像描述、视觉问答、物体定位等多种任务。

在线体验：访问阿里云百炼控制台，在页面右上角选择目标地域，进入视觉模型页面进行体验。

快速开始

您需要先获取与配置 API Key。若通过OpenAI SDK进行调用，需要安装SDK。 以下示例演示了如何调用模型描述图像内容。关于本地文件和图像限制的说明，请参见如何传入本地文件、图像限制章节。
  • OpenAI兼容
  • DashScope
  • Python
  • Node.js
  • Java
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max", # 此处以qwen3.8-max为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/models
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
                    },
                },
                {"type": "text", "text": "图中描绘的是什么景象?"},
            ],
        },
    ],
)
print(completion.choices[0].message.content)

返回结果 

这是一张在海滩上拍摄的照片。照片中，一个人和一只狗坐在沙滩上，背景是大海和天空。人和狗似乎在互动，狗的前爪搭在人的手上。阳光从画面的右侧照射过来，给整个场景增添了一种温暖的氛围。

模型效果

图像问答

描述图像中的内容或者对其进行分类打标，如识别人物、地点、动植物等。

p1021359

如果太阳很刺眼，我应该用这张图中的什么物品？

当太阳很刺眼时，你应该使用图中的粉色太阳镜。太阳镜可以有效阻挡强光、减少紫外线对眼睛的伤害，帮助你在阳光强烈时保护视力并提升视觉舒适度。

创意写作

根据图片或视频内容生成生动的文字描述，适用于故事创作、文案撰写、短视频脚本等创意场景。

vl-问答

请根据图片内容，帮我写一段有意思的朋友圈文案。

好的，这张图片充满了浓郁的中秋节日氛围，古典与现代元素结合得非常巧妙。根据图片中的主要元素，我为你准备了几个不同风格的朋友圈文案，你可以根据自己的喜好选择。

诗意唯美风

今夜月明人尽望，不知秋思落谁家。嫦娥奔月，玉兔捣药，古人的浪漫在今夜被点亮。愿这轮明月，能照亮你回家的路，也能寄去我最深的思念。中秋节快乐！

温馨祝福风

月圆人团圆，中秋夜最温柔。看烟花绽放，赏圆月当空，吃一口月饼，道一声安康。愿你我心中所念，皆能如愿以偿。祝大家中秋快乐，阖家幸福！

文字识别与信息抽取

识别图像中的文字、公式或抽取票据、证件、表单中的信息，支持格式化输出文本。

-q2cdz6jy89b6m3kp

提取图中的：['发票代码','发票号码','到站','燃油费','票价','乘车日期','开车时间','车次','座号']，请你以JSON格式输出。

{

"发票代码": "221021325353",

"发票号码": "10283819",

"到站": "开发区",

"燃油费": "2.0",

"票价": "8.00<全>",

"乘车日期": "2013-06-29",

"开车时间": "流水",

"车次": "040",

"座号": "371"

}

多学科题目解答

解答图像中的数学、物理、化学等问题，适用于中小学、大学以及成人教育阶段。

-5jwcstcvmdpqghaj

请你分步骤解答图中的数学题。

-答案

视觉编程

可通过图像或视频生成代码，可用于将设计图、网站截图等生成HTML、CSS、JS 代码。

code

根据我的草图设计使用HTML、CSS创建网页，主色调为黑色。

code-预览

网页预览效果

物体定位

支持二维和三维定位，可用于判断物体方位、视角变化、遮挡关系。三维定位为Qwen3-VL模型新增能力。
Qwen2.5-VL模型 480480～* 2560*2560 分辨率范围内，物体定位效果较为鲁棒，在此范围之外检测精度可能会下降（偶发检测框漂移现象）。
如需将定位结果绘制到原图可参见 常见问题 。
二维定位
-530xdcos1lqkcfuy
  • 返回 Box（边界框）坐标 ：检测图中所有食物并以JSON格式输出其bbox的坐标。
  • 返回 Point（中心点）坐标：以点的形式定位图中所有食物并以XML格式输出其point坐标。
可视化展示二维定位效果
-mu9podu1eyvph1zd
3d
检测图像中的汽车并预测3D位置。输出JSON：[{"bbox_3d": [x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw], "label": "category"}]。
3d-结果

文档解析

将图像类的文档（如扫描件/图片PDF）解析为 QwenVL HTML 或 QwenVL Markdown 格式，该格式不仅能精准识别文本，还能获取图像、表格等元素的位置信息。Qwen3-VL模型新增解析为 Markdown 格式的能力。
推荐提示词如下： qwenvl html （解析为HTML格式）或 qwenvl markdown （解析为Markdown格式）

image

qwenvl markdown。

-结果

可视化展示效果

视频理解

分析视频内容，如对具体事件进行定位并获取时间戳、生成关键时间段的摘要等。
请你描述下视频中的人物的一系列动作，以JSON格式输出开始时间（start_time）、结束时间（end_time）、事件（event），请使用HH:mm:ss表示时间戳。{"events": [{"start_time": "00:00:00","end_time": "00:00:05","event": "人物手持一个纸箱走向桌子，并将纸箱放在桌上。"},{"start_time": "00:00:05","end_time": "00:00:15","event": "人物拿起扫描枪，对准纸箱上的标签进行扫描。"},{"start_time": "00:00:15","end_time": "00:00:21","event": "人物将扫描枪放回原位，然后拿起笔在笔记本上记录信息。"}]}

核心能力

开启/关闭思考模式

  • qwen3.8、qwen3.7、qwen3.6、qwen3.5、qwen3-vl-plus、qwen3-vl-flash系列模型属于混合思考模型，模型可以在思考后回复，也可直接回复；通过enable_thinking参数控制是否开启思考模式：
    • true：开启思考模式。qwen3.8、qwen3.7、qwen3.6、qwen3.5系列模型默认为true。
    • false：关闭思考模式。qwen3-vl-plus、qwen3-vl-flash系列模型默认为false。
  • qwen3-vl-235b-a22b-thinking等带thinking后缀的属于仅思考模型，模型总会在回复前进行思考，且无法关闭。
  • 模型配置：在非 Agent 工具调用的通用对话场景下，为保持最佳效果，建议不设置System Message，可将模型角色设定、输出格式要求等指令通过User Message 传入。
  • 优先使用流式输出： 开启思考模式时，支持流式和非流式两种输出方式。为避免因响应内容过长导致超时，建议优先使用流式输出方式。
  • 限制思考长度：深度思考模型有时会输出冗长的推理过程，可使用 thinking_budget 参数限制思考过程的长度。若模型思考过程生成的 Token 数超过thinking_budget，推理内容会进行截断并立刻开始生成最终回复内容。thinking_budget 默认值为模型的最大思维链长度，请参见模型列表。
  • OpenAI 兼容
  • DashScope
enable_thinking非 OpenAI 标准参数，若使用 OpenAI Python SDK请通过 extra_body传入。
from openai import OpenAI
import os

# 初始化OpenAI客户端
client = OpenAI(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

reasoning_content = ""  # 定义完整思考过程
answer_content = ""     # 定义完整回复
is_answering = False   # 判断是否结束思考过程并开始回复
enable_thinking = True
# 创建聊天完成请求
completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
                {"type": "text", "text": "这道题怎么解答？"},
            ],
        },
    ],
    stream=True,
    # enable_thinking 参数开启思考过程，thinking_budget 参数设置最大推理过程 Token 数
    # 通过enable_thinking参数切换思考模式
    extra_body={
        'enable_thinking': enable_thinking,
        "thinking_budget": 81920},

    # 解除以下注释会在最后一个chunk返回Token使用量
    # stream_options={
    #     "include_usage": True
    # }
)

if enable_thinking:
    print("\n" + "=" * 20 + "思考过程" + "=" * 20 + "\n")

for chunk in completion:
    # 如果chunk.choices为空，则打印usage
    if not chunk.choices:
        print("\nUsage:")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # 打印思考过程
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content is not None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            # 开始回复
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "完整回复" + "=" * 20 + "\n")
                is_answering = True
            # 打印回复过程
            print(delta.content, end='', flush=True)
            answer_content += delta.content

# print("=" * 20 + "完整思考过程" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "完整回复" + "=" * 20 + "\n")
# print(answer_content)

多图像输入

视觉理解模型支持在单次请求中传入多张图片，可用于商品对比、多页文档处理等任务。实现时只需在user message 的content数组中包含多个图片对象即可。
图片数量受模型图文总 Token 上限的限制，所有图片和文本的总 Token 数必须小于模型的最大输入。
  • OpenAI兼容
  • DashScope
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen3.8-max", # 此处以qwen3.8-max为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/models
    messages=[
       {"role": "user","content": [
           {"type": "image_url","image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},},
           {"type": "image_url","image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},},
           {"type": "text", "text": "这些图描绘了什么内容？"},
            ],
        }
    ],
)

print(completion.choices[0].message.content)

返回结果 

图1中是一位女士和一只拉布拉多犬在海滩上互动的场景。女士穿着格子衬衫，坐在沙滩上，与狗进行握手的动作，背景是海浪和天空，整个画面充满了温馨和愉快的氛围。

图2中是一只老虎在森林中行走的场景。老虎的毛色是橙色和黑色条纹相间，它正向前迈步，周围是茂密的树木和植被，地面上覆盖着落叶，整个画面给人一种野生自然的感觉。

视频理解

视觉理解模型支持对视频内容进行理解，文件形式包括图像列表（视频帧）或视频文件。以下是理解在线视频或图像列表（通过URL指定）的示例代码。关于视频限制或可传入的图像列表数量限制，请参见视频限制章节。
建议使用性能较优的最新版或近期快照版模型理解视频文件。
  • 视频文件
  • 图像列表
视觉理解模型通过从视频中提取帧序列进行内容分析。您可以通过以下两个参数控制抽帧策略：
  • fps：控制抽帧频率，每隔 f p s 1 ​秒抽取一帧。取值范围为 [0.1, 10]，默认值为 2.0。
    • 高速运动场景：建议设置较高的 fps 值，以捕捉更多细节
    • 静态或长视频：建议设置较低的 fps 值，以提高处理效率
  • max_frames：限制视频抽取帧的上限。当按 fps 计算的总帧数超过此限制时，系统将自动在 max_frames 内均匀抽帧。此参数仅在使用 DashScope SDK时可用。
  • OpenAI兼容
  • DashScope
使用OpenAI SDK或HTTP方式向视觉理解模型直接输入视频文件时，需要将用户消息中的 "type" 参数设为 "video_url" 。
Python
import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx",
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "user",
            "content": [
                # 直接传入视频文件时，请将type的值设置为video_url
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                    },
                    "fps": 2
                },
                {
                    "type": "text",
                    "text": "这段视频的内容是什么?"
                }
            ]
        }
    ]
)

print(completion.choices[0].message.content)

传入本地文件（Base64 编码或文件路径）

视觉理解模型提供两种本地文件上传方式：Base64 编码上传和文件路径直接上传。可根据文件大小、SDK类型选择上传方式，具体建议请参见如何选择文件上传方式；两种方式均需满足图像限制中对文件的要求。
  • Base64 编码上传
  • 文件路径上传
将文件转换为 Base64 编码字符串，再传入模型。适用于 OpenAI 和 DashScope SDK及HTTP方式
  1. 文件编码：将本地图像转换为 Base64 编码； 
    #  编码函数： 将本地文件转换为 Base64 编码的字符串
import base64
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# 将xxxx/eagle.png替换为你本地图像的绝对路径
base64_image = encode_image("xxx/eagle.png")
  2. 构建 Data URL：格式如下：data:[MIME_type];base64,{base64_image}；
    1. MIME_type需替换为实际的媒体类型，确保与支持的图像格式表格中MIME Type 的值匹配（如image/jpeg、image/png）；
    2. base64_image为上一步生成的 Base64 字符串；
  3. 调用模型：通过image或image_url参数传递Data URL并调用模型。
  • 图像
  • 视频文件
  • 图像列表
  • 文件路径传入
  • Base64 编码传入
Python
import os
from dashscope import MultiModalConversation
import dashscope

# 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# 将xxx/eagle.png替换为你本地图像的绝对路径
local_path = "xxx/eagle.png"
image_path = f"file://{local_path}"
messages = [
                {'role':'user',
                'content': [{'image': image_path},
                            {'text': '图中描绘的是什么景象?'}]}]
response = MultiModalConversation.call(
    # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen3.7-plus',  # 此处以qwen3.7-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/models
    messages=messages)
print(response.output.choices[0].message.content[0]["text"])

处理高分辨率图像

视觉理解模型API对单张图像编码后的视觉 Token 数量设有限制，默认配置下，高分辨率图像会被压缩，可能丢失细节，影响理解准确性。启用 vl_high_resolution_images 或调整 max_pixels 可增加视觉 Token 数量，从而保留更多图像细节，提升理解效果。
当输入图像像素大于模型的像素上限时，会将图像进行缩小至像素上限内。

模型

每Token 对应像素

vl_high_resolution_images

max_pixels

Token 上限

像素上限

Qwen3.8、Qwen3.7、Qwen3.6、Qwen3.5、Qwen3-VL系列模型

32*32

true

max_pixels 无效

16384 Token

16777216（即16384*32*32）

false（默认）

可自定义，默认为 2621440，最大值是16777216

由 max_pixels 决定，即max_pixels/32/32

max_pixels

qwen-vl-max、qwen-vl-plus模型

32*32

true

max_pixels 无效

16384 Token

16777216（即16384*32*32）

false（默认）

可自定义，默认为1310720，最大值是16777216

由 max_pixels 决定，即max_pixels/32/32

max_pixels

QVQ系列模型

28*28

true

max_pixels 无效

16384 Token

12845056（即16384*28*28）

false（默认）

可自定义，默认为1003520，最大值是12845056

由 max_pixels 决定，即max_pixels/28/28

max_pixels

  • 当vl_high_resolution_images=true时，API 使用固定分辨率策略，忽略max_pixels设置。适合用于识别图像中的精细文本、微小物体或丰富细节。
  • 当vl_high_resolution_images=false时，最终的像素上限取决于 max_pixels 参数值。
    • 对成本敏感（希望减少视觉 Token 消耗）：使用max_pixels的默认值或设置为更小的值。max_pixels主要影响视觉 Token 数量与调用成本，实测对端到端响应时间没有显著影响；如需降低时延，请参见下方响应速度与模型选型。
    • 需要关注一定的细节，可接受较低的处理速度：适当提高max_pixels的值

响应速度与模型选型

在延迟敏感的场景中，响应时间主要由所选模型决定，而不是由max_pixels决定。qwen-vl-max与qwen-vl-plus在相同输入条件下的响应时间对比如下：

模型

平均响应时间

特点

qwen-vl-max

约 12s

识别精度更高，适合细节密集、容错要求低的图像

qwen-vl-plus

约 8s

速度与精度平衡，比qwen-vl-max快约 39%

上表为单张 2480x3508 像素图像在默认参数（vl_high_resolution_images=false）下的实测参考值：qwen-vl-max两次调用分别为 12.75s、11.84s，平均 12.29s；qwen-vl-plus两次调用分别为 8.29s、6.75s，平均 7.52s。实际耗时随图像尺寸、输出长度和网络状况变化，仅供量级参考，不构成性能承诺。
  • 启用流式输出（stream=True）可显著降低首字延迟：同一请求下首个 Token 约 0.95s 返回，完整响应的总耗时不变。适合需要尽快向用户反馈的交互式场景。
  • 工作流等对时延敏感的图片识别场景：建议使用qwen-vl-plus并开启stream=True，可在约 1 秒内拿到首字响应；仅当qwen-vl-plus的识别准确度不满足要求时，再切换到qwen-vl-max。调小max_pixels不是提速手段——实测中max_pixels=16384为 18.59s、max_pixels=65536为 13.22s，与默认值下的 12.29s 基本持平甚至更慢。
  • OpenAI 兼容
  • DashScope
vl_high_resolution_images非 OpenAI 标准参数，在不同语言的SDK中传递方式存在差异：
  • Python SDK:必须通过 extra_body 字典传递
  • Node.js SDK:可作为顶层参数直接传递
Python
import os
from openai import OpenAI

client = OpenAI(
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "user","content": [
            {"type": "image_url","image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250212/earbrt/vcg_VCG211286867973_RF.jpg"},
            # max_pixels表示输入图像的最大像素阈值，在vl_high_resolution_images=True，无效，vl_high_resolution_images=False，支持自定义，不同模型最大值不同
            # "max_pixels": 16384 * 32 * 32
            },
           {"type": "text", "text": "这张图表现的是哪个节日的氛围？"},
            ],
        }
    ],
    extra_body={"vl_high_resolution_images":True}

)
print(f"模型输出结果: {completion.choices[0].message.content}")
print(f"输入总Tokens: {completion.usage.prompt_tokens}")

更多用法

使用限制

输入文件限制

  • 图像限制
  • 视频限制
  • 图像分辨率：
    • 最小尺寸：图像的宽度和高度均须大于10像素。
    • 宽高比：原图及缩放后的图像，长边与短边的比值不得超过 200:1。
      图像缩放逻辑请参见 计算图像的Token 中 smart_resize 函数。
    • 像素上限：
      • 推荐将图像分辨率控制在8K(7680x4320)以内。超过此分辨率的图像可能因文件过大、网络传输耗时过长而导致API调用超时。
      • 自动缩放机制：模型可通过max_pixels和min_pixels调整图像大小；因此，提供超高分辨率的图像并不会提升识别精度，反而会增加调用失败的风险，建议在客户端提前将图像缩放至合理大小。
  • 支持的图像格式
    • 分辨率在4K (3840x2160)以下，支持的图像格式如下：

      图像格式

      常见扩展名

      MIME Type

      BMP

      .bmp

      image/bmp

      JPEG

      .jpe, .jpeg, .jpg

      image/jpeg

      PNG

      .png

      image/png

      TIFF

      .tif, .tiff

      image/tiff

      WEBP

      .webp

      image/webp

      HEIC

      .heic

      image/heic

    • 分辨率处于4K(3840x2160)到8K(7680x4320)范围，仅支持 JPEG、JPG 、PNG 格式
  • 图像大小：
    • 以公网URL传入时：Qwen3.8系列、Qwen3.7系列、Qwen3.6系列、Qwen3.5系列、Qwen3-VL系列单个图像不超过 20MB，其他模型单个图像不超过10MB
    • 以本地路径传入时：单个图像不超过10MB
    • 以 Base64 编码传入时（OpenAI 兼容接口或DashScope）：Qwen3.8系列、Qwen3.7系列、Qwen3.6系列、Qwen3.5、Qwen3-VL系列编码前的原始图像文件不超过 20MB，其他模型不超过10MB；且编码后的 Data URI 字符串不超过 20MB。
    • 以 Base64 编码传入时（Anthropic 兼容接口）：受请求体整体不超过6MB 的限制，多张图像时需共享此额度。
    上述限制取决于所选模型，不支持通过购买高级套餐或升级模型版本提升。
    如需压缩文件体积请参见 如何将图像或视频压缩到满足要求的大小 。
  • 图片数量限制：多图输入时根据传入方式不同，支持的图片数量上限有所区别：
    • 以公网URL或本地路径传入时：
      • Qwen3.8-Max、Qwen3.8-Flash、Qwen3.7-Plus：最多 2048 张
      • Qwen3.7-Flash、Qwen3.6-Plus、Qwen3.6-Flash、Qwen3.5-Plus、Qwen3.5-Flash、Qwen3-VL、Qwen-VL、QVQ系列：最多 256 张
    • 以 Base64 编码传入时：最多 250 张
    Qwen-Omni系列模型请参考全模态。
同时受模型图文总 Token 上限（即最大输入）的限制，所有图片的总 Token 数必须小于模型的最大输入。

文件传入方式

  • 公网URL：提供一个公网可访问的文件地址，支持HTTP或HTTPS协议。为获得最佳稳定性和性能，可将文件上传至OSS或上传文件获取临时URL，获取公网 URL。百炼服务无法访问 OSS 内网地址（endpoint 中带 -internal，如 https://<bucket>.oss-cn-hangzhou-internal.aliyuncs.com/image.jpg），传入内网地址会导致文件下载失败，返回 InvalidParameter，message 为 Failed to download multimodal content。请改用 OSS 公网域名（如 https://<bucket>.oss-cn-hangzhou.aliyuncs.com/image.jpg）或 OSS 临时签名 URL 传入文件。
    为确保模型能成功下载文件，提供的公网URL的响应头中必须包含 Content-Length（文件大小）和 Content-Type（媒体类型，如 image/jpeg）。任一字段缺失或者错误将会导致文件下载失败。
  • Base64编码传入：将文件转换为 Base64 编码字符串再传入。
  • 本地文件路径传入（仅限 DashScope SDK）：传入本地文件的路径。
关于文件传入方式的建议，请参见 如何选择文件上传方式？

应用于生产环境

  • 图像/视频预处理：视觉理解模型对输入的文件有大小限制，如需压缩文件请参见图像或视频压缩方法。
  • 处理文本文件：视觉理解模型仅支持输入文本、图像和视频，不支持直接处理 TXT、Word（.doc/.docx）、PDF 等文本文件。如需处理文本文件，可使用以下替代方案：
    • 将文本文件转换为图片格式，建议使用图像处理库（如Python的pdf2image）将文件按页转换为多张高质量的图片，再使用多图像输入方式传入模型。
    • 使用Qwen-Long模型，该模型支持上传文档并通过文件ID传入信息并对话。
  • 异步与批量处理：对于大规模、非实时的图像或视频处理任务，推荐使用OpenAI兼容-Batch（文件输入）的方式（仅支持部分模型）。此方式以异步方式处理任务，并提供50%的成本折扣。
  • 容错与稳定性
    • 超时处理：非流式调用的最大超时时间不少于300秒，实际时长因部署区域与选用模型存在差异。为了提升用户体验，超时后响应体中会将已生成的内容返回。如果响应头包含x-dashscope-partialresponse：true，表示本次响应触发了超时。您可以使用前缀续写功能（支持部分模型），将已生成的内容添加到 messages 数组并再次发出请求，使大模型继续生成内容。详情请参见：基于不完整输出进行续写。
    • 客户端超时配置：上文的超时是服务端限制，SDK 客户端本身也有默认超时时间。处理大尺寸图片（如 4000x4000 像素）时，请求耗时可能超过客户端默认超时时间，从而抛出 APITimeoutError。客户端超时与服务端超时是两个独立的限制，需要分别处理。使用 OpenAI Python SDK 时，可通过 with_options 延长客户端超时时间：
client = client.with_options(timeout=1800.0)
response = client.chat.completions.create(
    model="qwen-vl-plus",
    messages=[...]
)
  • 使用流式输出：将 stream 参数设置为 True 后，内容会逐步返回，避免长时间等待单个完整响应而触发客户端超时：
stream = client.chat.completions.create(
    model="qwen-vl-plus",
    messages=[...],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content)
  • 重试机制：设计合理的API调用重试逻辑（如指数退避），以应对网络波动或服务瞬时不可用的情况。

计费与限流

  • 计费 ：总费用根据输入和输出的总 Token 数计算；输入和输出价格可参见百炼控制台。
    • Token 构成：输入 Token 由文本 Token 和图像或视频转换后的 Token 组成；输出 Token 为模型生成的文本。在思考模式下，模型的思考过程也会计入输出 Token。若思考模式下未输出思考过程，按照非思考模式价格计费。
    • 计算图像与视频的Token：可通过以下代码计算图像或视频的 Token 消耗。估算结果仅供参考，实际用量以API响应为准。
      • 图像
      • 视频
      计算公式：图像 Token = h_bar * w_bar / token_pixels + 2
      • h_bar、w_bar：缩放后的图像长宽，模型在处理图像前会进行预处理，会将图像缩小至特定像素上限内，像素上限与max_pixels和vl_high_resolution_images参数的取值有关，相关章节：处理高分辨率图像。
      • token_pixels：每视觉Token对应的像素值，不同模型情况不同：
        • qwen3.8系列、qwen3.7系列、qwen3.6系列、qwen3.5系列、Qwen3-VL、qwen-vl-max、qwen-vl-plus：每个Token对应 32x32像素
        • QVQ及其他Qwen2.5-VL模型：每个Token对应28x28像素
      以下代码演示了模型内部对图像的大致缩放逻辑，可用于估算一张图像的Token，实际计费请以API响应为准。
      import math
from PIL import Image  # pip install Pillow

def smart_resize(image_path, max_pixels, vl_high_resolution_images):
    """根据模型参数，计算图像缩放后的尺寸，用于估算图像 Token。"""
    image = Image.open(image_path)
    height, width = image.height, image.width

    # Qwen3.6、Qwen3.5、Qwen3-VL 等模型的缩放因子为 32；其他模型为 28
    factor = 32
    h_bar = round(height / factor) * factor
    w_bar = round(width / factor) * factor

    # Token 下限：4 个 Token
    min_pixels = 4 * factor * factor

    # vl_high_resolution_images=True 时，Token 上限固定为 16384，忽略 max_pixels
    if vl_high_resolution_images:
        max_pixels = 16384 * factor * factor

    # 将总像素数约束在 [min_pixels, max_pixels] 范围内
    if h_bar * w_bar > max_pixels:
        beta = math.sqrt((height * width) / max_pixels)
        h_bar = math.floor(height / beta / factor) * factor
        w_bar = math.floor(width / beta / factor) * factor
    elif h_bar * w_bar < min_pixels:
        beta = math.sqrt(min_pixels / (height * width))
        h_bar = math.ceil(height * beta / factor) * factor
        w_bar = math.ceil(width * beta / factor) * factor

    return h_bar, w_bar

if __name__ == "__main__":
    # 注意：max_pixels 和 vl_high_resolution_images 的值需要与调用模型时传入的参数保持一致
    h_bar, w_bar = smart_resize("xxx/test.jpg", max_pixels=2560 * 32 * 32, vl_high_resolution_images=False)
    print(f"缩放后的图像尺寸：高度 {h_bar}，宽度 {w_bar}")

    # 每张图像额外包含 <vision_bos> 和 <vision_eos> 各 1 个 Token
    token = int(h_bar * w_bar / (32 * 32)) + 2
    print(f"图像的 Token 数：{token}")
  • 查看账单：您可以在阿里云控制台的费用与成本页面查看账单或进行充值。
  • 限流：视觉理解模型的限流条件参见限流。
  • 免费额度（仅北京地域）（仅新加坡地域）：从开通百炼或模型申请通过之日起计算有效期，有效期 90 天内，视觉理解模型提供 100 万 Token 的免费额度。

API参考

关于视觉理解模型的输入输出参数，请参见文本生成。

常见问题

推荐综合考虑SDK类型、文件大小以及网络稳定性来选择最合适的上传方式。

文件类型

文件规格

DashScope SDK（Python、Java）

OpenAI 兼容 / DashScope HTTP

图像

大于 7MB 小于 10MB

传入本地路径

仅支持公网 URL，建议使用阿里云对象存储服务

小于 7MB

传入本地路径

Base64 编码

视频

大于 100 MB

仅支持公网 URL，建议使用阿里云对象存储服务

仅支持公网 URL，建议使用阿里云对象存储服务

大于 7MB 小于 100 MB

传入本地路径

仅支持公网 URL，建议使用阿里云对象存储服务

小于 7MB

传入本地路径

Base64 编码

Base64 编码会增大数据体积，原始文件大小应小于 7 MB。
使用 Base64 或本地路径可避免服务端下载超时，提升稳定性。
视觉理解模型对输入的文件有大小限制，可通过以下方法压缩。
  • 在线工具：使用 CompressJPEG 等在线工具进行压缩。
  • 本地软件：使用 Photoshop 等软件，在导出时调整质量。
  • 代码实现：
# pip install pillow

from PIL import Image
def compress_image(input_path, output_path, quality=85):
    with Image.open(input_path) as img:
        img.save(output_path, "JPEG", optimize=True, quality=quality)

# 传入本地图像
compress_image("/xxx/before-large.jpeg","/xxx/after-min.jpeg")

# 批量压缩目录下的图像
import glob
import os

def batch_compress(input_dir, output_dir, quality=85):
    files = (
        glob.glob(os.path.join(input_dir, "*.jpg"))
        + glob.glob(os.path.join(input_dir, "*.jpeg"))
        + glob.glob(os.path.join(input_dir, "*.png"))
    )
    for i, f in enumerate(files, 1):
        try:
            compress_image(f, os.path.join(output_dir, os.path.basename(f)), quality)
            print(f"[{i}/{len(files)}] {os.path.basename(f)} done")
        except Exception as e:
            print(f"[{i}/{len(files)}] {os.path.basename(f)} error: {e}")

batch_compress("/xxx/input_dir", "/xxx/output_dir")
  • 在线工具：使用 FreeConvert 等在线工具进行压缩。
  • 本地软件：使用 HandBrake 等软件。
  • 代码实现：使用FFmpeg工具，更多用法请参见FFmpeg官网。
# 基础转换命令
# -i，作用：输入文件路径，常用值示例：input.mp4
# -vcodec，作用 视频编码器 ，一般取值有libx264（通用推荐）、libx265（压缩率更高）、
# -crf，作用：控制视频质量，取值范围：[18-28]，数值越小，质量越高，文件体积越大。
# --preset，作用：控制编码速度与压缩效率的平衡。一般取值有 slow、fast、faster
# -y，作用：覆盖已存在文件(无需赋值)
# output.mp4，作用：输出文件路径

ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset slow output.mp4
视觉理解模型输出物体定位效果后，可参照以下代码将检测框及其标签信息绘制到原图上。
  • Qwen2.5-VL：返回的坐标相对于缩放后的图像左上角的绝对值，单位为像素。可参见qwen2_5_vl_2d.py代码绘制检测框。
  • Qwen3-VL、Qwen3.5、Qwen3.6、Qwen3.7、Qwen3.8系列（如 qwen3.5-plus、qwen3.6-plus、qwen3.7-plus 等）：返回的坐标为相对坐标，坐标值会归一化到[0, 999]。可参见qwen3_vl_2d.py（二维定位）或qwen3_vl_3d.zip（三维定位）中的代码绘制检测框。

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。
阿里云百炼 home page阿里云百炼
开始使用
产品计费
Token Plan
模型体验
接入客户端/开发工具
模型推理
模型调优
模型部署
模型评测
模型压缩目录节点
用量统计与性能监控
资产中心
模型数据
安全合规
实践教程
服务支持
产品动态