OpenAI compatible - Chat

Updated at:

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.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore region: migrate from https://dashscope-intl.aliyuncs.com to https://{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:

ParameterTypeDefault valueDescription

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 {"role": role, "content": content}. The currently valid values of role are system, user, and assistant. Among them, only messages[0] supports the system role. In general, user and assistant must alternate, and the role of the last element in messages must be user.

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 1-4. For scenarios that require multiple responses (such as creative writing and advertising copy), you can set a larger n value.

Setting a larger n value does not increase input token consumption, but increases output token consumption.

Currently, this parameter is supported only on the qwen-plus model, and it is fixed at 1 when the tools parameter is passed in.

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.

  • string type

    Generation stops when the model is about to generate the specified stop word.

    For example, if you set stop to "你好", the model stops when it is about to generate "你好".

  • array type

    Elements in the array can be token_ids, strings, or arrays whose elements are token_ids. Generation stops when the token that the model is about to generate or its corresponding token_id is in stop. The following are examples of stop as an array (the corresponding tokenizer model is qwen3.5-flash):

    1. Elements are token_ids:

    The token_ids 108386 and 104307 correspond to the tokens "你好" and "天气" respectively. If you set stop to [108386,104307], the model stops when it is about to generate "你好" or "天气".

    1. Elements are strings:

    If you set stop to ["你好","天气"], the model stops when it is about to generate "你好" or "天气".

    1. Elements are arrays:

    The token_ids 108386 and 103924 correspond to the tokens "你好" and "啊" respectively, and the token_ids 35946 and 101243 correspond to the tokens "我" and "很好" respectively. If you set stop to [[108386, 103924],[35946, 101243]], the model stops when it is about to generate "你好啊" or "我很好".

    NoteWhen stop is of the array type, you cannot enter token_ids and strings as elements at the same time. For example, you cannot set stop to ["你好",104307].

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:

  • type, of the string type, indicates the type of the tools. Currently, only function is supported.

  • function, of the object type, whose keys include name, description, and parameters:

    • name: of the string type, indicates the name of the tool function. It must consist of letters and numbers, can contain underscores and hyphens, and has a maximum length of 64.

    • description: of the string type, indicates the description of the tool function, which the model refers to when deciding when and how to call the tool function.

    • parameters: of the object type, indicates the description of the tool parameters and must be a valid JSON Schema. For the description of JSON Schema, see link. If the parameters parameter is empty, the function has no input parameters.

      The type of each property in parameters supports the common types defined by JSON Schema, including string, number, integer, boolean, array, and object. When the property type is array, you need to specify the type of the array elements through the items field. Example:

{
    "type": "object",
    "properties": {
        "command": {
            "type": "array",
            "items": {"type": "string"},
            "description": "要执行的命令,例如['ls', '-l']"
        }
    },
    "required": ["command"]
}

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 stream_options={"include_usage":True}.

enable_search

boolean

False

Used to control whether the model uses internet search results as a reference when generating text. Valid values:

  • True: enables internet search. The model uses the search results as reference information during text generation, but the model determines whether to use the internet search results based on its internal logic.

    If no internet search is performed after you enable it, you can optimize the prompt, or set the forced_search parameter in search_options to enable forced search.

  • False (default): disables internet search.

qwen-long does not support this parameter currently.

The configuration method is: extra_body={"enable_search": True}.

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:

  • null while generation is in progress;

  • stop when generation ends because a stop condition in the input parameters is triggered;

  • length when generation ends because the generated content is too long.

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:

  1. In the provider settings of the client, select Custom provider.

  2. 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/v1 and 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 original https://dashscope.aliyuncs.com domain still works, but we recommend that you use the workspace-specific domain first.

  3. 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.

  4. 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-plus is only an example model name and does not indicate a free quota commitment.

  5. 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.