The general-purpose text embedding model converts text data into numerical vectors for downstream tasks such as semantic search, recommendations, clustering, and categorization.
Model overview
Singapore
Model | Embedding dimensions | Maxnumber of rows | Max tokens per line | Price (per 1M input tokens) | Supported languages | Free quota (Note) |
text-embedding-v4 Part of the Qwen3-Embedding series | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, 64 | 10 | 8,192 | $0.07 | Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, and 100+ other major languages | 1 million tokens Validity: 90 days after you activate Model Studio |
text-embedding-v3 | 1,024 (default), 768, 512 | Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, and 50+ other major languages | 500,000 tokens Validity: 90 days after you activate Model Studio |
Beijing
Model | Embedding dimensions | Maximum number of rows | Max tokens per line | Price (per million input tokens) | Supported languages |
text-embedding-v4 Part of the Qwen3-Embedding series | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, 64 | 10 | 8,192 | $0.072 | Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, and 100+ other major languages and multiple programming languages |
China (Hong Kong)
Model | Embedding dimensions | Maximum number of rows | Max tokens per line | Price (per million input tokens) | Supported languages |
text-embedding-v4 Part of the Qwen3-Embedding series | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, 64 | 10 | 8,192 | $0.07 | Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, Russian, and 100+ other major languages and multiple programming languages |
For model rate limits, see Rate limiting.
Prerequisites
To migrate from the OpenAI ecosystem, use the OpenAI compatible API. The DashScope API provides additional features. Choose the API that suits your needs.
Get an API key and export the API key as an environment variable. If you use an SDK to make calls, install the DashScope SDK.
OpenAI compatible
base_url for SDK:
Singapore: https://dashscope-intl.aliyuncs.com/compatible-mode/v1
China (Beijing): https://dashscope.aliyuncs.com/compatible-mode/v1
China (Hong Kong): https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1
Endpoint for HTTP:
Singapore: POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings
China (Beijing): POST https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
China (Hong Kong): POST https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1/embeddings
Request body | Input stringPythonJavaCurlIf you use a model in the China (Beijing) region, use an API key for that region and replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings Input string listPythonJavaCurlIf you use a model in the China (Beijing) region, use an API key for that region and replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings Input filePythonJavaCurlIf you use a model in the China (Beijing) region, use an API key for that region and replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings Make sure to replace 'texts_to_embedding.txt' with your file name or path. |
Model The model to call. Select from the Model overview table. | |
Input The text to process. The text can be a string, an array of strings, or a file. When the input is a string, it supports up to 8,192 tokens. When the input is a list of strings or a file, it supports up to 10 items (lines), with each item (line) supporting up to 8,192 tokens. | |
Dimensions Number of dimensions for the output vector. Must be 2,048 (for | |
Encoding_format Format of the returned embedding. Only |
Response object | Successful responseError response |
data Task output. | |
model The model used in this call. | |
object string Type of the returned data. Default: `list`. | |
usage | |
id string A unique request identifier for tracing and troubleshooting. |
Dashscope
base_url for SDK:
Singapore: https://dashscope-intl.aliyuncs.com/api/v1
China (Beijing): https://dashscope.aliyuncs.com/api/v1
China (Hong Kong): https://cn-hongkong.dashscope.aliyuncs.com/api/v1
Endpoint for HTTP:
Singapore: POST https://dashscope-intl.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
China (Beijing): POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
China (Hong Kong): POST https://cn-hongkong.dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
Request body | Input stringPythonJavaCurlIf you use a model in the China (Beijing) region, use an API key for that region and replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Input string listPythonJavaCurlIf you use a model in the China (Beijing) region, use an API key for that region and replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Input filePythonJavaCurlIf you use a model in the China (Beijing) region, use an API key for that region and replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Make sure to replace 'texts_to_embedding.txt' with your file name or path. |
Model The model to call. Select from the Model overview table. | |
Input The text to process. The text can be a string, an array of strings, or a file. A string input can contain up to 8,192 tokens. A list of strings or a file can contain up to 10 items or lines, where each item or line is limited to 8,192 tokens. | |
Text_type If you make a call over HTTP, place text_type in the `parameters` object. After converting text to vectors, use them for downstream tasks such as retrieval, clustering, and categorization. For asymmetric tasks like retrieval, distinguish between query text (`query`) and document text (`document`) for better results. For symmetric tasks like indexing, clustering, and categorization, use the default value | |
Dimension If you make a call over HTTP, place dimension in the `parameters` object. Number of dimensions for the output vector. Must be 2,048 (`text-embedding-v4` only), 1,536 (`text-embedding-v4` only), 1,024, 768, 512, 256, 128, or 64. Default: 1,024. | |
Output_type If you make a call over HTTP, place output_type in the `parameters` object. Whether to output sparse vector representations. Applicable only to | |
Instruct Add custom task instructions to guide the model in understanding the query intent. Writing instructions in English can improve performance by 1% to 5%. |
Response object | Successful responseError response |
status_code Status code of the request. 200 indicates success. | |
request_id A unique request identifier for tracing and troubleshooting. | |
code Error code returned on failure. Empty on success. | |
message Detailed error message returned on failure. Empty on success. | |
output Task output. | |
usage |
Error codes
If a model call fails and an error is returned, see Error messages for solutions.