The general-purpose text embedding model converts text data into numerical vectors for downstream tasks like semantic search, recommendation, clustering, and classification.
Model overview
Singapore
|
Model |
Embedding dimensions |
Max rows |
Max tokens per line (Note) |
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 over 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 over 50 other major languages |
500,000 tokens Validity: 90 days after you activate Model Studio |
China (Beijing)
|
Model |
Embedding dimensions |
Max rows |
Max tokens per line |
Price (per 1M 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 over 100 other major languages, plus multiple programming languages |
China (Hong Kong)
|
Model |
Embedding dimensions |
Max rows |
Max tokens per line |
Price (per 1M 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 over 100 other major languages, plus multiple programming languages |
For model rate limits, see Rate limiting.
Prerequisites
Users familiar with the OpenAI ecosystem can use the OpenAI-compatible API for a quick migration. The DashScope API provides more unique features.
Obtain 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 compatibility
The base_url to configure for SDK calls:
-
Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. Replace
WorkspaceIdwith your actual workspace ID. -
China (Beijing): https://dashscope.aliyuncs.com/compatible-mode/v1
-
China (Hong Kong): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1. Replace
WorkspaceIdwith your actual workspace ID.
The endpoint to configure for HTTP calls:
-
Singapore: POSThttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings. Replace
WorkspaceIdwith your actual workspace ID. -
China (Beijing): POSThttps://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
-
China (Hong Kong): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/embeddings. Replace
WorkspaceIdwith your actual workspace ID.
The legacy Singapore domain https://dashscope-intl.aliyuncs.com and China (Hong Kong) domain https://cn-hongkong.dashscope.aliyuncs.com will be discontinued. Migrate to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com (Singapore) and https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com (China (Hong Kong)) as soon as possible.
Request body |
Input stringPython
Java
curlIf you use a model in the China (Beijing) region, you must use an API key from that region and replace the URL with
Input string listPython
Java
curlIf you use a model in the China (Beijing) region, you must use an API key from that region and replace the URL with
Input filePython
Java
curlIf you use a model in the China (Beijing) region, you must use an API key from that region and replace the URL with
Replace 'texts_to_embedding.txt' with your file name or path.
|
|
model The name of the model to call. See the Model overview table for model names. |
|
|
input The input text to process. The input can be a string, an array of strings, or a file. If the input is a string, the maximum length is 8,192 tokens. If the input is a list of strings or a file, the maximum batch size is 10 items (lines), and each item (line) can contain up to 8,192 tokens. |
|
|
dimensions The dimension of the output embedding vectors. Must be one of the following values: 2048 (for |
|
|
encoding_format The returned embedding format. Currently, only |
Response object |
Successful response
Error response
|
|
data A list of the resulting embedding objects. |
|
|
model The name of the model used for this call. |
|
|
object string The object type. The value is always |
|
|
usage |
|
|
id string A unique request identifier, used for tracing and troubleshooting. |
DashScope
base_url for SDK calls:
-
Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1. Replace
WorkspaceIdwith your actual workspace ID. -
China (Beijing): https://dashscope.aliyuncs.com/api/v1
-
China (Hong Kong): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1. Replace
WorkspaceIdwith your actual workspace ID.
Endpoint for HTTP calls:
-
Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Replace
WorkspaceIdwith your actual workspace ID. -
China (Beijing): POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
-
China (Hong Kong): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Replace
WorkspaceIdwith your actual workspace ID.
The legacy China (Hong Kong) URL https://cn-hongkong.dashscope.aliyuncs.com/api/v1 will be deprecated soon. Please migrate to the new URL https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1 as soon as possible.
Model Studio has released a workspace-specific domain for the Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope-intl.aliyuncs.com to the new domain.
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Model Studio console. The existing domain remains fully functional.
Request body |
Input stringPython
Java
curlIf 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. This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
Input string listPython
Java
curlIf 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. This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
Input filePython
Java
curlIf 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. This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region. Replace 'texts_to_embedding.txt' with your file name or path.
|
|
model The model to use. For a list of available models, see the Model overview table. |
|
|
input The text to process. The input can be a string, an array of strings, or a file. A single string can be up to 8,192 tokens. A list of strings or a file can contain up to 10 items (lines), with each item up to 8,192 tokens. |
|
|
text_type When making an HTTP call, place text_type in the
Text converted to embeddings can be applied to downstream tasks such as retrieval, clustering, and classification. For asymmetric tasks such as retrieval, it is recommended to differentiate between query text (query) and document text (document) to achieve better retrieval performance. For symmetric tasks such as indexing, clustering, and classification, you can simply use the system default value of |
|
|
dimension When making an HTTP call, place dimension in the
Specifies the embedding dimension for the output vector. Valid values are 2048 (for |
|
|
output_type When making an HTTP call, place output_type in the
Specifies the output vector type. This parameter applies only to the |
|
|
instruct Provides custom instructions to guide the model in understanding the query intent. English instructions are recommended, as they typically improve performance by 1% to 5%. |
Response object |
Successful response
Error response
|
|
status_code The HTTP status code. A value of 200 indicates success. |
|
|
request_id A unique identifier for the request. Use this ID to trace and troubleshoot the request. |
|
|
code The error code returned if the request fails. This field is empty for successful requests. |
|
|
message A detailed error message if the request fails. This field is empty for successful requests. |
|
|
output The result of the task. |
|
|
usage |
Error codes
If a model call fails, see Error Messages.