Alibaba Cloud Model Studio's embedding models are compatible with the OpenAI API. To migrate your existing OpenAI applications to Model Studio, you only need to adjust the following three parameters:
base_url: Replace with
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1.For other regions, replace the base_url:
api_key: Replace with a Model Studio API key.
model: Replace with a model name from the list below.
Model Studio has released workspace-specific domains for the China (Beijing), Singapore, and China (Hong Kong) regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
-
China (Beijing): from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com -
Singapore: from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com -
China (Hong Kong): from
https://cn-hongkong.dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
{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.
Supported models
Singapore
Model | Embedding dimensions | Max rows | Max tokens per line (Note) | Price (per 1M input tokens) | Supported languages | Free quota (Note) |
text-embedding-v4 Qwen3-Embedding series | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, or 64 | 10 | 8,192 | $0.07 | More than 100 mainstream languages, such as Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian | 1 million tokens Valid for 90 days after Model Studio activation |
text-embedding-v3 | 1,024 (default), 768, or 512 | More than 50 mainstream languages, such as Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian | 500,000 tokens Valid for 90 days after Model Studio activation |
China (Beijing)
Model | Embedding dimensions | Max rows | Max tokens per line (Note) | Price (per 1M input tokens) | Supported languages |
text-embedding-v4 Qwen3-Embedding series | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, or 64 | 10 | 8,192 | $0.072 | More than 100 mainstream languages, such as Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian, and multiple programming languages |
China (Hong Kong)
Model | Embedding dimensions | Max rows | Max tokens per line (Note) | Price (per 1M input tokens) | Supported languages |
text-embedding-v4 Qwen3-Embedding series | 2,048, 1,536, 1,024 (default), 768, 512, 256, 128, or 64 | 10 | 8,192 | $0.07 | More than 100 mainstream languages, such as Chinese, English, Spanish, French, Portuguese, Indonesian, Japanese, Korean, German, and Russian, and multiple programming languages |
Multimodal embedding models, such as qwen3-vl-embedding and the tongyi-embedding-vision series, do not support the OpenAI-compatible API. See Multimodal Embedding.
How to use
Call examples
This section provides examples of string input using Python (OpenAI SDK) and cURL (HTTP). For examples that use other programming languages or input methods, see Get started with text embedding.
OpenAI SDK
To call the service using the OpenAI SDK, you must first install the OpenAI SDK.
import os
from openai import OpenAI
def get_response():
client = OpenAI(
# API keys vary by region. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"), # If you have not configured the environment variable, replace this value with your API key.
# The base_url of the Model Studio service. If you use a model in the China (Beijing) region, replace the URL with https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.embeddings.create(
model="text-embedding-v3", # If you use a model in the China (Beijing) region, replace the model name with text-embedding-v4.
input='The quality of the clothes is excellent. They are beautiful. It was worth the wait. I like them and will buy from here again.',
encoding_format="float"
)
print(completion.model_dump_json())
if __name__ == '__main__':
get_response()HTTP
Submit an interface call
Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings
China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddingsCall from the command line
# If you use a model in the China (Beijing) region, replace the URL with https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "text-embedding-v3",
"input": "The quality of the clothes is excellent. They are beautiful. It was worth the wait. I like them and will buy from here again.",
"encoding_format": "float"
}'The following result is returned after you run the code:
Sample error response
If an access request error occurs, the cause is indicated by the code and message parameters in the response.
{
"error": {
"message": "Incorrect API key provided. ",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}API reference
Error codes
If the model call fails and returns an error message, see Error codes for resolution.