Embedding models convert text, images, and video into numerical vectors for semantic search, recommendations, clustering, classification, and anomaly detection.
Prerequisites
Get an API key and set it as an environment variable. To use the SDK, install it.
Get embeddings
Text embedding
To make an API request, specify the text to embed and the model to use.
- OpenAI compatible API
- DashScope
Multimodal independent vectors
Generate separate vectors for each input modality (text, image, or video). Use this when you need to process each content type independently.
Multimodal independent embedding requires the DashScope SDK or API. OpenAI-compatible endpoints are not supported.
- Python
- Java
Model selection
Text embedding
| Model | Embedding dimensions | Batch size | Max tokens per batch | Supported languages |
|---|---|---|---|---|
| qwen3.7-text-embedding | 2,560, 2,048, 1,536, 1,024 (default), 768, 512, 256 | 20 | 128,000 | 201 major languages and dialects, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian |
| text-embedding-v4 (Part of the Qwen3-Embedding series) | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, 64 | 10 | 8,192 | 100+ major languages, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, and multiple programming languages |
| text-embedding-v3 | 1,024 (default), 768, 512 | 10 | 8,192 | 50+ major languages, including Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian |
Batch size is the maximum number of texts per API call. For example, text-embedding-v4 has a batch size of 10, which lets you include up to 10 texts for vectorization per request, where each text is limited to 8,192 tokens. This limit applies to:
- String array input: The array can contain a maximum of 10 elements.
- File input: The text file can contain a maximum of 10 lines of text.
All languages supported by qwen3.7-text-embedding
All languages supported by qwen3.7-text-embedding
- Sino-Tibetan: Chinese (Simplified Chinese, Traditional Chinese, Cantonese), Burmese, Tibetan, Meitei
- Indo-European: English, French, Portuguese, German, Romanian, Swedish, Danish, Bulgarian, Russian, Czech, Greek, Ukrainian, Spanish, Dutch, Slovak, Croatian, Polish, Lithuanian, Norwegian (Bokmal), Norwegian Nynorsk, Persian, Slovenian, Gujarati, Latvian, Italian, Occitan, Nepali, Marathi, Belarusian, Serbian, Luxembourgish, Venetian, Assamese, Welsh, Silesian, Asturian, Chhattisgarhi, Awadhi, Maithili, Bhojpuri, Sindhi, Irish, Faroese, Hindi, Punjabi, Bengali, Odia, Tajik, Eastern Yiddish, Lombard, Ligurian, Sicilian, Friulian, Sardinian, Galician, Catalan, Icelandic, Tosk, Albanian, Limburgish, Dari, Afrikaans, Macedonian, Sinhala, Urdu, Magahi, Bosnian, Armenian, Latgalian, Scottish Gaelic, Central Kurdish, Northern Kurdish, Southern Pashto, Sanskrit, Dhundari, Marwari, Ahirani, Bagheli, Bagri, Bundeli, Braj, Kumaoni, Kashmiri
- Afro-Asiatic: Arabic (Standard Arabic, Najdi Arabic, Levantine Arabic, Egyptian Arabic, Moroccan Arabic, Mesopotamian Arabic, Taizzi-Adeni Arabic, Tunisian Arabic, Gulf Arabic, Algerian Arabic, Sudanese Arabic, Libyan Arabic), Hebrew, Maltese, Amharic, Tigrinya, Kabyle, Somali, West Central Oromo, Hausa
- Austronesian: Indonesian, Malay, Tagalog, Cebuano, Javanese, Sundanese, Minangkabau, Balinese, Bangka, Pangasinan, Ilocano, Waray (Philippines), Plateau Malagasy, Malagasy, Buginese, Maori, Samoan, Hawaiian, Fijian
- Dravidian: Tamil, Telugu, Kannada, Malayalam
- Turkic: Turkish, North Azerbaijani, Northern Uzbek, Kazakh, Bashkir, Tatar, Crimean Tatar, Kyrgyz, Turkmen, Uyghur
- Kra-Dai: Thai, Lao, Shan
- Uralic: Finnish, Estonian, Hungarian, Meadow Mari
- Austroasiatic: Vietnamese, Khmer
- Niger-Congo: Yoruba, Ewe, Kinyarwanda, Lingala, Northern Sotho, Nyanja, Shona, Southern Sotho, Tswana, Xhosa, Zulu, Luganda, Swati, Tsonga, Tumbuka, Venda, Chokwe, Luba-Kasai, Rundi, Mbundu, Kikuyu, Kongo, Nigerian Fulfulde, Wolof, Fon, Kabiyé, Mossi, Akan, Twi, Bambara, Igbo
- Other: Japanese, Korean, Georgian, Basque, Haitian Creole, Papiamento, Cape Verdean Creole, Tok Pisin, Swahili, Central Aymara, Tulu, Naga, Nigerian Pidgin, Mauritian Creole, Sango, Ayacucho Quechua, Halh Mongolian, Southwestern Dinka, Nuer, Guarani
Multimodal embedding
| Model | Dimensions | Text limit | Image limit | Video limit |
|---|---|---|---|---|
| tongyi-embedding-vision-plus | 1152 | 1,024 tokens | Max 3 MB per image, up to 8 images | Max 10 MB per video |
| tongyi-embedding-vision-flash | 768 | 1,024 tokens | Max 3 MB per image, up to 8 images | Max 10 MB per video |
Text-only data? Use text-embedding-v4 instead — faster, cheaper, more dimension options. Multimodal embedding is for cross-modal retrieval (text+image, text+video).
Input and language support
| Model | Text | Image | Video | Max items per request |
|---|---|---|---|---|
| tongyi-embedding-vision-plus | Chinese and English | JPEG, PNG, BMP (URL or Base64) | MP4, MPEG, MOV, MPG, WEBM, AVI, FLV, MKV (URL only) | No element count limit. Total tokens must stay within the batch token limit. |
| tongyi-embedding-vision-flash | Chinese and English | JPEG, PNG, BMP (URL or Base64) | MP4, MPEG, MOV, MPG, WEBM, AVI, FLV, MKV (URL only) | No element count limit. Total tokens must stay within the batch token limit. |
Core features
Switch embedding dimensions
qwen3.7-text-embedding, text-embedding-v4, text-embedding-v3, tongyi-embedding-vision-plus, and tongyi-embedding-vision-flash support custom embedding dimensions. Higher dimensions retain richer semantic information but also increase storage and computation costs.
- General scenarios (Recommended): 1024 dimensions offer the best balance between performance and cost, suitable for most semantic retrieval tasks.
- High-precision scenarios: For applications that require high precision, choose 1536 or 2048 dimensions. This improves precision but significantly increases storage and computation overhead.
- Resource-constrained scenarios: In cost-sensitive scenarios, choose 768 or lower dimensions. This significantly reduces resource consumption but results in some loss of semantic information.
- OpenAI compatible API
- DashScope
Distinguish between query and document text (text_type)
This parameter can currently only be enabled through the DashScope SDK and API.
text_type parameter is designed for this purpose:
text_type: 'query': Use for user-provided query text. The model generates a "title-like" vector that is more directional and optimized for information retrieval.text_type: 'document'(default): Use for document text stored in the database. The model generates a "body-like" vector that contains more comprehensive information and is optimized for being retrieved.
query and document. For tasks where all texts have the same role, such as clustering or classification, you do not need to set this parameter.
Use instructions to improve performance (instruct)
This parameter can currently only be enabled through the DashScope SDK and API.
qwen3.7-text-embedding and text-embedding-v4 in optimizing vector quality for specific retrieval scenarios, improving precision. qwen3.7-text-embedding follows instructions 16.4% better than text-embedding-v4 and is the recommended choice. When using this feature, you must set the text_type parameter to query.
Dense and sparse vectors
This parameter can currently only be enabled through the DashScope SDK and API.
qwen3.7-text-embedding, text-embedding-v4, and text-embedding-v3 support three types of vector output to accommodate different retrieval strategies. The sparse embeddings of qwen3.7-text-embedding use a new SPLADE-style training strategy that improves performance by 8.4%, and the model additionally supports cross-lingual retrieval.
Vector type (output_type) | Core advantages | Main drawbacks | Typical application scenarios |
|---|---|---|---|
| dense | Deep semantic understanding that identifies synonyms and context for more relevant results. | Higher computational and storage costs. Does not guarantee an exact match for keywords. | Semantic search, AI chat, content recommendation. |
| sparse | High computational efficiency, focusing on an exact match for keywords and enabling fast filtering. | Lacks semantic understanding and cannot process synonyms or context. | Log retrieval, product SKU search, precise information filtering. |
| dense&sparse | Combines semantic and keyword matching for optimal search results. The generation cost is unchanged, and the API call overhead is identical to the single-vector mode. | Large storage requirements. More complex system architecture and retrieval logic. | High-quality, production-grade hybrid search engines. |
Use examples
The following code is for demonstration purposes only. For production, pre-compute and store embeddings in a vector database. This way, you only need to generate the query embedding for retrieval.
Semantic search
Perform precise semantic matching by calculating the similarity between the query embedding and the document embeddings.
Recommendation system
Analyze a user's behavioral history embeddings to identify their interests and recommend similar items.
Text clustering
Group similar texts by analyzing the distances between their embeddings.
Text classification
Perform zero-shot text classification by calculating the similarity between an input text's embedding and predefined label embeddings. This process classifies text into new categories without requiring pre-labeled examples.
Anomaly detection
Identify anomalous data by calculating the similarity between a text's embedding and the central embedding of normal samples. Data that significantly deviates from this pattern is considered an anomaly.
The threshold in the example is for demonstration purposes. The ideal value varies based on data content and distribution, so you must calibrate it using your own dataset.
API reference
- API details for OpenAI compatible embedding
- API details for DashScope embedding
- Multimodal Embedding API reference
Error codes
If a call fails, see Error messages.
Model performance (MTEB/CMTEB)
- MTEB: Massive Text Embedding Benchmark, a comprehensive benchmark that assesses the general-purpose performance of text embeddings on tasks such as classification, clustering, and retrieval.
- CMTEB: Chinese Massive Text Embedding Benchmark, a large-scale benchmark specifically for evaluating Chinese text embeddings.
- Scores range from 0 to 100. A higher value indicates better performance.
| Model | MTEB | MTEB (Retrieval task) | CMTEB | CMTEB (Retrieval task) |
|---|---|---|---|---|
| text-embedding-v3 (512 dimensions) | 62.11 | 54.30 | 66.81 | 71.88 |
| text-embedding-v3 (768 dimensions) | 62.43 | 54.74 | 67.90 | 72.29 |
| text-embedding-v3 (1024 dimensions) | 63.39 | 55.41 | 68.92 | 73.23 |
| text-embedding-v4 (512 dimensions) | 64.73 | 56.34 | 68.79 | 73.33 |
| text-embedding-v4 (1024 dimensions) | 68.36 | 59.30 | 70.14 | 73.98 |
| text-embedding-v4 (2048 dimensions) | 71.58 | 61.97 | 71.99 | 75.01 |