QwenCloud 官方视觉 API 文档使用正式模型 ID qwen4-max 展示图像问答请求;默认按高细节处理,图像可设 vl_high_resolution_images 或 max_pixels 控制视觉分辨率与 token 消耗。
适合的任务:图像问答、读小字、识别局部细节、提取图像文字
不适合的任务:需要保证像素级识别准确率,或把示例当作图像格式与大小限制的完整清单
适用的模型版本:官方示例中的 qwen4-max
适用的客户端、Agent 或 API:QwenCloud OpenAI 兼容 Chat Completions;示例使用 OpenAI Python SDK
推荐的推理档位和参数:默认 detail=high;读细节时可启用高分辨率模式,或按任务设置 max_pixels
以下示例沿用官方新加坡区域端点和请求结构。先设置匹配区域的 API Key:
export DASHSCOPE_API_KEY="YOUR_QWENCLOUD_API_KEY"import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
response = client.chat.completions.create(
model="qwen4-max",
messages=[{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg",
# 可选:设置单图像素上限;Qwen4-Max 最大为 16,777,216。
# "max_pixels": 8_000_000,
},
},
{"type": "text", "text": "请读出图片右下角的编号,并说明不确定之处。"},
],
}],
# 可选:保留更高分辨率的图像细节,视觉 token 消耗也会增加。
# extra_body={"vl_high_resolution_images": True},
)
print(response.choices[0].message.content)按细节需求选择一项配置:默认配置成本较低;读小字或局部细节时可启用 vl_high_resolution_images=True。若要明确设置像素上限,可使用 max_pixels,Qwen4-Max 上限为 16,777,216。
使用和 API Key 相同区域的端点,将 model 设为 qwen4-max。
通过 image_url 传入可公开访问的图片 URL,并在同一用户消息中加入文本指令。
需要读小字或细节时,启用 vl_high_resolution_images 或提高 max_pixels;观察输入 token 和结果变化。
失败时检查图片 URL 可访问性、请求大小、格式和分辨率限制。
文档的视觉 API 示例在 OpenAI 兼容 Chat Completions 中使用 model="qwen4-max",并包含单图和多图请求示例,确认该正式模型版本支持视觉输入。
文档说明 Qwen4-Max 默认 detail=high;未设置 max_pixels 时,high 最多处理 16,777,216 像素,low 与 auto 上限为 2,621,440 像素。
Qwen4-Max 使用每个视觉 token 对应 32 × 32 像素的配置,视觉 token 上限为 16,384;可配置的 max_pixels 默认值为 2,621,440,上限为 16,777,216。
图像最短边需大于 10 像素,长宽比不超过 200:1。建议不超过 8K(7680 × 4320);更高分辨率可能增加传输时间并导致超时。
8K 以下支持 BMP、JPEG、PNG、TIFF、WEBP、HEIC;4K 至 8K 仅支持 JPEG、JPG、PNG。单次请求总大小上限为 64 MB;Qwen4-Max 单张公网 URL 图片及 Base64 编码前原图上限为 20 MB。
vl_high_resolution_images 会增加视觉 token 消耗。官方文档说明 Qwen4-Max 在该模式下仍可使用显式 max_pixels;未设置时,最大按 16,777,216 像素处理。
放大 max_pixels 不保证结果准确,官方建议先将超高分辨率图片缩放到合理尺寸;细节识别仍应检查模型输出。
以上格式、像素和大小限制来自当前 QwenCloud 视觉文档;其他模型或区域可能有不同限制。端点示例为新加坡区域,换区时应同时更换为该区端点和 API Key。
本文聚焦图像输入与分辨率。API Key、SDK 安装及通用接入步骤请参见同目录的 QwenCloud Codex 接入配置。
于 2026-11-17 通过 Tabbit 打开并核对 QwenCloud 官方视觉文档,检查 qwen4-max 图像调用示例、分辨率参数和图像限制。示例按官方 OpenAI 兼容接口改写;未使用真实 API Key 发起请求。
Qwen4-Max