OpenAI compatible - Chat
The Qwen models on Model Studio support OpenAI compatible interfaces. You can migrate your existing OpenAI code to Model Studio by changing only the API key, base URL, and model name.
The Qwen models on Alibaba Cloud Model Studio support the OpenAI compatible interface. You only need to change the API key, BASE_URL, and model name to migrate your existing OpenAI code to Alibaba Cloud Model Studio.
Information required for OpenAI compatibility
BASE_URL
The BASE_URL represents the network access point or address of the model service. You can access the functions or data provided by the service through this address. In the use of web services or APIs, the BASE_URL usually corresponds to the URL of a specific operation or resource of the service. When you use the OpenAI compatible interface to use the Alibaba Cloud Model Studio model service, you need to configure the BASE_URL.
- When you call through the OpenAI SDK or other OpenAI compatible SDKs, the BASE_URL you need to configure is as follows:
北京:https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
弗吉尼亚:https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
新加坡:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
日本(东京):https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
- When you call through HTTP requests, the full endpoint you need to configure is as follows:
北京:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
弗吉尼亚:POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
新加坡:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
日本(东京):POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
ImportantModel Studio has launched workspace-specific domain names for the China (Beijing), Singapore, and China (Hong Kong) regions, which provide superior performance and higher stability for inference requests. We recommend that you migrate to the new domain names:
- China (Beijing) region: migrate from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore region: migrate from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which you can view on the workspace details page in the Alibaba Cloud Model Studio console. The existing domain names remain available.
Troubleshoot failed calls: When you call through the OpenAI compatible interface, if you encounter errors such as 404, 401, 403, or connection failures, check the following configurations in order:
Cross-region calls
Model Studio API keys are bound to regions. When you call the base_url of a region, you must use an API key created in that same region. Calling the endpoint of that region with an API key from another region is rejected during authentication.
This rule applies to all regions that provide endpoints, including China (Beijing), US (Virginia), Singapore, and Japan (Tokyo). Create the API key in the console of the region corresponding to the endpoint you call.
When you use an API key from the Beijing region to call the Virginia endpoint, HTTP 401 is returned, with the error message Incorrect API key provided and the error code invalid_api_key. This error indicates that the API key does not match the region of the endpoint, rather than that the API key is invalid or lacks permissions.
Supported models
Supported models: Qwen large language models (commercial and open-source editions), Qwen-VL, Qwen-Coder, Qwen-Omni, Qwen-Math, DeepSeek (Alibaba Cloud direct, SiliconFlow direct, Kuaishou Wanqing direct), Kimi (Alibaba Cloud direct, Moonshot direct), GLM (Alibaba Cloud direct), MiniMax (Alibaba Cloud direct, MiniMax direct).
Third-party direct-supply models are available only in the China (Beijing) region on the China site. Before calling them, you must first enable the corresponding service in the Model Studio console (for example, for SiliconFlow DeepSeek: search for deepseek → find the SiliconFlow DeepSeek model card → click Enable Now → confirm the authorization).
Qwen-Audio does not support the OpenAI compatible protocol. It supports only the DashScope protocol.
Call through the OpenAI SDK
Prerequisites
-
Make sure that a Python environment is installed on your computer.
-
Install the latest version of the OpenAI SDK.
# 如果下述命令报错,请将pip替换为pip3
pip install -U openai
-
You need to activate the Alibaba Cloud Model Studio model service and obtain an API key. For more information, see Obtain and configure an API key.
-
We recommend that you configure the API key as an environment variable to reduce the risk of API key leakage. For the configuration method, see Configure an API key as an environment variable. You can also configure the API key in code, but this increases the risk of leakage.
-
Select the model you want to use: Supported models.
Usage
You can refer to the following examples to use the OpenAI SDK to access Qwen models on Model Studio.
Non-streaming call example
from openai import OpenAI
import os
def get_response():
client = OpenAI(
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx",
# 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base_url
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen4-max", # 此处以qwen4-max为例,可按需更换模型名称。模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
messages=[{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': '你是谁?'}]
)
print(completion.model_dump_json())
if __name__ == '__main__':
get_response()
Running the code returns the following result:
The following historical qwen3.8-max response illustrates the response fields.
{
"id": "chatcmpl-xxx",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "我是来自阿里云的超大规模预训练模型,我叫千问。",
"role": "assistant",
"function_call": null,
"tool_calls": null
}
}
],
"created": 1716430652,
"model": "qwen3.8-max",
"object": "chat.completion",
"system_fingerprint": null,
"usage": {
"completion_tokens": 18,
"prompt_tokens": 22,
"total_tokens": 40
}
}
Streaming call example
from openai import OpenAI
import os
def get_response():
client = OpenAI(
# 如果您没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx"
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base_url
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen4-max", # 此处以qwen4-max为例,可按需更换模型名称。模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
messages=[{'role': 'system', 'content': 'You are a helpful assistant.'},
{'role': 'user', 'content': '你是谁?'}],
stream=True,
# 通过以下设置,在流式输出的最后一行展示token使用信息
stream_options={"include_usage": True}
)
for chunk in completion:
print(chunk.model_dump_json())
if __name__ == '__main__':
get_response()
Running the code returns the following result:
The following historical qwen3.8-max response illustrates the response fields.
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"","function_call":null,"role":"assistant","tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"我是","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"来自","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"阿里","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"云的大规模语言模型","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":",我叫千问。","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"","function_call":null,"role":null,"tool_calls":null},"finish_reason":"stop","index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":{"completion_tokens":16,"prompt_tokens":22,"total_tokens":38}}
function call example
This section uses a weather query tool and a time query tool as examples to show you how to implement function call through the OpenAI compatible interface. The example code supports multi-turn tool calling.
from openai import OpenAI
from datetime import datetime
import json
import os
client = OpenAI(
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx",
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base_url
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1", # 填写DashScope SDK的base_url
)
# 定义工具列表,模型在选择使用哪个工具时会参考工具的name和description
tools = [
# 工具1 获取当前时刻的时间
{
"type": "function",
"function": {
"name": "get_current_time",
"description": "当你想知道现在的时间时非常有用。",
# 因为获取当前时间无需输入参数,因此parameters为空字典
"parameters": {}
}
},
# 工具2 获取指定城市的天气
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "当你想查询指定城市的天气时非常有用。",
"parameters": {
"type": "object",
"properties": {
# 查询天气时需要提供位置,因此参数设置为location
"location": {
"type": "string",
"description": "城市或县区,比如北京市、杭州市、余杭区等。"
}
}
},
"required": [
"location"
]
}
}
]
# 模拟天气查询工具。返回结果示例:“北京今天是雨天。”
def get_current_weather(location):
return f"{location}今天是雨天。 "
# 查询当前时间的工具。返回结果示例:“当前时间:2024-04-15 17:15:18。“
def get_current_time():
# 获取当前日期和时间
current_datetime = datetime.now()
# 格式化当前日期和时间
formatted_time = current_datetime.strftime('%Y-%m-%d %H:%M:%S')
# 返回格式化后的当前时间
return f"当前时间:{formatted_time}。"
# 封装模型响应函数
def get_response(messages):
completion = client.chat.completions.create(
model="qwen4-max", # 此处以qwen4-max为例,可按需更换模型名称。模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
messages=messages,
tools=tools
)
return completion.model_dump()
def call_with_messages():
print('\n')
messages = [
{
"content": input('请输入:'), # 提问示例:"现在几点了?" "一个小时后几点" "北京天气如何?"
"role": "user"
}
]
print("-"*60)
# 模型的第一轮调用
i = 1
first_response = get_response(messages)
assistant_output = first_response['choices'][0]['message']
print(f"\n第{i}轮大模型输出信息:{first_response}\n")
if assistant_output['content'] is None:
assistant_output['content'] = ""
messages.append(assistant_output)
# 如果不需要调用工具,则直接返回最终答案
if assistant_output['tool_calls'] == None: # 如果模型判断无需调用工具,则将assistant的回复直接打印出来,无需进行模型的第二轮调用
print(f"无需调用工具,我可以直接回复:{assistant_output['content']}")
return
# 如果需要调用工具,则进行模型的多轮调用,直到模型判断无需调用工具
while assistant_output['tool_calls'] != None:
# 如果判断需要调用查询天气工具,则运行查询天气工具
if assistant_output['tool_calls'][0]['function']['name'] == 'get_current_weather':
tool_info = {"name": "get_current_weather", "role":"tool"}
# 提取位置参数信息
location = json.loads(assistant_output['tool_calls'][0]['function']['arguments'])['location']
tool_info['content'] = get_current_weather(location)
# 如果判断需要调用查询时间工具,则运行查询时间工具
elif assistant_output['tool_calls'][0]['function']['name'] == 'get_current_time':
tool_info = {"name": "get_current_time", "role":"tool"}
tool_info['content'] = get_current_time()
print(f"工具输出信息:{tool_info['content']}\n")
print("-"*60)
messages.append(tool_info)
assistant_output = get_response(messages)['choices'][0]['message']
if assistant_output['content'] is None:
assistant_output['content'] = ""
messages.append(assistant_output)
i += 1
print(f"第{i}轮大模型输出信息:{assistant_output}\n")
print(f"最终答案:{assistant_output['content']}")
if __name__ == '__main__':
call_with_messages()
Input parameter configuration
The input parameters are aligned with the interface parameters of OpenAI. The currently supported parameters are as follows:
| Parameter | Type | Default value | Description |
|---|---|---|---|
model | string | You can use the model parameter to specify the model. For available models, see Supported models. | |
messages | array | The conversation history between the user and the model. Each element in the array takes the form | |
top_p (optional) | float | The probability threshold for nucleus sampling during generation. For example, when the value is 0.8, only the smallest set of the most likely tokens whose cumulative probability is greater than or equal to 0.8 is retained as the candidate set. The value range is (0, 1.0). A larger value increases the randomness of generation; a smaller value increases the determinism of generation. | |
temperature (optional) | float | Used to control the randomness and diversity of model responses. Specifically, the temperature value controls the degree of smoothing applied to the probability distribution of each candidate word during text generation. A higher temperature value lowers the peak of the probability distribution, so that more low-probability words are selected and the generated results are more diverse; a lower temperature value sharpens the peak of the probability distribution, so that high-probability words are more likely to be selected and the generated results are more deterministic. Value range: [0, 2). A value of 0 is not recommended because it is meaningless. | |
presence_penalty (optional) | float | Used by the user to control the repetition within the entire sequence during model generation. Increasing presence_penalty can reduce the repetition of model generation. The value range is [-2.0, 2.0]. NoteCurrently, this parameter is supported only on Qwen commercial models and open-source models qwen1.5 and later. | |
n (optional) | integer | 1 | The number of responses to generate. The value range is
|
max_tokens (optional) | integer | The maximum number of tokens the model can generate. For example, if the maximum output length of the model is 2k, you can set this parameter to 1k to prevent the model from generating overly long content. Different models have different output limits. For details, see the model list. | |
seed (optional) | integer | The random seed used during generation to control the randomness of the generated content. seed supports unsigned 64-bit integers. | |
stream (optional) | boolean | False | Used to control whether to use streaming output. When results are output in stream mode, the result returned by the interface is a generator, and you need to iterate over it to obtain the results. Each output is the incremental sequence currently generated. |
stop (optional) | string or array | None | The stop parameter is used to precisely control the content generation process. Generation automatically stops when the content generated by the model is about to contain the specified string or token_id. stop can be of the string type or the array type.
|
tools (optional) | array | None | Used to specify the tool library that the model can call. In a function call flow, the model selects one of the tools from it. The structure of each tool in tools is as follows:
In a function call flow, you must set the tools parameter both in the turn that initiates the function call and in the turn that submits the execution result of the tool function to the model. Currently supported models include qwen-plus and qwen-max. Notetools cannot currently be used together with stream=True. |
stream_options (optional) | object | None | This parameter is used to configure whether to display the number of tokens used during streaming output. It takes effect only when stream is True. If you need to count the number of tokens in streaming output mode, configure this parameter as |
enable_search | boolean | False | Used to control whether the model uses internet search results as a reference when generating text. Valid values:
The configuration method is: |
Response parameters
Response parameter | Data type | Description | Notes |
|---|---|---|---|
id | string | The system-generated ID that identifies this call. | None |
model | string | The name of the model used for this call. | None |
system_fingerprint | string | The configuration version used by the model runtime. Currently not supported; an empty string "" is returned. | None |
choices | array | Details of the content generated by the model. | None |
choices[i].finish_reason | string | There are three cases:
| |
choices[i].message | object | The message output by the model. | |
choices[i].message.role | string | The role of the model, fixed as assistant. | |
choices[i].message.content | string | The text generated by the model. | |
choices[i].index | integer | The sequence number of the generated result. The default is 0. | |
created | integer | The timestamp of the current generated result (in seconds). | None |
usage | object | Metering information, indicating the token data consumed by this request. | None |
usage.prompt_tokens | integer | The length of the user input text after being converted into tokens. | None |
usage.completion_tokens | integer | The length of the model-generated reply after being converted into tokens. | None |
usage.total_tokens | integer | The sum of usage.prompt_tokens and usage.completion_tokens. | None |
Call through the langchain_openai SDK
Prerequisites
-
Make sure that a Python environment is installed on your computer.
-
Install the langchain_openai SDK by running the following command.
# 如果下述命令报错,请将pip替换为pip3
pip install -U langchain_openai
- You need to activate the Alibaba Cloud Model Studio model service and obtain an API key. For more information, see Obtain and configure an API key.
- We recommend that you configure the API key as an environment variable to reduce the risk of API key leakage. For details, see Configure an API key as an environment variable. You can also configure the API key in code, but this increases the risk of leakage.
- Select the model you want to use: Supported models.
Usage
You can refer to the following examples to use Qwen models on Alibaba Cloud Model Studio through the langchain_openai SDK.
Non-streaming output
Non-streaming output is implemented by using the invoke method. See the following example code:
from langchain_openai import ChatOpenAI
import os
def get_response():
llm = ChatOpenAI(
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx",
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base_url
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
model="qwen4-max" # 此处以qwen4-max为例,可按需更换模型名称。模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
)
messages = [
{"role":"system","content":"You are a helpful assistant."},
{"role":"user","content":"你是谁?"}
]
response = llm.invoke(messages)
print(response.json())
if __name__ == "__main__":
get_response()
Running the code, you can get the following result:
{
"content": "我是来自阿里云的大规模语言模型,我叫千问。",
"additional_kwargs": {},
"response_metadata": {
"token_usage": {
"completion_tokens": 16,
"prompt_tokens": 22,
"total_tokens": 38
},
"model_name": "qwen-plus",
"system_fingerprint": "",
"finish_reason": "stop",
"logprobs": null
},
"type": "ai",
"name": null,
"id": "run-xxx",
"example": false,
"tool_calls": [],
"invalid_tool_calls": []
}
Streaming output
Streaming output is implemented by using the stream method. You do not need to configure the stream parameter in the parameters.
from langchain_openai import ChatOpenAI
import os
def get_response():
llm = ChatOpenAI(
# 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx",
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base_url
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
model="qwen4-max", # 此处以qwen4-max为例,可按需更换模型名称。模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
stream_usage=True
)
messages = [
{"role":"system","content":"You are a helpful assistant."},
{"role":"user","content":"你是谁?"},
]
response = llm.stream(messages)
for chunk in response:
print(chunk.model_dump_json())
if __name__ == "__main__":
get_response()
Running the code, you can get the following result:
{"content": "", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "我是", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "来自", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "阿里", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "云", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "的大规模语言模型", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": ",我叫通", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "义千问。", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "", "additional_kwargs": {}, "response_metadata": {"finish_reason": "stop"}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": {"input_tokens": 22, "output_tokens": 16, "total_tokens": 38}, "tool_call_chunks": []}
For the configuration of input parameters, see Input parameter configuration. The relevant parameters are defined in the ChatOpenAI object.
Call through the HTTP interface
You can call the Alibaba Cloud Model Studio service through the HTTP interface and get responses with the same structure as those returned by calling OpenAI services through the HTTP interface.
Prerequisites
- You need to activate the Alibaba Cloud Model Studio model service and obtain an API key. For more information, see Obtain and configure an API key.
- We recommend that you configure the API key as an environment variable to reduce the risk of API key leakage. For the configuration method, see Configure an API key as an environment variable. You can also configure the API key in code, but this increases the risk of leakage.
Endpoint
北京:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
美国(弗吉尼亚):POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
新加坡:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Request examples
The following example shows a script that calls the API through the cURL command.
NoteIf you have not configured the API key as an environment variable, change $DASHSCOPE_API_KEY to your API key*.*
Non-streaming output
# ======= 重要提示 =======
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
# 以下是北京地域base_url
# === 执行时请删除该注释 ===
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen4-max",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "你是谁?"
}
]
}'
Running the command returns the following result:
The following historical qwen3.8-max response illustrates the response fields.
{
"choices": [
{
"message": {
"role": "assistant",
"content": "我是来自阿里云的大规模语言模型,我叫千问。"
},
"finish_reason": "stop",
"index": 0,
"logprobs": null
}
],
"object": "chat.completion",
"usage": {
"prompt_tokens": 11,
"completion_tokens": 16,
"total_tokens": 27
},
"created": 1715252778,
"system_fingerprint": "",
"model": "qwen3.8-max",
"id": "chatcmpl-xxx"
}
Streaming output
If you need streaming output, specify the stream parameter as true in the request body.
# ======= 重要提示 =======
# 各地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
# 以下是北京地域base_url
# === 执行时请删除该注释 ===
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen4-max",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "你是谁?"
}
],
"stream":true
}'
Running the command returns the following result:
The following historical qwen3.8-max response illustrates the response fields.
data: {"choices":[{"delta":{"content":"","role":"assistant"},"index":0,"logprobs":null,"finish_reason":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: {"choices":[{"finish_reason":null,"delta":{"content":"我是"},"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: {"choices":[{"delta":{"content":"来自"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: {"choices":[{"delta":{"content":"阿里"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: {"choices":[{"delta":{"content":"云的大规模语言模型"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: {"choices":[{"delta":{"content":",我叫千问。"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: {"choices":[{"delta":{"content":""},"finish_reason":"stop","index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}
data: [DONE]
For details about the input parameters, see Input parameter configuration.
Error response examples
When an API request fails, the output result indicates the cause of the error through code and message.
{
"error": {
"message": "Invalid API-key provided.",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}
Third-party client configuration
In addition to calling through SDKs and HTTP directly, you can also access Alibaba Cloud Model Studio from third-party LLM clients that support the OpenAI compatible protocol. The following uses the Zhipu client as an example. After you fill in the configuration as follows, you can make model calls:
-
In the provider settings of the client, select Custom provider.
-
Base URL: Enter the OpenAI SDK-style address for the region in the BASE_URL section of the "Information required for OpenAI compatibility" part of this document, that is, an address that ends with
/compatible-mode/v1and does not contain/chat/completions. The Base URL differs by region and must match the region of your API key.For example, for the China (Beijing) region, enter
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1, where{WorkspaceId}is your workspace ID, which you can view on the workspace details page in the Alibaba Cloud Model Studio console. The originalhttps://dashscope.aliyuncs.comdomain still works, but we recommend that you use the workspace-specific domain first. -
API Key: Enter the Model Studio API key for the corresponding region. You can create and obtain an API key on the API Key management page of the Model Studio console.
-
Model name: Enter the name of a large language model that supports the OpenAI compatible protocol. For available models, see the Supported models section of the "Information required for OpenAI compatibility" part of this document. For example,
qwen3.7-plusis only an example model name and does not indicate a free quota commitment. -
Save the configuration and start a conversation to verify whether the third-party client can call the model normally.
If a call returns HTTP 400, and error.message is current user api does not support http call and error.type is invalid_request_error, the model you entered does not support HTTP calls through the OpenAI compatible interface. Replace it with a model from the Supported models list and try again.
Status codes
Error code | Description |
|---|---|
400 - Invalid Request Error | The input request is incorrect. For details, see the specific error message. |
401 - Invalid API-key provided | The API key is incorrect. |
429 - Rate limit reached for requests | QPS, QPM, or other limits are exceeded. |
429 - You exceeded your current quota, please check your plan and billing details | The quota is exceeded or the account is in arrears. |
500 - The server had an error while processing your request | Server error. |
503 - The engine is currently overloaded, please try again later | The server load is too high. You can retry. |