Skip to main content

​
Overview

For production use without managing infrastructure, you can access Qwen3-VL through the DashScope API service. The API is fully compatible with the OpenAI client library, making integration seamless.

​
Getting Started

​
1. Get Your API Key

Obtain your DashScope API key from Aliyun Model Studio.

​
2. Install OpenAI Client

pip install openai

​
Using the API

Here’s a complete example of using the DashScope API with the OpenAI client: 
from openai import OpenAI

# Set your DASHSCOPE_API_KEY here
DASHSCOPE_API_KEY = "your-api-key-here"

client = OpenAI(
    api_key=DASHSCOPE_API_KEY,
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3-vl-235b-a22b-instruct",
    messages=[{"role": "user", "content": [
        {"type": "image_url",
         "image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},
        {"type": "text", "text": "这是什么"},
    ]}]
)
print(completion.model_dump_json())

​
API Configuration

​
Client Setup

When initializing the OpenAI client for DashScope: 
client = OpenAI(
    api_key=DASHSCOPE_API_KEY,  # Your DashScope API key
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DashScope endpoint
)

​
Available Models

The following Qwen3-VL models are available through the API:
  • qwen3-vl-235b-a22b-instruct: Large-scale instruction-tuned model
  • Other model variants (check the official documentation for the full list)

​
Multimodal Input

​
Image Input

Provide images via URL: 
messages = [{
    "role": "user",
    "content": [
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/image.jpg"}
        },
        {
            "type": "text",
            "text": "Describe this image."
        }
    ]
}]

completion = client.chat.completions.create(
    model="qwen3-vl-235b-a22b-instruct",
    messages=messages
)

​
Video Input

Provide videos via URL: 
messages = [{
    "role": "user",
    "content": [
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/video.mp4"}
        },
        {
            "type": "text",
            "text": "What happens in this video?"
        }
    ]
}]

completion = client.chat.completions.create(
    model="qwen3-vl-235b-a22b-instruct",
    messages=messages
)

​
Multiple Images

Include multiple images in a single request: 
messages = [{
    "role": "user",
    "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}},
        {"type": "text", "text": "Compare these two images."}
    ]
}]

​
Response Format

The API returns responses in the standard OpenAI format: 
completion = client.chat.completions.create(
    model="qwen3-vl-235b-a22b-instruct",
    messages=messages
)

# Access the response
response_text = completion.choices[0].message.content
print(response_text)

# Get full response as JSON
print(completion.model_dump_json())

​
Advanced Parameters

Customize generation with additional parameters: 
completion = client.chat.completions.create(
    model="qwen3-vl-235b-a22b-instruct",
    messages=messages,
    max_tokens=2048,          # Maximum tokens to generate
    temperature=0.7,          # Sampling temperature (0.0-1.0)
    top_p=0.8,               # Nucleus sampling parameter
    stream=False             # Enable streaming responses
)

​
Streaming Responses

Enable streaming for real-time output: 
stream = client.chat.completions.create(
    model="qwen3-vl-235b-a22b-instruct",
    messages=messages,
    stream=True
)

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

​
Error Handling

Implement proper error handling: 
from openai import OpenAI, OpenAIError

try:
    completion = client.chat.completions.create(
        model="qwen3-vl-235b-a22b-instruct",
        messages=messages
    )
    print(completion.choices[0].message.content)
except OpenAIError as e:
    print(f"API error: {e}")

​
Best Practices

​
API Key Security

  • Never hardcode API keys in your source code
  • Use environment variables: 
    import os
DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")

​
Rate Limiting

  • Implement exponential backoff for retries
  • Monitor your API usage
  • Cache responses when possible

​
Cost Optimization

  • Set appropriate max_tokens limits
  • Use batch processing for multiple requests
  • Monitor token usage in responses

​
Additional Resources

For more detailed information, refer to:

​
Next Steps