Multimodal embedding API

China (Beijing)

Singapore

Image embedding

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)
# Replace the URL with your own image URL.
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
try:
    # Call the model API.
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus",
        input=input
    )
    # Embedding result: resp.embeddings[i].embedding is the embedding vector, and resp.embeddings[i].index is the input index.
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

import os
import base64
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)
# Read the image and convert it to Base64. Replace xxx.png with your image file.
image_path = "xxx.png"
with open(image_path, "rb") as image_file:
    # Read the file and convert it to Base64.
    base64_image = base64.b64encode(image_file.read()).decode('utf-8')
# Set the image format.
image_format = "png"  # Change this to your image's format (e.g., jpg, bmp).
image_data = f"data:image/{image_format};base64,{base64_image}"
# Input data
input = [{'image': image_data}]
try:
    # Call the model API.
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus",
        input=input
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

Video embedding

Currently, the model only supports video input via URL. Local video files are not supported.

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)
# Replace the URL with your own video URL.
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
input = [{'video': video}]
try:
    # Call the model API.
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus",
        input=input
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

Text embedding

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)
text = "General multimodal representation model example"
input = [{'text': text}]
try:
    # Call the model API.
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus",
        input=input
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

Fused embedding

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If the environment variable is not set, provide your Model Studio API key, e.g., api_key="sk-xxx".
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Fuses text, image, and video into a single fused embedding.
# Ideal for use cases like cross-modal retrieval and image search.
text = "This is a test text for generating a multimodal fused embedding."
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"

# Input includes text, image, and video. Set enable_fusion=True to generate a fused embedding.
input_data = [
    {"text": text},
    {"image": image},
    {"video": video}
]

try:
    # Use qwen3-vl-embedding to generate a fused embedding.
    resp = client.multimodal.embeddings.create(
        model="qwen3-vl-embedding",
        input=input_data,
        enable_fusion=True,
        # Optional: Specify the embedding dimension. Valid values: 2560, 2048, 1536, 1024, 768, 512, and 256. Default: 2560.
        # dimension=1024
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

Multi-image fused embedding

Use qwen3-vl-embedding to fuse multiple images and text into a single embedding. To fuse multiple images, pass multiple image items. This is ideal for semantic retrieval using multi-angle product images and a text description.

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If the environment variable is not set, provide your Model Studio API key, e.g., api_key="sk-xxx".
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Fuses multiple product images and a description into a single embedding.
# Ideal for comprehensive semantic retrieval using multi-angle product images and a text description.
text = "White sports shoes, lightweight and breathable, suitable for running and daily wear."
image1 = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
image2 = "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"

# Pass multiple image items and set enable_fusion=True to fuse all inputs into a single embedding.
input_data = [
    {"text": text},
    {"image": image1},
    {"image": image2}
]

try:
    resp = client.multimodal.embeddings.create(
        model="qwen3-vl-embedding",
        input=input_data,
        enable_fusion=True
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

2026-03-06 snapshot version

This example shows how to use the tongyi-embedding-vision-plus-2026-03-06 model and its res_level (resolution) and max_video_frames (video frames) parameters. Built on the Qwen3 foundation, this model supports 30+ languages and generates both independent and fused embeddings.

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Demonstrates using the res_level (resolution) and max_video_frames (video frames) parameters.
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
text = "This is a visual multimodal representation model."

input_data = [
    {"text": text},
    {"image": image},
    {"video": video}
]

try:
    # Call the 2026-03-06 snapshot model.
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus-2026-03-06",
        input=input_data,
        dimension=1152,      # Valid values: 1152, 1024, 512, 256, 128, 64
        res_level=1,         # Resolution level: 0, 1, 2, or 3. The default is 1.
        max_video_frames=64  # Maximum number of sampled video frames. Default: 8. Maximum: 64.
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

To generate a fused embedding with the 2026-03-06 version, place text, image, and video in the same content object. The model fuses all inputs into a single embedding with the type fused.

import os
import dashscope
from dashscope.v2 import DashScopeError
# This configuration is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
client = dashscope.Client(
    # If you have not set an environment variable, replace this line with your Model Studio API key: api_key="sk-xxx",
    # API keys are region-specific. To get an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# To create a fused embedding, place text and image in the same content object.
# The model fuses all inputs into a single embedding of type `fused`.
text = "White sports shoes, lightweight and breathable, suitable for running and daily wear."
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"

# Multimodal content in the same object is fused into a single embedding.
input_data = [
    {"text": text, "image": image}
]

try:
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus-2026-03-06",
        input=input_data,
        dimension=1152
    )
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("For troubleshooting, see https://help.aliyun.com/en/model-studio/error-code")

dashscope CLI

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your Workspace ID. This model is available only in China (Beijing) and Singapore. For Singapore, replace cn-beijing with ap-southeast-1
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope multimodal-embedding create -m tongyi-embedding-vision-plus --text "Hello world"

For the complete region table, see Base URL overview.