Multimodal embeddings API

Multimodal embedding models convert text, images, and videos into embeddings in a shared semantic space, enabling cross-modal retrieval, content classification, and similarity search.

Core capabilities

Cross-modal retrieval: Search across content types --- text-to-image, image-to-video, or image-to-image.
Semantic similarity: Measure similarity between different content types in a unified embedding space.
Content classification and clustering: Group, label, and cluster content by semantic meaning.

Key attribute : All modalities (text, image, video) produce embeddings in the same semantic space, enabling direct cross-modal matching and comparison with cosine similarity. For model selection and usage, see text and multimodal embedding. Important

This model service is only available in the China (Beijing) region. Use an API key from this region to call the service.

Embedding types

The multimodal embedding model supports two embedding generation modes:

Multimodal independent embeddings : Generates a separate embedding for each input (text, image, video, or image sequence) in the contents array. For example, one text and one image produce two independent embeddings. Best for comparing individual content items, such as image-to-image or text-to-image search.
Multimodal fused embedding : Combines all inputs in contents into a single embedding for unified cross-modal semantic representation. Best when you need holistic understanding of multimodal content, such as combining product images and descriptions into one embedding for retrieval. For qwen3-vl-embedding, enable fusion by setting enable_fusion=true. Supported fusion combinations:
- Text and image
- Text and video
- Multiple images and text (by passing multiple image entries)
- Image, video, and text

qwen2.5-vl-embedding supports only fused embeddings, not independent embeddings. tongyi-embedding-vision-plus and tongyi-embedding-vision-flash support only independent embeddings.

For model details and selection, see Text and multimodal embedding.

Model overview

Singapore

Model	Embedding dimensions	Text length limit	Image size limit	Video size limit	Price (per 1M input tokens)	Free quota (Note)
tongyi-embedding-vision-plus	1152	1,024 tokens	Up to 3 MB per image. Supports up to 8 images.	Up to 10 MB per video file	Image/Video: $0.09Text: $0.09	1 million tokensValid for 90 days after activating Model Studio
tongyi-embedding-vision-flash	768	Image/Video: $0.03Text: $0.09

China (Beijing)

Model	Embedding dimensions	Text length limit	Image size limit	Video size limit	Price (per 1M input tokens)
qwen3-vl-embedding	2560 (default), 2048,\ 1536, 1024, 768, 512, 256	32,000 tokens	Up to 5 images, up to 5 MB per image	Up to 50 MB per video file	Image/Video: $0.258Text: $0.1
multimodal-embedding-v1	1024	512 tokens	Up to 8 images, 3 MB each	Up to 10 MB per video file	Free trial

Input format and language limits

Fused multimodal models
Model	Text	Image	Video	Request limit
qwen3-vl-embedding	Supports 33 major languages, including Chinese, English, Japanese, Korean, French, and German.	JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI (URL or Base64 supported)	MP4, AVI, MOV (URL only)	Up to 20 content elements per request, with a maximum of 5 images and 1 video.
Independent multimodal models
Model	Text	Image	Video	Request limit
tongyi-embedding-vision-plus	Chinese and English	JPG, PNG, BMP (URL or Base64 supported)	MP4, MPEG, MOV, MPG, WEBM, AVI, FLV, MKV (URL only)	No limit on the number of content elements. The total number of input tokens must not exceed the batch processing token limit.
tongyi-embedding-vision-flash
multimodal-embedding-v1	JPG, PNG, BMP (URL or Base64 supported)	Up to 20 content elements per request, with a maximum of 20 text segments, 1 image, and 1 video.

All models support text, image, and video inputs, individually or in combination. The tongyi-embedding-vision-plus , tongyi-embedding-vision-flash models also support multi_images input for image sequences.

Model capabilities

Model	Default dimension	Type	Supported inputs	Description
qwen3-vl-embedding	2,560	Independent / Fusion	text, image, video, multi_images	Fusion mode, enabled with the `enable_fusion` parameter, combines multimodal inputs into a single embedding.
tongyi-embedding-vision-plus	1,152	Independent only	text, image, video, multi_images	Supports `multi_images` sequences with up to 8 images.
tongyi-embedding-vision-flash	768
multimodal-embedding-v1	1,024	text, image, video	The dimension parameter is not supported. Fixed at 1,024.

Prerequisites

Create an API key and export the API key as an environment variable. If you use an SDK to make calls, install the DashScope SDK.

HTTP call

POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

Request

## Multimodal independent embedding

** The following example uses the tongyi-embedding-vision-plus model to generate independent embeddings (one embedding for each input). You can replace this with other model names. The multi_images type is supported only by tongyi-embedding-vision-plus and tongyi-embedding-vision-flash. The qwen3-vl-embedding model also supports a fused embedding mode, which is enabled by setting enable_fusion=true. For details, see the "Multimodal fused embedding" tab.

curl

curl --silent --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \\
 --header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
 --header 'Content-Type: application/json' \\
 --data '{
 "model": "tongyi-embedding-vision-plus",
 "input": {
 "contents": \[
 {"text": "Multimodal embedding model"},
 {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
 {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"},
 {"multi_images": \[
 "https://img.alicdn.com/imgextra/i2/O1CN019eO00F1HDdlU4Syj5_!!6000000000724-2-tps-2476-1158.png",
 "https://img.alicdn.com/imgextra/i2/O1CN01dSYhpw1nSoamp31CD_!!6000000005089-2-tps-1765-1639.png"
 \]
 }
 \]
 }
 }'

## Multimodal fused embedding

The qwen3-vl-embedding model supports fused embedding generation. Set enable_fusion=true to fuse all inputs into a single embedding. This supports various combinations, such as text with an image, text with a video, multiple images with text, and a mix of an image, a video, and text. The following example demonstrates a mixed fusion of multiple images, a video, and text.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \\
 --header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
 --header 'Content-Type: application/json' \\
 --data '{
 "model": "qwen3-vl-embedding",
 "input": {
 "contents": \[
 {"text": "Product description text"},
 {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"},
 {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
 {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"}
 \]
 },
 "parameters": {
 "enable_fusion": true
 }
 }'

<b>Request headers**

Content-Type *string* (Required) The content type of the request. Must be application/json.

Authorization *string* (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Request body

model *string*(Required) The model name. Set this to a model name from the Model overview.

input *object*(Required) The input content. Properties

contents** *array*(Required)** A list of content to process. Each element is a dictionary or string specifying content type and value: {"modality_type": "input_string_or_image/video_url"}. Supported types: text, image, video, multi_images. ** The qwen3-vl-embedding model supports both independent and fused embedding generation. To generate a fused embedding, add the boolean field enable_fusion and set it to true. The qwen2.5-vl-embedding model supports only fused embeddings.

Text: Key is text, value is a string. You can pass the string directly without a dictionary.
Image: Key is image. Value can be a public URL or Base64 Data URI (data:image/{format};base64,{data}), where {format} is the image format (like jpeg or png) and {data} is the Base64 string.
Multiple images: Supported by tongyi-embedding-vision-plus and tongyi-embedding-vision-flash only. Key is multi_images, value is a list of images (up to 8) following the format above.
Video: Key is video. Value must be a public URL.

<b>parameters** *object* (Optional) Embedding generation parameters. Wrap in the parameters object for HTTP calls; pass directly for SDK calls. Properties

output_type *string* (Optional) Output embedding format. Only dense is supported.

dimension *integer* (Optional) Output embedding dimension. Values vary by model:

qwen3-vl-embedding: Supports 2,560, 2,048, 1,536, 1,024, 768, 512, and 256. The default is 2,560.
tongyi-embedding-vision-plus: Not supported. Fixed at 1,152.
tongyi-embedding-vision-flash: Not supported. Fixed at 768.
multimodal-embedding-v1: Not supported. Fixed at 1,024.

fps *float* (Optional) Video frame extraction rate. Range: [0, 1] (lower = fewer frames). Default: 1.0.

instruct *string* (Optional) Custom task description to guide query intent. English recommended for 1--5% improvement.

enable_fusion *bool* (Optional) Whether to generate a fused embedding. Supported only by qwen3-vl-embedding. When set to true, all multimodal content in the contents array is fused into a single embedding. Default: false (generates an independent embedding for each modality). Supported combinations: text with an image, text with a video, multiple images with text (multiple image items), and image with video and text.

Response

## Successful response

json

{
 "output": {
 "embeddings": \[
 {
 "index": 0,
 "embedding": \[
 -0.026611328125,
 -0.016571044921875,
 -0.02227783203125,
 ...
 \],
 "type": "text"
 },
 {
 "index": 1,
 "embedding": \[
 0.051544189453125,
 0.007717132568359375,
 0.026611328125,
 ...
 \],
 "type": "image"
 },
 {
 "index": 2,
 "embedding": \[
 -0.0217437744140625,
 -0.016448974609375,
 0.040679931640625,
 ...
 \],
 "type": "video"
 }
 \]
 },
 "usage": {
 "input_tokens": 10,
 "input_tokens_details": {
 "image_tokens": 896,
 "text_tokens": 7
 },
 "output_tokens": 3,
 "total_tokens": 906
 },
 "request_id": "1fff9502-a6c5-9472-9ee1-73930fdd04c5"
}

## Error response

json

{
 "code":"InvalidApiKey",
 "message":"Invalid API-key provided.",
 "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

**output ***object* The embedding results. Properties

**embeddings ***array* List of embedding results, one per input element. Properties

**index ***int* Index in the input list.

**embedding ***array* The generated embedding.

**type ***string* The input type of the result: text, image, video, and multi_image. The following are special types: fusion is the type returned by qwen3-vl-embedding in fusion mode; vl is the type returned by qwen3-vl-embedding in independent mode.

request_id *string* Unique request identifier for tracing and troubleshooting.

code *string* Error code. Returned only for failed requests. See Error messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages. **usage ***object* Token usage statistics. Properties

**input_tokens ***int* Input token count.

**input_tokens_details ***object* Input token breakdown by type. Properties

**image_tokens ***int* Token count for input images or videos.

**text_tokens ***int* Token count for input text.

**output_tokens ***int* Output token count.

**total_tokens ***int* Total input and output tokens.

**image_tokens ***int* Image or video tokens. For videos, the system samples frames (with a configurable max) and calculates tokens from the result.

**image_count ***int* Input image count.

**duration ***int* Input video duration in seconds.

SDK usage

The SDK input parameter maps to input.contents in the HTTP request body.

Code examples

Image embedding

Image URL

HELPCODEESCAPE-python
import dashscope
import json
from http import HTTPStatus

image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
# Call the model API.
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

Local image

Convert a local image to Base64 for embedding:

HELPCODEESCAPE-python
import dashscope
import base64
import json
from http import HTTPStatus
# Read the image and convert it to Base64. Replace xxx.png with your image file name or path.
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"  # Modify this based on the actual format, such as jpg or bmp.
image_data = f"data:image/{image_format};base64,{base64_image}"
# Input data
input = [{'image': image_data}]

# Call the model API.
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)
if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

Video embedding

Video input must be a URL. Local videos are not supported.

HELPCODEESCAPE-python
import dashscope
import json
from http import HTTPStatus
# Replace this with your video URL.
video = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
input = [{'video': video}]
# Call the model API.
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

Text embedding

HELPCODEESCAPE-python
import dashscope
import json
from http import HTTPStatus

text = "General multimodal representation model example"
input = [{'text': text}]
# Call the model API.
resp = dashscope.MultiModalEmbedding.call(
    model="tongyi-embedding-vision-plus",
    input=input
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "code": getattr(resp, "code", ""),
        "message": getattr(resp, "message", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

Fused embedding

HELPCODEESCAPE-python
import dashscope
import json
import os
from http import HTTPStatus

# Multimodal fused embedding: Combines text, image, and video into a single fused embedding.
# Ideal for applications 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"

# The input contains text, an image, and a video. Set enable_fusion=True to generate a single fused embedding.
input_data = [
    {"text": text},
    {"image": image},
    {"video": video}
]

# Use qwen3-vl-embedding to generate a fused embedding.
resp = dashscope.MultiModalEmbedding.call(
    # If the environment variable is not set, provide your DashScope API Key directly, e.g., api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen3-vl-embedding",
    input=input_data,
    enable_fusion=True,
    # Optional parameter: Specify the embedding dimension. Supported values are 2560, 2048, 1536, 1024, 768, 512, and 256. The default is 2560.
    # parameters={"dimension": 1024}
)

print(json.dumps(resp, ensure_ascii=False, indent=4))

Multi-image fused embedding

This example shows how to fuse multiple images and text into a single embedding with qwen3-vl-embedding. Pass multiple image items for multi-image fusion. This approach is ideal for semantic retrieval of products using multi-angle images and text descriptions.

HELPCODEESCAPE-python
import dashscope
import json
import os
from http import HTTPStatus

# Multi-image + text fused embedding: Fuses multiple product images and a description text into a single embedding.
# Suitable 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 for multi-image fusion. `enable_fusion=True` fuses all inputs into a single embedding.
input_data = [
    {"text": text},
    {"image": image1},
    {"image": image2}
]

resp = dashscope.MultiModalEmbedding.call(
    # If the environment variable is not set, provide your DashScope API Key directly, e.g., api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen3-vl-embedding",
    input=input_data,
    enable_fusion=True
)

print(json.dumps(resp, ensure_ascii=False, indent=4))

2026-03-06 snapshot version

This example demonstrates 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 over 30 languages and generates both independent and fused embeddings.

HELPCODEESCAPE-python
import dashscope
import json
import os
from http import HTTPStatus

# Example for tongyi-embedding-vision-plus-2026-03-06
# 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}
]

# Call the 2026-03-06 snapshot version model.
resp = dashscope.MultiModalEmbedding.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="tongyi-embedding-vision-plus-2026-03-06",
    input=input_data,
    dimension=1152,      # Supported values: 1152, 1024, 512, 256, 128, and 64
    res_level=1,         # Resolution level. Supported values: 0, 1, 2, 3. Default: 1.
    max_video_frames=64  # Maximum number of sampled video frames. Default: 8, Maximum: 64.
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

The following example shows fused embedding usage for the 2026-03-06 version: text, image, and video are placed in the same content object, and the model fuses all inputs into a single embedding with type set to fused.

HELPCODEESCAPE-python
import dashscope
import json
import os
from http import HTTPStatus

# Fused embedding: Place text, image, and video in the same content object.
# The model fuses all inputs into a single embedding with 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 within the same object is fused into a single embedding.
input_data = [
    {"text": text, "image": image}
]

resp = dashscope.MultiModalEmbedding.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="tongyi-embedding-vision-plus-2026-03-06",
    input=input_data,
    dimension=1152
)

if resp.status_code == HTTPStatus.OK:
    result = {
        "status_code": resp.status_code,
        "request_id": getattr(resp, "request_id", ""),
        "output": resp.output,
        "usage": resp.usage
    }
    print(json.dumps(result, ensure_ascii=False, indent=4))

Output

HELPCODEESCAPE-json
{
    "status_code": 200,
    "request_id": "40532987-ba72-42aa-a178-bb58b52fb7f3",
    "code": "",
    "message": "",
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.009490966796875,
                    -0.024871826171875,
                    -0.031280517578125,
                    ...
                ],
                "type": "text"
            }
        ]
    },
    "usage": {
        "input_tokens": 10,
        "input_tokens_details": {
            "image_tokens": 0,
            "text_tokens": 10
        },
        "output_tokens": 1,
        "total_tokens": 11
    }
}

Error codes

If the model call fails and returns an error message, see Error messages for resolution.

Multimodal embeddings API ​

Core capabilities ​

Embedding types ​

Model overview ​

Singapore ​

China (Beijing) ​

Input format and language limits ​

Model capabilities ​

Prerequisites ​

HTTP call ​

Request ​

## Multimodal independent embedding ​

## Multimodal fused embedding ​

<b>Request headers** ​

Request body ​

Response ​

## Successful response ​

## Error response ​

SDK usage ​

Code examples ​

Image embedding ​

Image URL ​

Local image ​

Video embedding ​

Text embedding ​

Fused embedding ​

Multi-image fused embedding ​

2026-03-06 snapshot version ​

Output ​

Error codes ​