Appearance
Use the Qwen3.7 model for visual understanding
Reference, synced 2026-06-13.
flowchart TD n0["Models"] n1["Overview"] n2["Products"] n3["Solutions"] n4["Pricing"] n5["Resources"] n6["Partners"] n7["Support"] n8["Language"] n0 --> n1 n1 --> n2 n2 --> n3 n3 --> n4 n4 --> n5 n5 --> n6 n6 --> n7 n7 --> n8
Free access Accelerate Delivery with Fixed-Cost Agentic CodingWatch how it works
Models
Empowering AI innovation for both enterprises and developers with Alibaba Cloud’s best-in-class Qwen models, AI-native apps, and AI solutions.
Alibaba Cloud Model Studio \ Enterprise-grade large model service and application development platform.
Try Visual Model \ Supports image understanding, image generation, and video generation.
Models
HappyHorse-1.0-T2V \ Cinematic creative generation, ultimate dynamic details Qwen3-VL-Plus \ Native VL, spatial reasoning, 1M-context video analysis Wan2.7-VideoEdit \ Supports both localized and global editing with prompt
Qwen3.6-Plus \ Native multimodal, 1M context, agentic coding Wan2.7-Image-Pro \ Interactive editing, long-text rendering, precise prompt following Qwen-Plus \ Balanced intelligence, efficient inference, production-ready performance
Qwen-Image-2.0 \ Professional infographics, exquisite photorealism Z-Image-Turbo \ Ultra-fast image generation, high throughput, cost-optimized inference Qwen3-Coder-Next \ Multi-turn tool interactions, future-ready development support
Wan2.7-T2V \ High-fidelity T2V, 15s duration, advanced camera control Wan2.7-I2V \ Cinematic I2V with emotional depth and visceral impact Wan2.7-R2V \ Up to 5 mixed image/video inputs and audio timbre cloning
GenAI Application
Qoder \ Intelligent coding assistant, available for enterprise-dedicated deployment. Qoder CN \ AI-powered coding assistant that boosts developer productivity with intelligent code completion, AI chat, multi-file editing, and task automation.
AI Service
Model Experience \ Experience full-scale, multimodal model capabilities online. Platform for AI \ An AI-native algorithm engineering platform for end-to-end modeling, training, and inference service deployment. Fine-tune Video Generation Model \ Customize Wan’s text-to-video capabilities through model fine-tuning to meet your unique requirements.
AI Use Case
AI Savings Plan Hot \ Save up to 47% on AI costs. Limited-time offer tailored to your usage. AI Video Creation \ Elevate your professional video production with Wan 2.6.
AI Token Plan \ One plan. Multiple models. Big Savings with a Fixed Subscription. AI Image Creation \ All-in-one creative suite for copywriting, image generation, and poster design.
Overview
As a global full-stack AI leader, Alibaba Cloud aims to make computing accessible to everyone and help worldwide customers accelerate innovation.
Why Alibaba Cloud
About Alibaba Cloud \ AI Powered Cloud Technology Our Global Network \ Explore our global presence and deployment regions around the world Our Global Offices \ With offices in 4 continents, we're always close to where it matters.
Asia Accelerator \ Accelerate Success in Asia with Alibaba Cloud Go Global \ Benefits of our Global Alliance Trust Center \ Empowering enterprises with a secure, compliant, and globally trusted cloud infrastructure
Customers and Insights
Olympic Games \ Alibaba Cloud Powers Olympic Games with AI-powered cloud technology Case Studies \ Learn how customers are scaling their businesses on Alibaba Cloud Analyst Reports \ Learn what the top industry analyst firms are saying about Alibaba Cloud
What's New
Events and Webinars \ Quick access to upcoming and on-demand events Product Updates \ Stay informed of the latest innovations Press Room \ Latest news and media releases
Products
Featured ProductsAI & Machine Learning Computing Container Storage Networking & CDN Security Middleware Database Analytics ComputingMedia ServicesEnterprise Services & Cloud CommunicationDomain Names and WebsitesEnd User ComputingServerlessDeveloper ToolsMigration & O&M ManagementApsara Stack
Featured Products
Alibaba Cloud Model Studio \ Supercharge your AI journey effortlessly with industry-leading GenAI models ApsaraDB RDS \ Store and manage your business data, with automated monitoring and backups Certificate Management Service (Original SSL Certificate) \ Create a safe and secure connection between your website and users
Elastic Compute Service (ECS) \ Host websites anywhere and scale enterprise workloads Container Service for Kubernetes (ACK) \ Run and scale containerized applications on managed Kubernetes infrastructure Object Storage Service (OSS) \ Store large amounts of data in the cloud and access it anywhere, anytime
Simple Application Server (SAS) \ All-in-one services for fast deployment Elastic IP Address (EIP) \ Manage your public IPs independently to improve internet network quality Domain Names and Website \ Get the perfect domain name to suit your every need
Related Programs
Solutions
Solutions by Industry Technical Solutions AI WebsitesNetworking Security and ComplianceData and AnalyticsEnterprise Service and ApplicationCloud MigrationCloud NativeHybrid CloudSMB solutions
Financial Services \ Innovate faster with Alibaba Cloud Games \ Grow your game rapidly with high global availability
New Retail \ Alibaba Cloud enables digital retail transformation to fuel growth and realize an omnichannel customer experience throughout the consumer journey. Media and Entertainment \ Ready your content for today's media market with a digitalized media journey
Supply Chain \ Power your supply chain with intelligent, efficient, and reliable solutions Sports \ Digitizing the sports industry with intelligent tech
Sustainability \ Achieve a sustainable future with low-carbon and energy-efficient technologies
Pricing
Flexible options like pay-as-you-go and clear billing rules to meet diverse business needs.
Overview & Tools
Pricing Calculator \ Get an instant pricing estimate based on your usage and needs Free Trial \ Try our 80+ cloud products for free.
Pricing Options \ Get the most out of Alibaba Cloud with flexible pricing
Optimize your cost
Migrate & Save \ Superior Performance At Lower Pricing. Save up to 50%. Promotion Center \ Unlock the latest Alibaba Cloud offers & promos
Resources
Official documentation, extensive tools, training resources, and a community to grow and innovate in the cloud.
Technical Resources
Documentation \ Product guides and FAQs Architecture Center \ Design reliable, secure, and efficient cloud architecture. Intelligent Solution Explorer \ Find the right solution for you, powered by AI
Blog \ Latest cloud insights and developer trends Whitepapers \ Research that explores the how and why behind our technology
Training&Certification
Alibaba Cloud Academy \ Build cloud skills and earn certifications with expert-led training.
Developer Hub
Alibaba Cloud Project Hub \ Explore real-world projects built by developers using our platform. Our Developer MVPs \ Celebrating the developers who lead, build, and inspire our community
Partners
Partner-first strategy offering collaborative product, sales, and service models, plus high-quality partner solutions that complement Alibaba Cloud’s capabilities.
Marketplace
AI Alliance for ISVs \ Partner with us to build and grow AI solutions together ISV Benefits \ Unlock resources, market access, and go-to-market support as an ISV partner
Alibaba Cloud Marketplace \ Explore ready-to-deploy solutions from our partners and ISVs
Find a Partner
Partner Hub \ Find your ideal partner in no time
Become a Partner
Partner Network \ A partner portal for Alibaba Cloud Channel, Technology, MSP partner and other partner programs
Support
Full-lifecycle support and expert services, from cloud advisory and migration to operations.
Support & Professional Services
Professional Services \ Expert-led services to design, migrate, and optimize your cloud journey Support Plans \ Flexible support for every stage — from startup to enterprise
Partner Support Program \ Priority technical support for partners, with dedicated managers and faster issue resolution
Contact us
Connect With Us \
Talk to a sales expert and get a custom quote for your business
Language
- English
- 简体中文
- 繁體中文
- 日本語
- Bahasa Indonesia
Locale
Visit aliyun.com
Documentation
Alibaba Cloud Model Studio
User Guide (Models) User Guide (Application) API Reference (Models) API Reference (Application)
Search for Help Content
Getting Started
The Beginner's Guide
Well-Architected Framework
AI & Machine Learning
Platform For AI
Alibaba Cloud Model Studio
DashVector
Artificial Intelligence Recommendation
OpenSearch
Image Search
Machine Translation
Intelligent Speech Interaction
Optimization Solver
Intelligent Computing LINGJUN
Computing
Elastic Compute Service
Elastic GPU Service
Elastic Container Instance
Dedicated Host
Compute Nest
Simple Application Server
Cloud Box
Auto Scaling
Elastic High Performance Computing
Batch Compute (Deprecated)
Function Compute
Serverless App Engine
ENS
Elastic Desktop Service
App Streaming
WUYING Terminal
Cloud Phone
Edge Network Acceleration
Alibaba Cloud Linux
AgentBay
Container
Container Service for Kubernetes
Container Compute Service
Container Registry
Storage
Object Storage Service
Cloud Parallel File Storage
File Storage NAS
Tablestore
Storage Capacity Unit
Simple Log Service
Cloud Backup
Intelligent Media Management
Drive and Photo Service
Data Transport
Cloud Storage Gateway
Data Online Migration
Hybrid Cloud Storage Array
Storage Services Overview
Backup and Disaster Recovery Center
Networking and CDN
Server Load Balancer
Elastic IP Address
Internet Shared Bandwidth
Data Transfer Plan
Virtual Private Cloud
NAT Gateway
PrivateLink
Alibaba Cloud DNS PrivateZone
Network Intelligence Service
Cloud Data Transfer
IPv6 Gateway
Anycast Elastic IP Address
Cloud Enterprise Network
Global Accelerator
VPN Gateway
Smart Access Gateway
Express Connect
CDN
Edge Security Acceleration
Cloud Network Well-architected Design Guidelines
Security
Anti-DDoS
Web Application Firewall
Cloud Firewall
Security Center
Bastionhost
Secure Access Service Edge
Certificate Management Service
Key Management Service
Data Security Center
Identity as a Service
Fraud Detection
AI Guardrails
Captcha
Blockchain as a Service
ID Verification
Managed Security Service
Middleware
Enterprise Distributed Application Service
Microservices Engine
Alibaba Cloud Service Mesh
SchedulerX
ApsaraMQ for RocketMQ
ApsaraMQ for Kafka
ApsaraMQ for RabbitMQ
ApsaraMQ for MQTT
Simple Message Queue (formerly MNS)
CloudFlow
EventBridge
Application Real-Time Monitoring Service
Managed Service for Prometheus
Managed Service for Grafana
Managed Service for OpenTelemetry
Performance Testing
Databases
ApsaraDB Console
PolarDB
ApsaraDB RDS
ApsaraDB for OceanBase (Deprecated)
Tair (Redis® OSS-Compatible)
Lindorm
Time Series Database
ApsaraDB for MongoDB
ApsaraDB for HBase
ApsaraDB for Memcache
ApsaraDB for MyBase
AnalyticDB
ApsaraDB for ClickHouse
ApsaraDB for SelectDB
Data Transmission Service
Database Autonomy Service
Data Management
Database Gateway - Deprecated
ApsaraDB for Cassandra - Deprecated
Analytics Computing
MaxCompute
Hologres
Realtime Compute for Apache Flink
Elasticsearch
Vector Retrieval Service for Milvus
E-MapReduce
Data Lake Formation
DataV
Quick BI
Quick Audience
Quick Tracking
DataWorks
DataHub
Dataphin
Media Services
ApsaraVideo VOD
ApsaraVideo Live
Intelligent Media Services
ApsaraVideo Media Processing
Apsara Video SDK
Enterprise Services & Cloud Communication
Energy Expert
CloudQuotation
Salesforce on Alibaba Cloud
GoChina ICP Filing Assistant
Marketplace
Alibaba Mail
Direct Mail
Short Message Service
Voice Service
Phone Number Verification Service
Cell Phone Number Service
Chat App Message Service
Financial Intelligence Engine
Domain Names and Websites
Domain Names
ICP Filing
Alibaba Cloud DNS
End User Computing
Elastic Desktop Service
App Streaming
WUYING Terminal
Cloud Phone
AgentBay
Internet of Things
IoT Platform
Serverless
Serverless App Engine
CloudFlow
EventBridge
Simple Message Queue (formerly MNS)
Function Compute
Developer Tools
OpenAPI Explorer
Alibaba Cloud SDK
Cloud Shell
Resource Orchestration Service
Alibaba Cloud CLI
BSS OpenAPI
Terraform
Pulumi
Ticket System API
Mobile Platform as a Service
Alibaba Cloud DevOps
API Gateway
Cloud Control API
AI Coding Assistant Lingma
Cloud Skills Portal
Migration & O&M Management
CloudOps Orchestration Service
Cloud Monitor
Intelligent Advisor
Cloud Governance Center
ActionTrail
Cloud Config
Resource Access Management
Resource Management
Cloud Architect Design Tools
Migration Hub
Server Migration Center
Service Catalog
Logic Composer
Quota Center
CloudSSO
HTTPDNS
Solutions
SAP
SuperApp
OpenLake
Membership Service
Expenses and Costs
Account Center
More
Support
Legal
Tech Share Terms and Conditions
After Sales Support
China Gateway Program
Service Level Objectives
Management Console
Security Control
Visual understanding models analyze the images or videos you provide and return natural-language answers. They support single and multiple image inputs and cover tasks such as image captioning, visual question answering, OCR, object detection, document parsing, and video content analysis. This document covers image and video understanding only. For video generation, see the video generation documentation.
Try online: Go to the Model Studio console, select a region in the upper-right corner, and navigate to the Vision page.
Getting started
Prerequisites
Obtain an API key and set the API key as an environment variable.
If you make calls using an SDK, install the SDK. The DashScope Python SDK must be version 1.24.6 or later, and the DashScope Java SDK must be version 2.21.10 or later.
The following example calls a model to describe an image. For other input methods, see Pass local files and Image limits.
OpenAI compatible
DashScope
Python
Node.js
curl
python
from openai import OpenAI
import os
client = OpenAI(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)
completion = client.chat.completions.create(
model="qwen3.7-plus", # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/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": "What is depicted in the image?"},\
],\
},\
],
)
print(completion.choices[0].message.content)Response
plaintext
This is a photo taken on a beach. In the photo, a person and a dog are sitting on the sand, with the sea and sky in the background. The person and the dog seem to be interacting, with the dog's front paw resting on the person's hand. The sunlight is coming from the right side of the frame, adding a warm atmosphere to the whole scene.nodejs
import OpenAI from "openai";
const openai = new OpenAI({
// API keys vary by region. To get an API key, visit: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If an environment variable is not set, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
});
async function main() {
const response = await openai.chat.completions.create({
model: "qwen3.7-plus", // This example uses qwen3.7-plus. Change the model name as needed. Model List: https://www.alibabacloud.com/help/model-studio/getting-started/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: "What is shown in the picture?"\
}\
]\
}\
]
});
console.log(response.choices[0].message.content);
}
main()Response
plaintext
This is a photo taken on a beach. In the photo, a person and a dog are sitting on the sand, with the sea and sky in the background. The person and the dog seem to be interacting, and the dog's front paw is on the person's hand. Sunlight is coming from the right side of the frame, which adds a warm atmosphere to the scene.curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3.7-plus",
"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": "What is depicted in the image?"}\
]\
}]
}'Response
json
{
"choices": [\
{\
"message": {\
"content": "This is a photo taken on a beach. In the photo, a person and a dog are sitting on the sand, with the sea and sky in the background. The person and the dog seem to be interacting, with the dog's front paw resting on the person's hand. The sunlight is coming from the right side of the frame, adding a warm atmosphere to the whole scene.",\
"role": "assistant"\
},\
"finish_reason": "stop",\
"index": 0,\
"logprobs": null\
}\
],
"object": "chat.completion",
"usage": {
"prompt_tokens": 1270,
"completion_tokens": 54,
"total_tokens": 1324
},
"created": 1725948561,
"system_fingerprint": null,
"model": "qwen3.7-plus",
"id": "chatcmpl-0fd66f46-b09e-9164-a84f-3ebbbedbac15"
}Python
Java
curl
python
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [\
{\
"role": "user",\
"content": [\
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},\
{"text": "What is depicted in the image?"}]\
}]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus', # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=messages
)
print(response.output.choices[0].message.content[0]["text"])Response
plaintext
This is a photo taken on a beach. In the photo, there is a woman and a dog. The woman is sitting on the sand, smiling and interacting with the dog. The dog is wearing a collar and seems to be shaking hands with the woman. The background is the sea and the sky, and the sunlight shining on them creates a warm atmosphere.java
import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
static {
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"),
Collections.singletonMap("text", "What is depicted in the image?"))).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured environment variables, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus") // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}Response
plaintext
This is a photo taken on a beach. In the photo, there is a person wearing a plaid shirt and a dog wearing a collar. The person and the dog are sitting face to face, seemingly interacting. The background is the sea and the sky, and the sunlight shining on them creates a warm atmosphere.curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{\
"role": "user",\
"content": [\
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},\
{"text": "What is depicted in the image?"}\
]\
}\
]
}
}'Response
json
{
"output": {
"choices": [\
{\
"finish_reason": "stop",\
"message": {\
"role": "assistant",\
"content": [\
{\
"text": "This is a photo taken on a beach. In the photo, there is a person wearing a plaid shirt and a dog wearing a collar. They are sitting on the sand, with the sea and sky in the background. The sunlight is coming from the right side of the frame, adding a warm atmosphere to the whole scene."\
}\
]\
}\
}\
]
},
"usage": {
"output_tokens": 55,
"input_tokens": 1271,
"image_tokens": 1247
},
"request_id": "ccf845a3-dc33-9cda-b581-20fe7dc23f70"
}Select a model
- Qwen3.7: The latest generation of unified visual-language multimodal agent models. Offers further improvements in multimodal reasoning, code development, and tool calling compared to Qwen3.6.
qwen3.7-plus: The most capable model. Recommended.
- Qwen3.6: Offers significant improvements in code development, generalization, and multimodal capabilities such as object recognition, OCR, and object detection compared to Qwen3.5.
qwen3.6-plus: The most capable model in the series. Recommended.qwen3.6-flash: Faster and more cost-effective.qwen3.6-35b-a3b: The open source model from the Qwen3.6 series.
- Qwen3.5: Excels at multimodal reasoning, 2D/3D image understanding, complex document parsing, visual programming, video understanding, and multimodal agents.
qwen3.5-plus: A powerful visual understanding model that excels at multimodal reasoning and video understanding.qwen3.5-flash: Faster and more cost-effective. Suitable for latency-sensitive scenarios.qwen3.5-397b-a17b,qwen3.5-122b-a10b,qwen3.5-27b, andqwen3.5-35b-a3b: The open source models from the Qwen3.5 series.
- Qwen3-VL: Suited for high-precision object recognition and detection (including 3D detection), agent tool calling, document and webpage parsing, complex problem-solving, and long video understanding. The models in this series:
qwen3-vl-plus: The most capable model in the Qwen3-VL series.qwen3-vl-flash: Faster and more cost-effective. Suitable for latency-sensitive scenarios.
- Qwen2.5-VL: Suited for general tasks such as simple image captioning and short video synopsis extraction. The models in this series:
qwen-vl-max(belongs to Qwen2.5-VL): The best-performing model in the Qwen2.5-VL series.qwen-vl-plus(belongs to Qwen2.5-VL): Faster and provides a good balance between performance and cost.
For model names, context length, prices, and snapshot versions, see the Model Studio console. For rate limiting, see Rate limits.
Model feature comparison
| Model | Deep thinking | Tool calling | Context cache | Structured output | Supported languages |
Qwen3.7 series, Qwen3.6 series, Qwen3.5 series | Supported | Supported | qwen3.7-plus, qwen3.6-plus, qwen3.6-flash, qwen3.5-plus, qwen3.5-flash > qwen3.6-flash and qwen3.5-flash support only explicit caching. | Supported in non-thinking mode | 33 languages: Chinese, Japanese, Korean, Indonesian, Vietnamese, Thai, English, French, German, Russian, Portuguese, Spanish, Italian, Swedish, Danish, Czech, Norwegian, Dutch, Finnish, Turkish, Polish, Swahili, Romanian, Serbian, Greek, Kazakh, Uzbek, Cebuano, Arabic, Urdu, Persian, Hindi/Devanagari, and Hebrew. |
Qwen3-VL series | Supported | Supported | Support for stable versions of qwen3-vl-plus and qwen3-vl-flash | Supported in non-thinking mode | 33 languages: Chinese, Japanese, Korean, Indonesian, Vietnamese, Thai, English, French, German, Russian, Portuguese, Spanish, Italian, Swedish, Danish, Czech, Norwegian, Dutch, Finnish, Turkish, Polish, Swahili, Romanian, Serbian, Greek, Kazakh, Uzbek, Cebuano, Arabic, Urdu, Persian, Hindi/Devanagari, and Hebrew. |
Qwen2.5-VL series | Not supported | Not supported | Support for stable versions of qwen-vl-max and qwen-vl-plus | The stable and latest versions of qwen-vl-max and qwen-vl-plus are supported. | 11 languages: Chinese, English, Japanese, Korean, Arabic, Vietnamese, French, German, Italian, Spanish, and Russian. |
Model capabilities
Visual understanding models excel in enterprise use cases such as:
Image Q&A: identify objects, answer questions about image content, and classify or label images
Creative writing: generate captions, social media copy, and short video scripts from visual content
Text recognition and information extraction: extract structured data from receipts, certificates, and forms using OCR
Multidisciplinary problem-solving: solve math, physics, and chemistry problems presented as images
Visual programming: generate HTML, CSS, and JavaScript code from design mockups or screenshots
Object detection: locate objects in 2D and 3D space, with bounding box and centroid coordinate output
Document parsing: convert image-based documents and PDFs into structured HTML or Markdown
Video understanding: analyze video content, locate specific events, and generate time-stamped summaries
Image Q&A
Describe image content, or classify and label it, such as identifying people, places, animals, and plants.
| If the sun is glaring, what item from this picture should I use? | When the sun is glaring, you should use the pink sunglasses in the picture. Sunglasses can effectively block strong light, reduce UV damage to the eyes, and help protect your vision and improve visual comfort in bright sunlight. |
|---|
| If the sun is glaring, what item from this picture should I use? | When the sun is glaring, you should use the pink sunglasses in the picture. Sunglasses can effectively block strong light, reduce UV damage to the eyes, and help protect your vision and improve visual comfort in bright sunlight. |
Creative writing
Generate text descriptions from image or video content, suitable for storytelling, copywriting, and short video scripts.
| Please help me write an interesting social media post based on the content of the picture. | Of course. This picture is filled with a rich Mid-Autumn Festival atmosphere, cleverly combining classical and modern elements. Based on the main elements in the picture, I have prepared several social media posts in different styles for you to choose from. Poetic and aesthetic style Tonight, the moon is bright for all to see, but where do autumn thoughts fall? Chang'e flies to the moon, the Jade Rabbit pounds medicine—the romance of the ancients is lit up tonight. May this bright moon light your way home and carry my deepest thoughts to you. Happy Mid-Autumn Festival! Warm and blessing style A full moon brings people together, making the Mid-Autumn night the gentlest. Watch the fireworks bloom, admire the full moon in the sky, take a bite of a mooncake, and want for good health. May all that you and I want for come true. Happy Mid-Autumn Festival and a happy family reunion to everyone! |
Text recognition and information extraction
Recognize text and formulas in images, or extract information from receipts, certificates, and forms. Supports formatted text output. For supported languages, see Model feature comparison.
| Extract the following from the image: ['Invoice Code', 'Invoice Number', 'Destination', 'Fuel Surcharge', 'Fare', 'Date of Travel', 'Departure Time', 'Train Number', 'Seat Number']. Please output in JSON format. |
Multidisciplinary problem-solving
Solve problems in images related to mathematics, physics, chemistry, and other subjects, at primary, secondary, university, and adult education levels.
| Please solve the math problem in the image step by step. |
|---|
| Please solve the math problem in the image step by step. |
Visual programming
Generate code from images or videos, such as creating HTML, CSS, and JavaScript from design drafts or website screenshots.
| Create a webpage using HTML and CSS based on my sketch, with black as the main color. | Webpage preview |
|---|
| Create a webpage using HTML and CSS based on my sketch, with black as the main color. | Webpage preview |
Object detection
Supports 2D and 3D detection for determining object orientation, perspective, and occlusion relationships. 3D detection requires the Qwen3-VL model series.
The object detection performance of the Qwen2.5-VL model is robust within a resolution range of 480 × 480 to 2560 × 2560. Outside this range, the detection accuracy may decrease, and detection frame drift may occasionally occur.
To draw detection results on the original image, see the FAQ section.
| 2D positioning - Return Box (bounding box) coordinates: Detect all food items in the image and output their bbox coordinates in JSON format. - Return Point (centroid) coordinates: Locate all food items in the image as points and output their point coordinates in XML format. | Visualization of 2D positioning results |
3D positioning Detect the car in the image and predict its 3D position. Output JSON: [{"bbox_3d": [x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw], "label": "category"}]. | Visualization of 3D positioning results |
Document parsing
Parse image-based documents, such as scans or image PDFs, into QwenVL HTML or QwenVL Markdown format. This format accurately recognizes text and retrieves position information for elements such as images and tables. The Qwen3-VL model also supports parsing into standard Markdown format.
The recommended prompts are:
qwenvl html(to parse into HTML format) orqwenvl markdown(to parse into Markdown format).
| qwenvl markdown. | Visualization of results |
|---|
| qwenvl markdown. | Visualization of results |
Video understanding
Analyze video content, locate specific events with timestamps, or generate summaries of key time periods. This section covers video understanding only. For video generation, see the video generation documentation.
| Please describe the series of actions of the person in the video. Output the start time (start_time), end time (end_time), and event (event) in JSON format. Please use HH:mm:ss to represent the timestamp. | { "events": [ { "start_time": "00:00:00", "end_time": "00:00:05", "event": "A person walks towards a table holding a cardboard box and places it on the table." }, { "start_time": "00:00:05", "end_time": "00:00:15", "event": "The person picks up a scanner and scans the label on the cardboard box." }, { "start_time": "00:00:15", "end_time": "00:00:21", "event": "The person puts the scanner back in its place and then picks up a pen to record information in a notebook."}] } |
Key features
Enable or disable thinking mode
- The
qwen3.6,qwen3.5,qwen3-vl-plus, andqwen3-vl-flashseries are hybrid thinking models that can respond with or without a reasoning step. Use theenable_thinkingparameter to control thinking mode:true: Enables thinking mode. The default value forqwen3.6andqwen3.5series models istrue.false: Disables thinking mode. The default value forqwen3-vl-plusandqwen3-vl-flashseries models isfalse.
- Models with the
thinkingsuffix, such asqwen3-vl-235b-a22b-thinking, are thinking-only models. They always reason before responding; this cannot be disabled.
Important
Model configuration: In general conversation scenarios without agent tool calling, omit the
System Messagefor optimal performance. Pass role settings and output format requirements through theUser Messageinstead.Use streaming output: When thinking mode is enabled, both streaming and non-streaming output are supported. To avoid timeouts from long responses, use streaming output.
Limit thinking length: Deep thinking models can produce lengthy reasoning. Use the
thinking_budgetparameter to cap the thinking length. If tokens generated during thinking exceedthinking_budget, the thinking is truncated and the model generates the final response immediately. The default value ofthinking_budgetis the model's maximum chain-of-thought length. For details, see the model list.
OpenAI compatible
DashScope
The enable_thinking parameter is not a standard OpenAI parameter. If you use the OpenAI Python SDK, you can pass it through extra_body.
Python
Node.js
curl
Python
python
import os
from openai import OpenAI
client = OpenAI(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)
reasoning_content = "" # Define the complete thinking process
answer_content = "" # Define the complete response
is_answering = False # Determine whether to end the thinking process and start responding
enable_thinking = True
# Create a chat completion request
completion = client.chat.completions.create(
model="qwen3.7-plus",
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": "How do I solve this problem?"},\
],\
},\
],
stream=True,
# The enable_thinking parameter enables the thinking process, and the thinking_budget parameter sets the maximum number of tokens for the inference process.
# Switch thinking mode using the enable_thinking parameter.
extra_body={
'enable_thinking': enable_thinking,
"thinking_budget": 81920},
# Uncomment the following to return token usage in the last chunk.
# stream_options={
# "include_usage": True
# }
)
if enable_thinking:
print("\n" + "=" * 20 + "Thinking Process" + "=" * 20 + "\n")
for chunk in completion:
# If chunk.choices is empty, print usage.
if not chunk.choices:
print("\nUsage:")
print(chunk.usage)
else:
delta = chunk.choices[0].delta
# Print the thinking process.
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:
# Start responding.
if delta.content != "" and is_answering is False:
print("\n" + "=" * 20 + "Complete Response" + "=" * 20 + "\n")
is_answering = True
# Print the response process.
print(delta.content, end='', flush=True)
answer_content += delta.content
# print("=" * 20 + "Complete Thinking Process" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "Complete Response" + "=" * 20 + "\n")
# print(answer_content)Node.js
nodejs
import OpenAI from "openai";
// Initialize the OpenAI client.
const openai = new OpenAI({
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
});
let reasoningContent = '';
let answerContent = '';
let isAnswering = false;
let enableThinking = true;
let 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: "Solve this problem" },\
]\
}]
async function main() {
try {
const stream = await openai.chat.completions.create({
model: 'qwen3.7-plus',
messages: messages,
stream: true,
// Note: In the Node.js SDK, non-standard parameters like enableThinking are passed as top-level properties and do not need to be placed in extra_body.
enable_thinking: enableThinking,
thinking_budget: 81920
});
if (enableThinking){console.log('\n' + '='.repeat(20) + 'Thinking Process' + '='.repeat(20) + '\n');}
for await (const chunk of stream) {
if (!chunk.choices?.length) {
console.log('\nUsage:');
console.log(chunk.usage);
continue;
}
const delta = chunk.choices[0].delta;
// Process the thinking process.
if (delta.reasoning_content) {
process.stdout.write(delta.reasoning_content);
reasoningContent += delta.reasoning_content;
}
// Process the formal response.
else if (delta.content) {
if (!isAnswering) {
console.log('\n' + '='.repeat(20) + 'Complete Response' + '='.repeat(20) + '\n');
isAnswering = true;
}
process.stdout.write(delta.content);
answerContent += delta.content;
}
}
} catch (error) {
console.error('Error:', error);
}
}
main();curl
curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3.7-plus",
"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": "Please solve this problem"\
}\
]\
}\
],
"stream":true,
"stream_options":{"include_usage":true},
"enable_thinking": true,
"thinking_budget": 81920
}'Python
Java
curl
Python
python
import os
import dashscope
from dashscope import MultiModalConversation
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
enable_thinking=True
messages = [\
{\
"role": "user",\
"content": [\
{"image": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"},\
{"text": "Solve this problem?"}\
]\
}\
]
response = MultiModalConversation.call(
# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx",
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv('DASHSCOPE_API_KEY'),
model="qwen3.7-plus",
messages=messages,
stream=True,
# The enable_thinking parameter enables the thinking process.
# Switch thinking mode using the enable_thinking parameter.
enable_thinking=enable_thinking,
# The thinking_budget parameter sets the maximum number of tokens for the inference process.
thinking_budget=81920,
)
# Define the complete thinking process.
reasoning_content = ""
# Define the complete response.
answer_content = ""
# Determine whether to end the thinking process and start responding.
is_answering = False
if enable_thinking:
print("=" * 20 + "Thinking Process" + "=" * 20)
for chunk in response:
# If both the thinking process and the response are empty, ignore.
message = chunk.output.choices[0].message
reasoning_content_chunk = message.get("reasoning_content", None)
if (chunk.output.choices[0].message.content == [] and
reasoning_content_chunk == ""):
pass
else:
# If it is currently in the thinking process.
if reasoning_content_chunk is not None and chunk.output.choices[0].message.content == []:
print(chunk.output.choices[0].message.reasoning_content, end="")
reasoning_content += chunk.output.choices[0].message.reasoning_content
# If it is currently responding.
elif chunk.output.choices[0].message.content != []:
if not is_answering:
print("\n" + "=" * 20 + "Complete Response" + "=" * 20)
is_answering = True
print(chunk.output.choices[0].message.content[0]["text"], end="")
answer_content += chunk.output.choices[0].message.content[0]["text"]
# To print the complete thinking process and complete response, uncomment and run the following code.
# print("=" * 20 + "Complete Thinking Process" + "=" * 20 + "\n")
# print(f"{reasoning_content}")
# print("=" * 20 + "Complete Response" + "=" * 20 + "\n")
# print(f"{answer_content}")Java
java
// The DashScope SDK version must be 2.21.10 or later.
import java.util.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import io.reactivex.Flowable;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.exception.InputRequiredException;
import java.lang.System;
import com.alibaba.dashscope.utils.Constants;
public class Main {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
static {Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";}
private static final Logger logger = LoggerFactory.getLogger(Main.class);
private static StringBuilder reasoningContent = new StringBuilder();
private static StringBuilder finalContent = new StringBuilder();
private static boolean isFirstPrint = true;
private static void handleGenerationResult(MultiModalConversationResult message) {
String re = message.getOutput().getChoices().get(0).getMessage().getReasoningContent();
String reasoning = Objects.isNull(re)?"":re; // Default value
List<Map<String, Object>> content = message.getOutput().getChoices().get(0).getMessage().getContent();
if (!reasoning.isEmpty()) {
reasoningContent.append(reasoning);
if (isFirstPrint) {
System.out.println("====================Thinking Process====================");
isFirstPrint = false;
}
System.out.print(reasoning);
}
if (Objects.nonNull(content) && !content.isEmpty()) {
Object text = content.get(0).get("text");
finalContent.append(content.get(0).get("text"));
if (!isFirstPrint) {
System.out.println("\n====================Complete Response====================");
isFirstPrint = true;
}
System.out.print(text);
}
}
public static MultiModalConversationParam buildMultiModalConversationParam(MultiModalMessage Msg) {
return MultiModalConversationParam.builder()
// If you have not configured environment variables, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.messages(Arrays.asList(Msg))
.enableThinking(true)
.thinkingBudget(81920)
.incrementalOutput(true)
.build();
}
public static void streamCallWithMessage(MultiModalConversation conv, MultiModalMessage Msg)
throws NoApiKeyException, ApiException, InputRequiredException, UploadFileException {
MultiModalConversationParam param = buildMultiModalConversationParam(Msg);
Flowable<MultiModalConversationResult> result = conv.streamCall(param);
result.blockingForEach(message -> {
handleGenerationResult(message);
});
}
public static void main(String[] args) {
try {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMsg = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(Collections.singletonMap("image", "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"),
Collections.singletonMap("text", "Please solve this problem")))
.build();
streamCallWithMessage(conv, userMsg);
// Print the final result.
// if (reasoningContent.length() > 0) {
// System.out.println("\n====================Complete Response====================");
// System.out.println(finalContent.toString());
// }
} catch (ApiException | NoApiKeyException | UploadFileException | InputRequiredException e) {
logger.error("An exception occurred: {}", e.getMessage());
}
System.exit(0);
}
}curl
curl
# ======= Important =======
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-SSE: enable' \
-d '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{\
"role": "user",\
"content": [\
{"image": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"},\
{"text": "Please solve this problem"}\
]\
}\
]
},
"parameters":{
"enable_thinking": true,
"incremental_output": true,
"thinking_budget": 81920
}
}'Multiple image input
Visual understanding models support multiple images in a single request, useful for tasks such as product comparison and multi-page document processing. Include multiple image objects in the user message``content array.
Important
The number of images is limited by the model's total token limit for images and text. The total token count for all images and text must not exceed the model's maximum input limit.
OpenAI compatible
DashScope
Python
Node.js
curl
python
import os
from openai import OpenAI
client = OpenAI(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus", # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/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": "What do these images depict?"},\
],\
}\
],
)
print(completion.choices[0].message.content)Response
plaintext
Image 1 shows a woman and a Labrador Retriever interacting on a beach. The woman is wearing a plaid shirt and sitting on the sand, shaking hands with the dog. The background shows ocean waves and the sky. The whole scene has a warm and pleasant atmosphere.
Image 2 shows a tiger walking in a forest. The tiger has orange and black stripes and is walking forward. It is surrounded by dense trees and vegetation, and the ground is covered with fallen leaves. The scene gives a feeling of wild nature.nodejs
import OpenAI from "openai";
const openai = new OpenAI(
{
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
);
async function main() {
const response = await openai.chat.completions.create({
model: "qwen3.7-plus", // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/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: "What do these images depict?" },\
]}]
});
console.log(response.choices[0].message.content);
}
main()Response
plaintext
In the first image, a person and a dog are interacting on a beach. The person is wearing a plaid shirt, and the dog is wearing a collar. They appear to be shaking hands or giving a high-five.
In the second image, a tiger is walking in a forest. The tiger has orange and black stripes, and the background consists of green trees and vegetation.curl
# ======= Important =======
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"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": "What do these images depict?"\
}\
]\
}\
]
}'Response
json
{
"choices": [\
{\
"message": {\
"content": "Image 1 shows a woman and a Labrador Retriever interacting on a beach. The woman is wearing a plaid shirt and sitting on the sand, shaking hands with the dog. The background shows a sea view and a sunset sky, making the whole scene look very warm and harmonious.\n\nImage 2 shows a tiger walking in a forest. The tiger has orange and black stripes and is walking forward. It is surrounded by dense trees and vegetation, and the ground is covered with fallen leaves. The whole scene is full of natural wildness and vitality.",\
"role": "assistant"\
},\
"finish_reason": "stop",\
"index": 0,\
"logprobs": null\
}\
],
"object": "chat.completion",
"usage": {
"prompt_tokens": 2497,
"completion_tokens": 109,
"total_tokens": 2606
},
"created": 1725948561,
"system_fingerprint": null,
"model": "qwen3.7-plus",
"id": "chatcmpl-0fd66f46-b09e-9164-a84f-3ebbbedbac15"
}Python
Java
curl
python
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [\
{\
"role": "user",\
"content": [\
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},\
{"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},\
{"text": "What do these images depict?"}\
]\
}\
]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus', # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/en/model-studio/getting-started/models
messages=messages
)
print(response.output.choices[0].message.content[0]["text"])Response
plaintext
These images show some animals and natural scenes. The first image shows a person and a dog interacting on a beach. The second image shows a tiger walking in a forest.java
import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"),
Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"),
Collections.singletonMap("text", "What do these images depict?"))).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus") // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text")); }
public static void main(String[] args) {
try {
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}Response
plaintext
These images show some animals and natural scenes.
1. First image: A woman and a dog are interacting on a beach. The woman is wearing a plaid shirt and sitting on the sand. The dog is wearing a collar and extending its paw to shake hands with the woman.
2. Second image: A tiger is walking in a forest. The tiger has orange and black stripes, and the background consists of trees and leaves.curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{\
"role": "user",\
"content": [\
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},\
{"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},\
{"text": "What do these images show?"}\
]\
}\
]
}
}'Response
json
{
"output": {
"choices": [\
{\
"finish_reason": "stop",\
"message": {\
"role": "assistant",\
"content": [\
{\
"text": "These images show some animals and natural scenes. The first image shows a person and a dog interacting on a beach. The second image shows a tiger walking in a forest."\
}\
]\
}\
}\
]
},
"usage": {
"output_tokens": 81,
"input_tokens": 1277,
"image_tokens": 2497
},
"request_id": "ccf845a3-dc33-9cda-b581-20fe7dc23f70"
}Video understanding
Visual understanding models process video content from image lists (pre-extracted frames) or video files. For video limits and the maximum number of images per image list, see the Video limits section.
Use the latest or a recent snapshot version of a high-performance model to understand video files.
Video files
Image list
Visual understanding models analyze video by extracting frames. Control frame extraction with the following parameters:
- fps: Controls the frame extraction frequency. One frame is extracted every fps1 seconds. The value ranges from 0.1 to 10. The default value is 2.0.
High-motion scenarios: Set a higher fps value to capture more details.
Static or long videos: Set a lower fps value to improve processing efficiency.
- max_frames: Caps the maximum number of frames extracted from a video. If the frame count calculated from fps exceeds this limit, the system samples frames evenly within the cap. This parameter is only available when using the DashScope SDK.
OpenAI compatible
DashScope
When you input a video file to a visual understanding model using the OpenAI SDK or HTTP, you must set the
"type"parameter in the user message to"video_url".
Python
Node.js
curl
python
import os
from openai import OpenAI
client = OpenAI(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus",
messages=[\
{\
"role": "user",\
"content": [\
# When you input a video file directly, set the value of type to 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": "What is the content of this video?"\
}\
]\
}\
]
)
print(completion.choices[0].message.content)nodejs
import OpenAI from "openai";
const openai = new OpenAI(
{
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
);
async function main() {
const response = await openai.chat.completions.create({
model: "qwen3.7-plus",
messages: [\
{\
role: "user",\
content: [\
// When you input a video file directly, set the value of type to 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: "What is the content of this video?"\
}\
]\
}\
]
});
console.log(response.choices[0].message.content);
}
main();curl
# ======= Important =======
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"messages": [\
{\
"role": "user",\
"content": [\
{\
"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": "What is the content of this video?"\
}\
]\
}\
]
}'Python
Java
curl
python
import dashscope
import os
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [\
{"role": "user",\
"content": [\
# The fps parameter controls the video frame extraction frequency. It indicates that one frame is extracted every 1/fps seconds. For complete usage, see https://www.alibabacloud.com/help/model-studio/use-qwen-by-calling-api?#2ed5ee7377fum\
{"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4","fps":2},\
{"text": "What is the content of this video?"}\
]\
}\
]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key ="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus',
messages=messages
)
print(response.output.choices[0].message.content[0]["text"])java
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
// The fps parameter controls the video frame extraction frequency. It indicates that one frame is extracted every 1/fps seconds. For complete usage, see https://www.alibabacloud.com/help/model-studio/use-qwen-by-calling-api?#2ed5ee7377fum
Map<String, Object> params = new HashMap<>();
params.put("video", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4");
params.put("fps", 2);
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
params,
Collections.singletonMap("text", "What is the content of this video?"))).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{"role": "user","content": [{"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4","fps":2},\
{"text": "What is the content of this video?"}]}]}
}'When you provide a video as an image list (pre-extracted video frames), you can use the fps parameter to specify the time interval between frames. This helps the model better understand the sequence, duration, and dynamic changes of events. The model uses the fps parameter to determine the frame rate of the original video, indicating that frames were extracted every fps1 seconds. This parameter is supported by the Qwen3.6, Qwen3-VL, and Qwen2.5-VL models.
OpenAI compatible
DashScope
When you input a video as an image list to a visual understanding model using the OpenAI SDK or HTTP, you must set the
"type"parameter in the user message to"video".
Python
Node.js
curl
python
import os
from openai import OpenAI
client = OpenAI(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus", # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=[{"role": "user","content": [\
# When you provide an image list, the "type" parameter in the user message is "video".\
{"type": "video","video": [\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg"],\
"fps":2},\
{"type": "text","text": "Describe the specific process in this video"},\
]}]
)
print(completion.choices[0].message.content)nodejs
// Make sure you have specified "type": "module" in your package.json file.
import OpenAI from "openai";
const openai = new OpenAI({
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
});
async function main() {
const response = await openai.chat.completions.create({
model: "qwen3.7-plus", // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages: [{\
role: "user",\
content: [\
{\
// When you provide an image list, the "type" parameter in the user message is "video".\
type: "video",\
video: [\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg"],\
"fps": 2\
},\
{\
type: "text",\
text: "Describe the specific process in this video"\
}\
]\
}]
});
console.log(response.choices[0].message.content);
}
main();curl
# ======= Important =======
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"messages": [{"role": "user","content": [{"type": "video","video": [\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg"],\
"fps":2},\
{"type": "text","text": "Describe the specific process in this video"}]}]
}'Python
Java
curl
python
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [{"role": "user",\
"content": [\
# When you provide an image list, the fps parameter applies to the Qwen3.6, Qwen3-VL, and Qwen2.5-VL series models.\
{"video":["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg"],\
"fps":2},\
{"text": "Describe the specific process in this video"}]}]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
model='qwen3.7-plus', # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=messages
)
print(response.output.choices[0].message.content[0]["text"])java
// The DashScope SDK version must be 2.21.10 or later.
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
private static final String MODEL_NAME = "qwen3.7-plus"; // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
public static void videoImageListSample() throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
// When you provide an image list, the fps parameter applies to the Qwen3.6, Qwen3-VL, and Qwen2.5-VL series models.
Map<String, Object> params = new HashMap<>();
params.put("video", Arrays.asList("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg"));
params.put("fps", 2);
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
params,
Collections.singletonMap("text", "Describe the specific process in this video")))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(MODEL_NAME)
.messages(Arrays.asList(userMessage)).build();
MultiModalConversationResult result = conv.call(param);
System.out.print(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
videoImageListSample();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input": {
"messages": [\
{\
"role": "user",\
"content": [\
{\
"video": [\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/xzsgiz/football1.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/tdescd/football2.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/zefdja/football3.jpg",\
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/aedbqh/football4.jpg"\
],\
"fps":2\
\
},\
{\
"text": "Describe the specific process in this video"\
}\
]\
}\
]
}
}'Pass a local file ( Base64 encoding or file path )
Visual understanding models support two methods for uploading local files: Base64 encoding and direct file path upload. Choose based on your file size and SDK:
Conversational or chat history scenarios: Use a public URL. The request size stays small and server-side caching reduces latency.
Offline or private deployment scenarios: Use Base64 encoding or a local file path to avoid server-side download timeouts.
DashScope SDK only: Direct local file path upload is supported.
For a full decision table, see How to choose a file upload method. Both methods must meet the file requirements in Image limitations.
Upload using Base64 encoding
Upload using a file path
Convert the file to a Base64-encoded string and pass it to the model. Suitable for OpenAI and DashScope SDKs, and HTTP requests.
Steps to pass a Base64-encoded string (image example)
- Encode the file: Convert the local image to a Base64-encoded string.
Example code for converting an image to Base64 encoding
python
# Encoding function: Converts a local file to a Base64-encoded string
import base64
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
# Replace xxx/eagle.png with the absolute path of your local image
base64_image = encode_image("xxx/eagle.png")Build a Data URL in the following format:
data:[MIME_type];base64,{base64_image}.Replace
MIME_typewith the actual media type. The value must match aMIME Typelisted in the Supported image formats table, such asimage/jpegorimage/png.base64_imageis the Base64-encoded string generated in the previous step.Invoke the model: Pass the
Data URLin theimageorimage_urlparameter and invoke the model.
Directly pass the local file path to the model. This method is supported only by the DashScope Python and Java SDKs. It is not supported for DashScope HTTP requests or the OpenAI-compatible mode.
Refer to the following table to specify the file path based on your programming language and operating system.
Specify a file path (image example)
| System | SDK | File path to pass | Example |
| Linux or macOS system | Python SDK | file://{absolute_path_of_the_file} | file:///home/images/test.png |
| Java SDK | |||
| Windows system | Python SDK | file://{absolute_path_of_the_file} | file://D:/images/test.png |
| Java SDK | file:///{absolute_path_of_the_file} | file:///D:/images/test.png |
Images
Video files
Image list
Pass using a file path
Passing in Base64-encoded data
Python
Java
python
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Replace xxx/eagle.png with the absolute path of your local image.
local_path = "xxx/eagle.png"
image_path = f"file://{local_path}"
messages = [\
{'role':'user',\
'content': [{'image': image_path},\
{'text': 'What scene is depicted in the image?'}]}]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus', # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=messages)
print(response.output.choices[0].message.content[0]["text"])java
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
public static void callWithLocalFile(String localPath)
throws ApiException, NoApiKeyException, UploadFileException {
String filePath = "file://"+localPath;
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(new HashMap<String, Object>(){{put("image", filePath);}},
new HashMap<String, Object>(){{put("text", "What scene is depicted in the image?");}})).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If the environment variable is not configured, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus") // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));}
public static void main(String[] args) {
try {
// Replace xxx/eagle.png with the absolute path of your local image.
callWithLocalFile("xxx/eagle.png");
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}OpenAI compatible
DashScope
Python
Node.js
curl
python
from openai import OpenAI
import os
import base64
# Encoding function: Converts a local file to a Base64-encoded string.
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
# Replace xxx/eagle.png with the absolute path of your local image.
base64_image = encode_image("xxx/eagle.png")
client = OpenAI(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus", # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=[\
{\
"role": "user",\
"content": [\
{\
"type": "image_url",\
# When passing Base64 image data, note that the image format (image/{format}) must match the Content-Type in the list of supported images. "f" is a string formatting method.\
# PNG image: f"data:image/png;base64,{base64_image}"\
# JPEG image: f"data:image/jpeg;base64,{base64_image}"\
# WEBP image: f"data:image/webp;base64,{base64_image}"\
"image_url": {"url": f"data:image/png;base64,{base64_image}"},\
},\
{"type": "text", "text": "What scene is depicted in the image?"},\
],\
}\
],
)
print(completion.choices[0].message.content)nodejs
import OpenAI from "openai";
import { readFileSync } from 'fs';
const openai = new OpenAI(
{
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If the environment variable is not configured, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
);
const encodeImage = (imagePath) => {
const imageFile = readFileSync(imagePath);
return imageFile.toString('base64');
};
// Replace xxx/eagle.png with the absolute path of your local image.
const base64Image = encodeImage("xxx/eagle.png")
async function main() {
const completion = await openai.chat.completions.create({
model: "qwen3.7-plus", // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages: [\
{"role": "user",\
"content": [{"type": "image_url",\
// Note: When passing Base64 data, the image format (image/{format}) must match the Content-Type in the list of supported images.\
// PNG image: data:image/png;base64,${base64Image}\
// JPEG image: data:image/jpeg;base64,${base64Image}\
// WEBP image: data:image/webp;base64,${base64Image}\
"image_url": {"url": `data:image/png;base64,${base64Image}`},},\
{"type": "text", "text": "What scene is depicted in the image?"}]}]
});
console.log(completion.choices[0].message.content);
}
main();To convert a file to a Base64-encoded string, see the example code.
For demonstration purposes, the Base64-encoded string in the code,
"data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...", is truncated. In practice, you must pass the complete encoded string.
curl
# ======= Important =======
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3.7-plus",
"messages": [\
{\
"role": "user",\
"content": [\
{"type": "image_url", "image_url": {"url": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA"}},\
{"type": "text", "text": "What scene is depicted in the image?"}\
]\
}]
}'Python
Java
curl
python
import base64
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Encoding function: Converts a local file to a Base64-encoded string.
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
# Replace xxxx/eagle.png with the absolute path of your local image.
base64_image = encode_image("xxxx/eagle.png")
messages = [\
{\
"role": "user",\
"content": [\
# Note: When passing Base64 data, the image format (image/{format}) must match the Content-Type in the list of supported images. "f" is a string formatting method.\
# PNG image: f"data:image/png;base64,{base64_image}"\
# JPEG image: f"data:image/jpeg;base64,{base64_image}"\
# WEBP image: f"data:image/webp;base64,{base64_image}"\
{"image": f"data:image/png;base64,{base64_image}"},\
{"text": "What scene is depicted in the image?"},\
],\
},\
]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen3.7-plus", # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=messages,
)
print(response.output.choices[0].message.content[0]["text"])java
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Base64;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.*;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
private static String encodeImageToBase64(String imagePath) throws IOException {
Path path = Paths.get(imagePath);
byte[] imageBytes = Files.readAllBytes(path);
return Base64.getEncoder().encodeToString(imageBytes);
}
public static void callWithLocalFile(String localPath) throws ApiException, NoApiKeyException, UploadFileException, IOException {
String base64Image = encodeImageToBase64(localPath); // Base64 encoding
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
new HashMap<String, Object>() {{ put("image", "data:image/png;base64," + base64Image); }},
new HashMap<String, Object>() {{ put("text", "What scene is depicted in the image?"); }}
)).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
// Replace xxx/eagle.png with the absolute path of your local image.
callWithLocalFile("xxx/eagle.png");
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}To convert a file to a Base64-encoded string, see the example code.
For demonstration purposes, the Base64-encoded string in the code,
"data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...", is truncated. In practice, you must pass the complete encoded string.
curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{\
"role": "user",\
"content": [\
{"image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA..."},\
{"text": "What scene is depicted in the image?"}\
]\
}\
]
}
}'This topic uses a local file named test.mp4 as an example.
Pass the file path
Pass the Base64 encoded string
Python
Java
python
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Replace xxx/test.mp4 with the absolute path of your local video file.
local_path = "xxx/test.mp4"
video_path = f"file://{local_path}"
messages = [\
{'role':'user',\
# The fps parameter controls the number of frames extracted from the video. It extracts one frame every 1/fps seconds.\
'content': [{'video': video_path,"fps":2},\
{'text': 'What scene does this video depict?'}]}]
response = MultiModalConversation.call(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not set, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus',
messages=messages)
print(response.output.choices[0].message.content[0]["text"])java
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
public static void callWithLocalFile(String localPath)
throws ApiException, NoApiKeyException, UploadFileException {
String filePath = "file://"+localPath;
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(new HashMap<String, Object>()
{{
put("video", filePath);// The fps parameter controls the number of frames extracted from the video. It extracts one frame every 1/fps seconds.
put("fps", 2);
}},
new HashMap<String, Object>(){{put("text", "What scene does this video depict?");}})).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If the environment variable is not set, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));}
public static void main(String[] args) {
try {
// Replace xxx/test.mp4 with the absolute path of your local video file.
callWithLocalFile("xxx/test.mp4");
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}OpenAI compatible
DashScope
Python
Node.js
curl
python
from openai import OpenAI
import os
import base64
# Encoding function: Converts a local file to a Base64 encoded string.
def encode_video(video_path):
with open(video_path, "rb") as video_file:
return base64.b64encode(video_file.read()).decode("utf-8")
# Replace xxx/test.mp4 with the absolute path of your local video file.
base64_video = encode_video("xxx/test.mp4")
client = OpenAI(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not set, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus",
messages=[\
{\
"role": "user",\
"content": [\
{\
# When passing a video file directly, set the value of type to video_url.\
"type": "video_url",\
"video_url": {"url": f"data:video/mp4;base64,{base64_video}"},\
"fps":2\
},\
{"type": "text", "text": "What scene does this video depict?"},\
],\
}\
],
)
print(completion.choices[0].message.content)nodejs
import OpenAI from "openai";
import { readFileSync } from 'fs';
const openai = new OpenAI(
{
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If the environment variable is not set, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
);
const encodeVideo = (videoPath) => {
const videoFile = readFileSync(videoPath);
return videoFile.toString('base64');
};
// Replace xxx/test.mp4 with the absolute path of your local video file.
const base64Video = encodeVideo("xxx/test.mp4")
async function main() {
const completion = await openai.chat.completions.create({
model: "qwen3.7-plus",
messages: [\
{"role": "user",\
"content": [{\
// When passing a video file directly, set the value of type to video_url.\
"type": "video_url",\
"video_url": {"url": `data:video/mp4;base64,${base64Video}`},\
"fps":2},\
{"type": "text", "text": "What scene does this video depict?"}]}]
});
console.log(completion.choices[0].message.content);
}
main();To convert a file to a Base64-encoded string, see the sample code.
For demonstration purposes, the Base64-encoded string in the code,
"data:video/mp4;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...", is truncated. In practice, you must pass the complete encoded string.
curl
# ======= Important =======
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen3.7-plus",
"messages": [\
{\
"role": "user",\
"content": [\
{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA..."},"fps":2},\
{"type": "text", "text": "What scene does this video depict?"}\
]\
}]
}'Python
Java
curl
python
import base64
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Encoding function: Converts a local file to a Base64 encoded string.
def encode_video(video_path):
with open(video_path, "rb") as video_file:
return base64.b64encode(video_file.read()).decode("utf-8")
# Replace xxxx/test.mp4 with the absolute path of your local video file.
base64_video = encode_video("xxxx/test.mp4")
messages = [{'role':'user',\
# The fps parameter controls the number of frames extracted from the video. It extracts one frame every 1/fps seconds.\
'content': [{'video': f"data:video/mp4;base64,{base64_video}","fps":2},\
{'text': 'What scene does this video depict?'}]}]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not set, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus',
messages=messages)
print(response.output.choices[0].message.content[0]["text"])java
import java.io.IOException;
import java.util.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.*;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
private static String encodeVideoToBase64(String videoPath) throws IOException {
Path path = Paths.get(videoPath);
byte[] videoBytes = Files.readAllBytes(path);
return Base64.getEncoder().encodeToString(videoBytes);
}
public static void callWithLocalFile(String localPath)
throws ApiException, NoApiKeyException, UploadFileException, IOException {
String base64Video = encodeVideoToBase64(localPath); // Base64 encoding
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(new HashMap<String, Object>()
{{
put("video", "data:video/mp4;base64," + base64Video);// The fps parameter controls the number of frames extracted from the video. It extracts one frame every 1/fps seconds.
put("fps", 2);
}},
new HashMap<String, Object>(){{put("text", "What scene does this video depict?");}})).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If the environment variable is not set, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
// Replace xxx/test.mp4 with the absolute path of your local video file.
callWithLocalFile("xxx/test.mp4");
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}To convert a file to a Base64-encoded string, see the sample code.
For demonstration purposes, the Base64-encoded string in the code,
"data:video/mp4;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...", is truncated. In practice, you must pass the complete encoded string.
curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{\
"role": "user",\
"content": [\
{"video": "data:video/mp4;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA..."},\
{"text": "What scene does this video depict? "}\
]\
}\
]
}
}'This example uses the local files football1.jpg, football2.jpg, football3.jpg, and football4.jpg.
Pass by file path
Base64-encoded input
Python
Java
python
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
local_path1 = "football1.jpg"
local_path2 = "football2.jpg"
local_path3 = "football3.jpg"
local_path4 = "football4.jpg"
image_path1 = f"file://{local_path1}"
image_path2 = f"file://{local_path2}"
image_path3 = f"file://{local_path3}"
image_path4 = f"file://{local_path4}"
messages = [{'role':'user',\
# When you pass an image list, the fps parameter applies to the Qwen3.6, Qwen3-VL, and Qwen2.5-VL series models.\
'content': [{'video': [image_path1,image_path2,image_path3,image_path4],"fps":2},\
{'text': 'What scene does this video depict?'}]}]
response = MultiModalConversation.call(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus', # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=messages)
print(response.output.choices[0].message.content[0]["text"])java
// The DashScope SDK version must be 2.21.10 or later.
import java.util.Arrays;
import java.util.Map;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
private static final String MODEL_NAME = "qwen3.7-plus"; // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
public static void videoImageListSample(String localPath1, String localPath2, String localPath3, String localPath4)
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
String filePath1 = "file://" + localPath1;
String filePath2 = "file://" + localPath2;
String filePath3 = "file://" + localPath3;
String filePath4 = "file://" + localPath4;
Map<String, Object> params = new HashMap<>();
params.put("video", Arrays.asList(filePath1,filePath2,filePath3,filePath4));
// When you pass an image list, the fps parameter applies to the Qwen3.6, Qwen3-VL, and Qwen2.5-VL series models.
params.put("fps", 2);
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(params,
Collections.singletonMap("text", "Describe the specific process in this video")))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model(MODEL_NAME)
.messages(Arrays.asList(userMessage)).build();
MultiModalConversationResult result = conv.call(param);
System.out.print(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
videoImageListSample(
"xxx/football1.jpg",
"xxx/football2.jpg",
"xxx/football3.jpg",
"xxx/football4.jpg");
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}OpenAI compatible
DashScope
Python
Node.js
curl
python
import os
from openai import OpenAI
import base64
# Encoding function: Converts a local file to a Base64-encoded string.
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
base64_image1 = encode_image("football1.jpg")
base64_image2 = encode_image("football2.jpg")
base64_image3 = encode_image("football3.jpg")
base64_image4 = encode_image("football4.jpg")
client = OpenAI(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus", # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=[\
{"role": "user","content": [\
{"type": "video","video": [\
f"data:image/jpeg;base64,{base64_image1}",\
f"data:image/jpeg;base64,{base64_image2}",\
f"data:image/jpeg;base64,{base64_image3}",\
f"data:image/jpeg;base64,{base64_image4}",]},\
{"type": "text","text": "Describe the specific process in this video"},\
]}]
)
print(completion.choices[0].message.content)nodejs
import OpenAI from "openai";
import { readFileSync } from 'fs';
const openai = new OpenAI(
{
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
);
const encodeImage = (imagePath) => {
const imageFile = readFileSync(imagePath);
return imageFile.toString('base64');
};
const base64Image1 = encodeImage("football1.jpg")
const base64Image2 = encodeImage("football2.jpg")
const base64Image3 = encodeImage("football3.jpg")
const base64Image4 = encodeImage("football4.jpg")
async function main() {
const completion = await openai.chat.completions.create({
model: "qwen3.7-plus", // This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages: [\
{"role": "user",\
"content": [{"type": "video",\
"video": [\
`data:image/jpeg;base64,${base64Image1}`,\
`data:image/jpeg;base64,${base64Image2}`,\
`data:image/jpeg;base64,${base64Image3}`,\
`data:image/jpeg;base64,${base64Image4}`]},\
{"type": "text", "text": "What scene does this video depict?"}]}]
});
console.log(completion.choices[0].message.content);
}
main();To convert a file to a Base64-encoded string, see the sample code.
For demonstration purposes, the Base64-encoded string
"data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA..."in the code is truncated. In practice, you must pass the complete encoded string.
curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"messages": [{"role": "user",\
"content": [{"type": "video",\
"video": [\
"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...",\
"data:image/jpeg;base64,nEpp6jpnP57MoWSyOWwrkXMJhHRCWYeFYb...",\
"data:image/jpeg;base64,JHWQnJPc40GwQ7zERAtRMK6iIhnWw4080s...",\
"data:image/jpeg;base64,adB6QOU5HP7dAYBBOg/Fb7KIptlbyEOu58..."\
]},\
{"type": "text",\
"text": "Describe the specific process in this video"}]}]
}'Python
Java
curl
python
import base64
import os
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Encoding function: Converts a local file to a Base64-encoded string.
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
base64_image1 = encode_image("football1.jpg")
base64_image2 = encode_image("football2.jpg")
base64_image3 = encode_image("football3.jpg")
base64_image4 = encode_image("football4.jpg")
messages = [{'role':'user',\
'content': [\
{'video':\
[f"data:image/jpeg;base64,{base64_image1}",\
f"data:image/jpeg;base64,{base64_image2}",\
f"data:image/jpeg;base64,{base64_image3}",\
f"data:image/jpeg;base64,{base64_image4}"\
]\
},\
{'text': 'Describe the specific process in this video.'}]}]
response = dashscope.MultiModalConversation.call(
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
model='qwen3.7-plus', # This example uses qwen3.7-plus. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
messages=messages)
print(response.output.choices[0].message.content[0]["text"])java
import java.io.IOException;
import java.util.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.*;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
private static String encodeImageToBase64(String imagePath) throws IOException {
Path path = Paths.get(imagePath);
byte[] imageBytes = Files.readAllBytes(path);
return Base64.getEncoder().encodeToString(imageBytes);
}
public static void videoImageListSample(String localPath1,String localPath2,String localPath3,String localPath4)
throws ApiException, NoApiKeyException, UploadFileException, IOException {
String base64Image1 = encodeImageToBase64(localPath1); // Base64 encoding
String base64Image2 = encodeImageToBase64(localPath2);
String base64Image3 = encodeImageToBase64(localPath3);
String base64Image4 = encodeImageToBase64(localPath4);
MultiModalConversation conv = new MultiModalConversation();
Map<String, Object> params = new HashMap<>();
params.put("video", Arrays.asList(
"data:image/jpeg;base64," + base64Image1,
"data:image/jpeg;base64," + base64Image2,
"data:image/jpeg;base64," + base64Image3,
"data:image/jpeg;base64," + base64Image4));
// When you pass an image list, the fps parameter applies to the Qwen3.6, Qwen3-VL, and Qwen2.5-VL series models.
params.put("fps", 2);
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(params,
Collections.singletonMap("text", "Describe the specific process in this video")))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.messages(Arrays.asList(userMessage))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
}
public static void main(String[] args) {
try {
// Replace xxx/football1.png and other placeholders with the absolute paths of your local images.
videoImageListSample(
"xxx/football1.jpg",
"xxx/football2.jpg",
"xxx/football3.jpg",
"xxx/football4.jpg"
);
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}To convert a file to a Base64-encoded string, see the sample code.
For demonstration purposes, the Base64-encoded string
"data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA..."in the code is truncated. In practice, you must pass the complete encoded string.
curl
# ======= Important =======
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input": {
"messages": [\
{\
"role": "user",\
"content": [\
{\
"video": [\
"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...",\
"data:image/jpeg;base64,nEpp6jpnP57MoWSyOWwrkXMJhHRCWYeFYb...",\
"data:image/jpeg;base64,JHWQnJPc40GwQ7zERAtRMK6iIhnWw4080s...",\
"data:image/jpeg;base64,adB6QOU5HP7dAYBBOg/Fb7KIptlbyEOu58..."\
],\
"fps":2\
},\
{\
"text": "Describe the specific process in this video"\
}\
]\
}\
]
}
}'Processing high-resolution images
The API limits visual tokens per image. With default settings, high-resolution images are compressed and fine details can be lost. Use vl_high_resolution_images or adjust max_pixels to retain more detail.
View the pixels per visual token, token limit, and pixel limit for each model
If the input image resolution exceeds the model's pixel limit, the image is scaled down to fit within the limit.
| Model | Pixels per token | vl_high_resolution_images | max_pixels | Token limit | Pixel limit |
Qwen3.6 and Qwen3-VL series models | 32*32 | true | max_pixels is invalid | 16384 tokens | 16777216 (which is 16384×32×32) |
false (default) | Customizable. The default is 2621440, and the maximum is 16777216. | Determined by max_pixels, which is max_pixels/32/32 | max_pixels | ||
qwen-vl-max, qwen-vl-max-latest, qwen-vl-max-2025-08-13, qwen-vl-plus, qwen-vl-plus-latest, qwen-vl-plus-2025-08-15, and models | 32*32 | true | max_pixels is invalid | 16384 tokens | 16777216 (which is 163843232) |
false (default) | Customizable. The default is 1310720, and the maximum is 16777216. | Determined by max_pixels, which is max_pixels/32/32 | max_pixels | ||
Other qwen-vl-max, other qwen-vl-plus, Qwen2.5-VL open source series, and QVQ series models | 28*28 | true | max_pixels is invalid | 16384 tokens | 12845056 (which is 163842828) |
false (default) | Customizable. The default is 1003520, and the maximum is 12845056. | Determined by max_pixels, which is max_pixels/28/28 | max_pixels |
When
vl_high_resolution_images=true, the API applies a fixed high-resolution policy and ignoresmax_pixels. Use this when you need to detect fine text, small objects, or rich visual detail.When
vl_high_resolution_images=false, the pixel limit is controlled bymax_pixels.For high processing speed or cost-sensitive scenarios: use the default
max_pixelsvalue or set it smaller.To prioritize detail over processing speed: increase
max_pixels.
OpenAI compatibility
DashScope
vl_high_resolution_images is not a standard OpenAI parameter. Pass it as follows:
Python SDK: pass through the
extra_bodydictionary.Node.js SDK: pass as a top-level parameter.
Python
Node.js
curl
python
import os
import time
from openai import OpenAI
client = OpenAI(
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.7-plus",
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 specifies the maximum pixel threshold for the input image. It is invalid when vl_high_resolution_images=True. When vl_high_resolution_images=False, it is customizable, and the maximum value varies by model.\
# "max_pixels": 16384 * 32 * 32\
},\
{"type": "text", "text": "What festival atmosphere does this picture show"},\
],\
}\
],
extra_body={"vl_high_resolution_images":True}
)
print(f"Model output: {completion.choices[0].message.content}")
print(f"Total input tokens: {completion.usage.prompt_tokens}")nodejs
import OpenAI from "openai";
const openai = new OpenAI(
{
// API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
}
);
const response = await openai.chat.completions.create({
model: "qwen3.7-plus",
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 specifies the maximum pixel threshold for the input image. It has no effect when vl_high_resolution_images=True. When vl_high_resolution_images=False, it is customizable, and the maximum value varies by model.\
// "max_pixels": 2560 * 32 * 32\
},\
{type: "text", text: "What festival atmosphere does this picture show?" },\
]}],
vl_high_resolution_images:true
})
console.log("Model output: ",response.choices[0].message.content);
console.log("Total input tokens",response.usage.prompt_tokens);curl
# ======= Important notes =======
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"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"\
}\
},\
{\
"type": "text",\
"text": "What festival atmosphere does this picture show?"\
}\
]\
}\
],
"vl_high_resolution_images":true
}'Python
Java
curl
python
import os
import time
import dashscope
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [\
{\
"role": "user",\
"content": [\
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250212/earbrt/vcg_VCG211286867973_RF.jpg",\
# max_pixels specifies the maximum pixel threshold for the input image. It is invalid when vl_high_resolution_images=True. When vl_high_resolution_images=False, it is customizable, and the maximum value varies by model.\
# "max_pixels": 16384 * 32 * 32\
},\
{"text": "What festival atmosphere does this picture show?"}\
]\
}\
]
response = dashscope.MultiModalConversation.call(
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv('DASHSCOPE_API_KEY'),
model='qwen3.7-plus',
messages=messages,
vl_high_resolution_images=True
)
print("Model output",response.output.choices[0].message.content[0]["text"])
print("Total input tokens:",response.usage.input_tokens)java
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
import java.util.HashMap;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
Map<String, Object> map = new HashMap<>();
map.put("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250212/earbrt/vcg_VCG211286867973_RF.jpg");
// max_pixels specifies the maximum pixel threshold for the input image. It is invalid when vl_high_resolution_images=True. When vl_high_resolution_images=False, it is customizable, and the maximum value varies by model.
// map.put("max_pixels", 2621440);
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
map,
Collections.singletonMap("text", "What festival atmosphere does this picture show?"))).build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
// If you have not configured the environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3.7-plus")
.message(userMessage)
.vlHighResolutionImages(true)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
System.out.println(result.getUsage().getInputTokens());
}
public static void main(String[] args) {
try {
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}curl
# ======= Important notes =======
# API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
# === Delete this comment before execution ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3.7-plus",
"input":{
"messages":[\
{\
"role": "user",\
"content": [\
{"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250212/earbrt/vcg_VCG211286867973_RF.jpg"},\
{"text": "What festival atmosphere does this picture show?"}\
]\
}\
]
},
"parameters": {
"vl_high_resolution_images": true
}
}'More examples
Multi-turn conversation
Streaming output
Limitations
Input file limits
Image limits
Video limits
Image resolution
Minimum size: Both width and height must exceed
10pixels.Aspect ratio: The ratio of the long side to the short side must not exceed
200:1for both the original and scaled images.For the image scaling logic, see the
smart_resizefunction in Calculate image tokensPixel limit:
Keep the image resolution within
8K (7680x4320). Higher resolutions can cause API timeouts due to large file sizes and long transfer times.The model scales images automatically using
max_pixelsandmin_pixels, so ultra-high resolution does not improve accuracy and increases the risk of failed calls. Scale images to a reasonable size on the client side before calling the API.
Supported image formats
For resolutions below 4K
(3840x2160), the following image formats are supported:Image format Common extensions 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 For resolutions between
4K (3840x2160)and8K (7680x4320), only the JPEG, JPG, and PNG formats are supported.
Image size:
When passed as a public URL: A single image cannot exceed
20 MBfor Qwen3.7 series, Qwen3.6 series, and Qwen3.5 series models. For other models, a single image cannot exceed10 MB.When passed as a local path: A single image cannot exceed
10 MB.When passed as a Base64-encoded string: The encoded string cannot exceed
10 MB.
To compress a file, see How to compress an image or video to meet the size limit .
- Image count limit: For multi-image inputs, the maximum number of supported images varies based on the input method:
- When passed as public URLs or local paths:
Qwen3.7 series: Up to 2048 images.
Other models: Up to 256 images.
- When passed as Base64-encoded strings: Up to 250 images.
- When passed as public URLs or local paths:
The total number of tokens for all images is also limited by the model's maximum input token limit. The total token count must be less than the model's maximum input limit.
- When passed as an image list, the number of images in the list is limited as follows:
qwen3.6series andqwen3.5series: A minimum of 4 images and a maximum of 8,000 images.qwen3-vl-plusseries,qwen3-vl-flashseries,qwen3-vl-235b-a22b-thinking, andqwen3-vl-235b-a22b-instruct: A minimum of 4 images and a maximum of 2,000 images.Other open source
Qwen3-VL,Qwen2.5-VL(including commercial and open source versions), andQVQseries models: A minimum of 4 images and a maximum of 512 images.Other models: A minimum of 4 images and a maximum of 80 images.
- When passed as a video file:
Video size:
When passed as a public URL:
qwen3.6series,qwen3.5series,Qwen3-VLseries, andqwen-vl-max(includingqwen-vl-max-latest,qwen-vl-max-2025-04-08, and all later versions): Up to 2 GB.qwen-vl-plusseries, otherqwen-vl-maxmodels, open sourceQwen2.5-VLseries, andQVQseries models: Up to 1 GB.Other models: Up to 150 MB.
When passed as a Base64-encoded string: The encoded string must be less than 10 MB.
When passed as a local file path: The video file cannot exceed 100 MB.
To compress a file, see How to compress an image or video to meet the size limit .
Video duration:
qwen3.6series andqwen3.5series: 2 seconds to 2 hours.qwen3-vl-plusseries,qwen3-vl-flashseries,qwen3-vl-235b-a22b-thinking, andqwen3-vl-235b-a22b-instruct: 2 seconds to 1 hour.Other open source
Qwen3-VLseries andqwen-vl-max(includingqwen-vl-max-latest,qwen-vl-max-2025-04-08, and later updated versions): 2 seconds to 20 minutes.qwen-vl-plusseries, otherqwen-vl-maxmodels, open sourceQwen2.5-VLseries, andQVQseries models: 2 seconds to 10 minutes.Other models: 2 seconds to 40 seconds.
Video format: MP4, AVI, MKV, MOV, FLV, WMV, and more.
Video dimensions: No specific limits. The model can automatically adjust video dimensions using
max_pixelsandmin_pixels. Larger video files do not result in better understanding.Video count limit: Up to 64 videos can be passed.
Audio understanding: Audio understanding for video files is not supported.
File input methods
- Public URL: Provide an HTTP or HTTPS URL that the API can download. For the best stability and performance, upload the file to OSS to get a public URL.
Important
The response header of the public URL must include Content-Length (file size) and Content-Type (media type, such as image/jpeg). If either field is missing or incorrect, the download fails.
Base64 encoding: Convert the file to a Base64-encoded string before passing it. Suitable for all SDK types and HTTP. Note that Base64 encoding increases data size by ~33%, so the original file must be under 7 MB to stay within the 10 MB encoded limit.
Local file path (DashScope SDK only): Pass the path to a local file directly. Files must not exceed 10 MB.
For recommendations on how to choose a file upload method, see How to choose a file upload method?
Going live
Image and video pre-processing: Visual understanding models have input file size limits. To compress files, see image or video compression methods.
Processing text files: Visual understanding models only support image files and cannot process text files directly. Workarounds:
Convert the text file to an image format. Use an image editing library, such as Python's pdf2image, to convert the file into multiple high-quality images, one per page. Then pass the images to the model using the multi-image input method.
Qwen-Long supports processing text files and can be used to parse file content.
Fault tolerance and stability
Timeout handling: In non-streaming calls, a timeout error occurs if the model does not complete output within 300 seconds. After a timeout, the generated content is returned in the response body. Check for the
x-dashscope-partialresponse: trueresponse header to detect timeouts. To continue generation, use the partial mode feature (supported by select models): add the generated content to the messages array and resend the request. See Continue from incomplete output.Retry mechanism: Implement retry logic, such as exponential backoff, for API calls to handle network fluctuations or temporary service unavailability.
Billing and rate limiting
- Billing: The total cost is calculated from the total number of input and output tokens. For prices, see the Model Studio console.
Token composition: Input tokens include text tokens and tokens converted from images or videos. Output tokens are the text generated by the model. In thinking mode, the reasoning chain also counts as output tokens. If the reasoning chain is suppressed, billing uses the non-thinking mode price.
Calculate tokens for images and videos: Use the following code to calculate token consumption for an image or video. The estimate is for reference only. Actual usage is subject to the API response.
Calculate tokens for images and videos
Images
Videos
Formula:
Image Tokens = h_bar * w_bar / token_pixels + 2h_bar, w_bar: The height and width of the scaled image. The model scales images to a pixel limit based onmax_pixelsandvl_high_resolution_images. See Process high-resolution images.token_pixels: The pixel value corresponding to each visualToken. This varies by model:qwen3.7 series,qwen3.6 series,qwen3.5 series,Qwen3-VL,qwen-vl-max,qwen-vl-max-latest,qwen-vl-max-2025-08-13,qwen-vl-plus,qwen-vl-plus-latest,qwen-vl-plus-2025-08-15: EachTokencorresponds to32x32pixels.QVQand otherQwen2.5-VLmodels: Each Token corresponds to28x28pixels.
The following code demonstrates the approximate image scaling logic used by the model. Use it to estimate token consumption. Actual billing is subject to the API response.
Example: A 4000×3000 image passed to a qwen3.7-plus model (token_pixels = 32×32 = 1024). With default max_pixels (2621440), the model scales the image down. After scaling, the adjusted dimensions are 1376×1856. Token count = (1376 × 1856) / 1024 + 2 = 2494 + 2 = 2496 tokens. Use the code below to calculate the exact scaled dimensions for your image.
python
import math
from PIL import Image # pip install Pillow
def smart_size(image_path, max_pixels, vl_high_resolution_images):
"""Calculates the scaled dimensions of an image based on model parameters to estimate image tokens."""
image = Image.open(image_path)
height, width = image.height, image.width
# The zoom factor is 32 for models such as Qwen3.6, Qwen3.5, and Qwen3-VL. For other models, it is 28.
factor = 32
h_bar = round(height / factor) * factor
w_bar = round(width / factor) * factor
# Token lower limit: 4 tokens
min_pixels = 4 * factor * factor
# When vl_high_resolution_images=True, the token upper limit is fixed at 16384, and max_pixels is ignored.
if vl_high_resolution_images:
max_pixels = 16384 * factor * factor
# Constrain the total number of pixels to the range of [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__":
# Note: The values of max_pixels and vl_high_resolution_images must be consistent with the parameters passed when calling the model.
h_bar, w_bar = smart_size("xxx/test.jpg", max_pixels=2560 * 32 * 32, vl_high_resolution_images=False)
print(f"Scaled image dimensions: height {h_bar}, width {w_bar}")
# Each image includes one <vision_bos> token and one <vision_eos> token.
token = int(h_bar * w_bar / (32 * 32)) + 2
print(f"Number of image tokens: {token}")- **Video files:**
When processing a video file, the model first extracts frames and then calculates the total number of tokens for all video frames. Because this calculation is complex, you can use the following code to estimate the total token consumption for a video by passing its path:
```python
# Before use, install with: pip install opencv-python
import math
import os
import logging
import cv2
logger = logging.getLogger(__name__)
FRAME_FACTOR = 2
# For models such as Qwen3.6, Qwen3.5, Qwen3-VL, qwen-vl-max-0813, qwen-vl-plus-0815, and qwen-vl-plus-0710, the image zoom factor is 32.
IMAGE_FACTOR = 32
# For other models, the image zoom factor is 28.
# IMAGE_FACTOR = 28
# Maximum aspect ratio for video frames
MAX_RATIO = 200
# Minimum pixel count for video frames
VIDEO_MIN_PIXELS = 4 * 32 * 32
# Maximum pixel count for video frames. For the Qwen3-VL-Plus model, VIDEO_MAX_PIXELS is 640 * 32 * 32. For other models, it is 768 * 32 * 32.
VIDEO_MAX_PIXELS = 640 * 32 * 32
# If the user does not pass the FPS parameter, the default value is used.
FPS = 2.0
# Minimum number of extracted frames
FPS_MIN_FRAMES = 4
# Maximum number of extracted frames (default: 2000 for Qwen3-VL-Plus, 512 for Qwen3-VL-Flash/Qwen2.5-VL, 80 for others)
FPS_MAX_FRAMES = 2000
# Maximum pixel value for video input (default: 131072*32*32 for Qwen3-VL-Plus, 65536*32*32 for others)
VIDEO_TOTAL_PIXELS = int(float(os.environ.get('VIDEO_MAX_PIXELS', 131072 * 32 * 32)))
def round_by_factor(number: int, factor: int) -> int:
"""Returns the integer closest to 'number' that is divisible by 'factor'."""
return round(number / factor) * factor
def ceil_by_factor(number: int, factor: int) -> int:
"""Returns the smallest integer greater than or equal to 'number' that is divisible by 'factor'."""
return math.ceil(number / factor) * factor
def floor_by_factor(number: int, factor: int) -> int:
"""Returns the largest integer less than or equal to 'number' that is divisible by 'factor'."""
return math.floor(number / factor) * factor
def extract_vision_info(conversations):
vision_infos = []
if isinstance(conversations[0], dict):
conversations = [conversations]
for conversation in conversations:
for message in conversation:
if isinstance(message["content"], list):
for ele in message["content"]:
if (
"image" in ele
or "image_url" in ele
or "video" in ele
or ele.get("type","") in ("image", "image_url", "video")
):
vision_infos.append(ele)
return vision_infos
def smart_nframes(ele,total_frames,video_fps):
"""Calculates the number of extracted video frames.
Args:
ele (dict): A dictionary containing video configuration.
- fps: Controls the number of frames extracted for model input.
total_frames (int): The original total number of frames in the video.
video_fps (int | float): The original frame rate of the video.
Raises:
An error is raised if nframes is not within the interval [FRAME_FACTOR, total_frames].
Returns:
The number of video frames for model input.
"""
assert not ("fps" in ele and "nframes" in ele), "Only accept either `fps` or `nframes`"
fps = ele.get("fps", FPS)
min_frames = ceil_by_factor(ele.get("min_frames", FPS_MIN_FRAMES), FRAME_FACTOR)
max_frames = floor_by_factor(ele.get("max_frames", min(FPS_MAX_FRAMES, total_frames)), FRAME_FACTOR)
duration = total_frames / video_fps if video_fps != 0 else 0
if duration-int(duration)>(1/fps):
total_frames = math.ceil(duration * video_fps)
else:
total_frames = math.ceil(int(duration)*video_fps)
nframes = total_frames / video_fps * fps
if nframes > total_frames:
logger.warning(f"smart_nframes: nframes[{nframes}] > total_frames[{total_frames}]")
nframes = int(min(min(max(nframes, min_frames), max_frames), total_frames))
if not (FRAME_FACTOR <= nframes and nframes <= total_frames):
raise ValueError(f"nframes should in interval [{FRAME_FACTOR}, {total_frames}], but got {nframes}.")
return nframes
def get_video(video_path): # Get video information cap = cv2.VideoCapture(video_path)
frame_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
# Get video height
frame_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
video_fps = cap.get(cv2.CAP_PROP_FPS)
return frame_height, frame_width, total_frames, video_fps
def smart_resize(ele, path, factor=IMAGE_FACTOR): # Get the original video's width and height height, width, total_frames, video_fps = get_video(path) # Token lower limit for video frames min_pixels = VIDEO_MIN_PIXELS total_pixels = VIDEO_TOTAL_PIXELS # Number of extracted video frames nframes = smart_nframes(ele, total_frames, video_fps) max_pixels = max(min(VIDEO_MAX_PIXELS, total_pixels / nframes * FRAME_FACTOR),int(min_pixels * 1.05))
# The aspect ratio of the video should not exceed 200:1 or 1:200.
if max(height, width) / min(height, width) > MAX_RATIO:
raise ValueError(
f"absolute aspect ratio must be smaller than {MAX_RATIO}, got {max(height, width) / min(height, width)}"
)
h_bar = max(factor, round_by_factor(height, factor))
w_bar = max(factor, round_by_factor(width, factor))
if h_bar * w_bar > max_pixels:
beta = math.sqrt((height * width) / max_pixels)
h_bar = floor_by_factor(height / beta, factor)
w_bar = floor_by_factor(width / beta, factor)
elif h_bar * w_bar < min_pixels:
beta = math.sqrt(min_pixels / (height * width))
h_bar = ceil_by_factor(height * beta, factor)
w_bar = ceil_by_factor(width * beta, factor)
return h_bar, w_bar
def token_calculate(video_path, fps): # Pass the video path and fps frame extraction parameter messages = [{"content": [{"video": video_path, "fps": fps}]}] vision_infos = extract_vision_info(messages)[0]
resized_height, resized_width = smart_resize(vision_infos, video_path)
height, width, total_frames, video_fps = get_video(video_path)
num_frames = smart_nframes(vision_infos, total_frames, video_fps)
print(f"Original video dimensions: {height}*{width}, model input dimensions: {resized_height}*{resized_width}, total video frames: {total_frames}, total frames extracted when fps is {fps}: {num_frames}", end=", ")
video_token = int(math.ceil(num_frames / 2) * resized_height / 32 * resized_width / 32)
video_token += 2 # The system automatically adds <|vision_bos|> and <|vision_eos|> visual markers (1 token each).
return video_token
video_token = token_calculate("xxx/test.mp4", 1) print("Video tokens:", video_token)
- **Image list:**
When a video is passed as a list of images, it means that frame extraction has already been completed. You can use the following code to calculate the token consumption by passing the path and number of images:
```python
# Before use, install with: pip install Pillow
import math
import os
import logging
from typing import Tuple
from PIL import Image
logger = logging.getLogger(__name__)
# ==================== Constant Definitions ====================
FRAME_FACTOR = 2
# For models like Qwen3-VL, qwen-vl-max-0813, qwen-vl-plus-0815, and qwen-vl-plus-0710, the zoom factor is 32.
IMAGE_FACTOR = 32
# For other models, the zoom factor is 28.
# IMAGE_FACTOR = 28
# Constants for token calculation
TOKEN_DIVISOR = 32 # Divisor for token calculation
VISION_SPECIAL_TOKENS = 2 # <|vision_bos|> and <|vision_eos|> markers
# Maximum aspect ratio for video frames
MAX_RATIO = 200
# Minimum pixel count for video frames
VIDEO_MIN_PIXELS = 4 * 32 * 32
# Maximum pixel count for video frames. For the Qwen3-VL-Plus model, VIDEO_MAX_PIXELS is 640 * 32 * 32. For other models, it is 768 * 32 * 32.
VIDEO_MAX_PIXELS = 640 * 32 * 32
# Maximum pixel value for video input (default: 131072*32*32 for Qwen3-VL-Plus, 65536*32*32 for others)
VIDEO_TOTAL_PIXELS = int(float(os.environ.get('VIDEO_MAX_PIXELS', 131072 * 32 * 32)))
def round_by_factor(number: int, factor: int) -> int:
"""Returns the integer closest to 'number' that is divisible by 'factor'."""
return round(number / factor) * factor
def ceil_by_factor(number: int, factor: int) -> int:
"""Returns the smallest integer greater than or equal to 'number' that is divisible by 'factor'."""
return math.ceil(number / factor) * factor
def floor_by_factor(number: int, factor: int) -> int:
"""Returns the largest integer less than or equal to 'number' that is divisible by 'factor'."""
return math.floor(number / factor) * factor
def get_image_size(image_path: str) -> Tuple[int, int]:
if not os.path.exists(image_path):
raise FileNotFoundError(f"Image file not found: {image_path}")
try:
image = Image.open(image_path)
height = image.height
width = image.width
image.close() # Close the file promptly
return height, width
except Exception as e:
raise ValueError(f"Cannot read image file {image_path}: {str(e)}")
def smart_resize(height: int, width: int, nframes: int, factor: int = IMAGE_FACTOR) -> Tuple[int, int]:
"""
Calculates the scaled dimensions of an image.
Args:
height: Original image height
width: Original image width
nframes: Number of video frames
factor: Zoom factor, defaults to IMAGE_FACTOR
Returns:
(resized_height, resized_width) Scaled height and width
Raises:
ValueError: Aspect ratio exceeds the limit
"""
# Token lower limit for video frames
min_pixels = VIDEO_MIN_PIXELS
total_pixels = VIDEO_TOTAL_PIXELS
# Number of extracted video frames
max_pixels = max(min(VIDEO_MAX_PIXELS, total_pixels / nframes * FRAME_FACTOR), int(min_pixels * 1.05))
# The aspect ratio of the video should not exceed 200:1 or 1:200.
aspect_ratio = max(height, width) / min(height, width)
if aspect_ratio > MAX_RATIO:
raise ValueError(
f"Image aspect ratio must be less than {MAX_RATIO}:1, current is {aspect_ratio:.2f}:1"
)
h_bar = max(factor, round_by_factor(height, factor))
w_bar = max(factor, round_by_factor(width, factor))
if h_bar * w_bar > max_pixels:
beta = math.sqrt((height * width) / max_pixels)
h_bar = floor_by_factor(height / beta, factor)
w_bar = floor_by_factor(width / beta, factor)
elif h_bar * w_bar < min_pixels:
beta = math.sqrt(min_pixels / (height * width))
h_bar = ceil_by_factor(height * beta, factor)
w_bar = ceil_by_factor(width * beta, factor)
return h_bar, w_bar
def calculate_video_tokens(image_path: str, nframes: int = 1, factor: int = IMAGE_FACTOR, verbose: bool = True) -> int:
"""
Args:
image_path: Path to the video frame file
nframes: Number of video frames,
factor: Zoom factor, defaults to IMAGE_FACTOR
verbose: Whether to print detailed information
Returns:
The number of tokens consumed
Raises:
FileNotFoundError: File does not exist
ValueError: Invalid file format or aspect ratio out of bounds
"""
# Get original image dimensions (read only once)
height, width = get_image_size(image_path)
# Calculate scaled dimensions
resized_height, resized_width = smart_resize(height, width, nframes, factor)
# Calculate the number of tokens
# Formula: ceil(frames/2) * (height/TOKEN_DIVISOR) * (width/TOKEN_DIVISOR) + VISION_SPECIAL_TOKENS
video_token = int(
math.ceil(nframes / 2) *
(resized_height / TOKEN_DIVISOR) *
(resized_width / TOKEN_DIVISOR)
)
# Add visual marker tokens (<|vision_bos|> and <|vision_eos|>)
video_token += VISION_SPECIAL_TOKENS
if verbose:
print(f"Original video frame dimensions: {height}×{width}, model input dimensions: {resized_height}×{resized_width}, ", end="")
return video_token
if __name__ == "__main__":
try:
video_token = calculate_video_tokens("xxx/test.jpg", nframes=30)
print(f"Video tokens: {video_token}\n")
except Exception as e:
print(f"Error: {str(e)}\n")
```
- **View bills:** View bills or top up your account on the Expenses and Costs page of the Alibaba Cloud Management Console.
- **Rate limiting:** For rate limits for visual understanding models, see Rate limits.
- **Free quota** (Singapore region only): A free quota of 1 million tokens is provided for visual understanding models, valid for 90 days from the date you enable Model Studio or your model request is approved.
## API reference
For input and output parameters of the visual understanding model, see Text generation.
## **FAQ**
### How to choose a file upload method
Choose an upload method based on SDK type, file size, and network stability.
| | | | |
| --- | --- | --- | --- |
| **File type** | **File specifications** | **DashScope SDK (Python, Java)** | **OpenAI-compatible / DashScope HTTP** |
| Image | Greater than 7 MB and less than 10 MB | Pass the local path | Only public URLs are supported. Use Alibaba Cloud Object Storage Service. |
| Less than 7 MB | Pass the local path | Base64 encoding |
| Video | Greater than 100 MB | Only public URLs are supported. Use Alibaba Cloud Object Storage Service. | Only public URLs are supported. Use Alibaba Cloud Object Storage Service. |
| Greater than 7 MB and less than 100 MB | Pass the local path | Only public URLs are supported. Use Alibaba Cloud Object Storage Service. |
| Less than 7 MB | Pass the local path | Base64 encoding |
> Base64 encoding increases the data size. The original file must be smaller than 7 MB.
> Use Base64 or a local path to prevent server-side download timeouts and improve stability.
### How to compress an image or video to meet the size limit
Visual understanding models have input file size limits. Use the following methods to compress your files.
**Image compression methods**
- Online tools: Use an online tool such as CompressJPEG to compress the image.
- Local software: Use software such as Photoshop to adjust the quality when exporting the image.
- Code implementation:
```python
# 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)
# Pass a local image
compress_image("/xxx/before-large.jpeg","/xxx/after-min.jpeg")Video compression methods
Online tools: Use an online tool such as FreeConvert to compress the video.
Local software: Use software such as HandBrake.
Code implementation: Use the FFmpeg tool. See the official FFmpeg website.
bash
# Basic transform command
# -i: Specifies the path of the input file. Example: input.mp4
# -vcodec: Specifies the video encoder. Common values include libx264 (recommended for general use) and libx265 (higher compression ratio).
# -crf: Controls the video quality. The value ranges from 18 to 28. A smaller value indicates higher quality and a larger file size.
# --preset: Controls the balance between encoding speed and compression efficiency. Common values include slow, fast, and faster.
# -y: Overwrites the output file if it already exists. No value is required.
# output.mp4: Specifies the path of the output file.
ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset slow output.mp4How to draw detection frames on the original image after object detection
After the model outputs object locations, use the following code to draw detection frames and labels on the original image.
Qwen2.5-VL: Returns coordinates as absolute pixel values relative to the top-left corner of the scaled image. To draw detection frames, see the code in qwen2_5_vl_2d.py.
Qwen3-VL: Returns relative coordinates with values normalized to the range of
[0, 999]. To draw detection frames, see the code in qwen3_vl_2d.py (2D localization) or qwen3_vl_3d.zip (3D localization).
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
Previous: Visual understandingNext: Text extraction (Qwen-OCR)
Is this page helpful?
Getting started
Select a model
Model capabilities
Image Q&A
Creative writing
Text recognition and information extraction
Multidisciplinary problem-solving
Visual programming
Object detection
Document parsing
Video understanding
Key features
Enable or disable thinking mode
Multiple image input
Video understanding
Pass a local file (Base64 encoding or file path)
Processing high-resolution images
More examples
Limitations
Input file limits
File input methods
Going live
Billing and rate limiting
API reference
FAQ
How to choose a file upload method
How to compress an image or video to meet the size limit
How to draw detection frames on the original image after object detection
Error codes
Contact Us
Sales Support
Live-chat with our sales team or get in touch with a business development professional in your region.
Contact Sales
Technical Support
Open a ticket and get quick help from our technical team.
Open a Ticket >
Connect & Report Abuse
We look forward to your suggestion.
Post a Suggestion > Report Abuse >
\ \ Hi, I'm Alibaba Cloud AI Assistant!\ \ I can help with questions and solutions.
Why Alibaba Cloud
About Alibaba Cloud
Asia Accelerator
Our Global Network
Global Offices
Trust Center
Case Studies
Analyst Reports
Products & Pricings
Pricing Calculator
ECS
SAS
Model Studio
Database
Security
SMS
Solutions
Financial Services
Retail Services
Media Services
Gaming Services
ISV Solutions
Engage
Developer Community
Partner Network
Startups
Marketplace
Join Alibaba Cloud
Resources & Support
Developer Learning Hub
Documentation Center
Training & Certification
Service Notices
Submit a Ticket
Security Report
Qwen Cloud
Careers About Us Privacy Policy Legal Integrity Compliance Reporting Channel Service Notices Links
© 2009-2026 Copyright by Alibaba Cloud All rights reserved
- YouTube
- TikTok
- contact.us@alibabacloud.com
- Call Us Now
- Discord
© 2009-2026 Copyright by Alibaba Cloud All rights reserved
Careers About Us Privacy Policy Legal Integrity Compliance Reporting Channel Service Notices Links