# MaaS标准API V1 本文介绍对话Chat相关API的调用规范。 ![](https://support.huaweicloud.com/model-call-maas/public_sys-resources/note_3.0-zh-cn.png) MaaS标准API V1接口不再演进，建议优先使用MaaS标准API V2接口。 #### 约束限制 - 该功能仅支持"西南-贵阳一"区域。 - 对于支持图片上传的模型，单个图片文件的大小不超过10MB。如果以Base64编码形式上传图片，需确保编码后的图片小于10MB。 #### 接口信息 表1接口信息 | 名称 | 说明 | 取值 | |:---|:---|:---| | API地址 | 调用模型服务的API地址。 | https://api.modelarts-maas.com/v1/chat/completions | | model参数 | model参数调用名称。 | 您可以任选以下方式获取model参数值。 - 在"模型推理 \> 在线推理 \> 预置服务"页签的服务名称左侧，单击![](https://support.huaweicloud.com/model-call-maas/figure/zh-cn_image_0000002484335976.png "点击放大")图标，在"model参数"列查看取值。更多信息，请参见[MaaS开通预置服务](https://support.huaweicloud.com/model-call-maas/model-call-052.html)。 图1预置服务-model参数 ![](https://support.huaweicloud.com/model-call-maas/figure/zh-cn_image_0000002484335200.png "点击放大") - 在"模型推理 \> 在线推理 \> 自定义接入点"页签的"model参数"列查看取值。更多信息，请参见[使用自定义接入点](https://support.huaweicloud.com/model-call-maas/model-call-048.html#ZH-CN_TOPIC_0000002549717747)。 图2自定义接入点-model参数 ![](https://support.huaweicloud.com/model-call-maas/figure/zh-cn_image_0000002516575329.png "点击放大") | #### 支持模型 | **模型系列** | **模型名称** | 支持地域 | **model** **参数值** | |:---|:---|:---|:---| | Qwen3 | Qwen3-32B | 西南-贵阳一 | qwen3-32b | | Qwen3 | Qwen3-30B-A3B | 西南-贵阳一 | qwen3-30b-a3b | #### 创建聊天对话请求 - 鉴权说明 MaaS推理服务支持使用API Key鉴权，鉴权头采用如下格式： ``` 'Authorization': 'Bearer 该服务所在Region的ApiKey' ``` - 请求参数和响应参数说明如下： 表2请求参数说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | model | 是 | String | **参数解释：** 调用时的模型参数。取值请参见上方[表1]。 **约束限制：** 不涉及。 **取值范围**： 取值请参见[支持模型]。 **默认取值：** 不涉及。 | | messages | 是 | Array | **参数解释：** 请求输入的问题，其中role为角色，content为对话内容。示例如下： ``` "messages": [ {"role": "system","content": "你是一个乐于助人的AI助手"}, {"role": "user","content": "9.11和9.8哪个大？"} ] ``` 更多信息，请参见[表3]。 **约束限制：** 不涉及。 | | messages.prefix | 否 | Boolean | **参数解释：** 控制是否开启续写模式：用户提供assistant开头的消息，让模型基于该开头和输入指令来补全其余的部分。 **约束限制：** 使用该功能时，需确保messages列表里最后一条消息的role为assistant，并设置最后一条消息的prefix参数为True，示例如下： ``` messages = [ {"role": "user", "content": "写一段python代码"}, {"role": "assistant", "content": "```python\n", "prefix": True} ] ``` **取值范围**： - True：开启前缀续写。 - False：不开启前缀续写。 **默认取值：** False | | stream_options | 否 | Object | **参数解释：** 该参数用于在流式输出时是否展示使用的Token数目。 **约束限制：** 只有当字段"stream"为"True"时，该参数才会生效。如果您需要统计流式输出模式下的Token数目，可将该参数配置为stream_options={"include_usage":True}。更多信息，请参见[表4]。 | | max_tokens | 否 | Int | **参数解释：** 当前任务允许生成Token数上限，包括模型输出的Tokens和深度思考的Reasoning Tokens。 **约束限制：** 不涉及。 **取值范围**： 各个模型取值不同，详情请参见MaaS控制台模型详情页的**最大输出长度**。 **默认取值：** 不涉及。 | | top_k | 否 | Int | **参数解释：** 控制模型生成时每次只从概率最高的k个词里挑选，用来控制生成文本的随机性。取值越大，生成的随机性越高；取值越小，生成的确定性越高。 **约束限制：** 不涉及。 **取值范围：** \>=0 **默认取值：** 不涉及。 | | top_p | 否 | Float | **参数解释：** 核采样概率阈值，用于控制模型生成内容的多样性，和temperature参数类似，但原理不同，可以更精细地控制模型输出的词汇范围。 设置值接近0时，模型只从概率最高的极少数词中采样，输出非常保守、确定性强。设置值接近1时，则几乎不限制词库，输出更随机、更发散。 **约束限制：** 建议仅调整temperature或top_p其中之一，不建议两者都修改。 **取值范围：** (0,1.0\] **默认取值：** 1.0：表示考虑所有Tokens。 | | temperature | 否 | Float | **参数解释：** 模型采样温度。设置的值越高，模型输出越随机；设置的值越低，输出越确定。 **约束限制：** 通常情况只建议调整temperature或top_p，不要同时修改两个参数。 **取值范围：** \[0,2.0\]。 取值建议：Qwen3系列建议值为0.6，Qwen2.5-VL系列建议值为0.2。 **默认取值：** 1.0 | | stop | 否 | None/String/List | **参数解释：** 用于停止生成的字符串列表。返回的输出将不包含停止字符串。 例如，设置为\["你"，"好"\]时，在生成文本过程中，遇到"你"或者"好"将停止文本生成。 **约束限制：** 不涉及。 | | stream | 否 | Boolean | **参数解释：** 是否开启流式推理。 **约束限制：** 不涉及。 **取值范围：** - False：不开启流式推理。 - True：开启流式推理。 **默认取值：** False | | n | 否 | Int | 为每个输入的消息生成的响应数。 - 不使用beam_search场景下，n取值建议为1≤n≤10。如果n\>1时，必须确保不使用greedy_sample采样，即top_k \> 1，temperature \> 0。 - 使用beam_search场景下，n取值建议为1\ 模型详情"页面的"版本"区域，查看"深度思考模式"对应的说明。 | 表3请求参数messages说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | role | 是 | String | **参数解释：** 发送消息的角色。 **约束限制：** 不涉及。 **取值范围：** - system：开发人员输入的指令，例如模型应遵循的答复格式、扮演的角色等。 - user：用户输入的消息，包括提示词和上下文信息。 - assistant：模型生成的回复内容。 - tool：模型调用工具返回的信息。 **默认取值**： 不涉及。 | | content | 是 | String | **参数解释：** 对应角色的消息内容。 **约束限制：** 不涉及。 **取值范围：** - 当role为system时：给AI模型设定的人设。 ``` { "role": "system", "content": "你是一个乐于助人的AI助手" } ``` - 当role为user时：用户输入的问题。 - 文本对话： ``` { "role": "user", "content": "9.11和9.8哪个大？" } ``` - 图像理解： 支持图片格式：png、jpeg、jpg、webp、bmp、tiff。 支持使用图片的Base64编码内容或者公网可访问的图片地址。以下是两种方式的代码示例： - 使用图片的Base64编码内容： ``` { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": f"data:image/png;base64,{base64_image}" } }, { "type": "text", "text": "图像显示的是什么内容？" } ] } ``` Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法，用于将Base64编码的图像数据嵌入到URL中。示例如下： ``` # PNG图像 f"data:image/png;base64,{base64_image}" # JPEG图像 f"data:image/jpeg;base64,{base64_image}" # WEBP图像： f"data:image/webp;base64,{base64_image}" ``` - 使用公网可访问的图片地址： ``` { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/xxx.jpeg" } }, { "type": "text", "text": "图像显示的是什么内容？" } ] } ``` - 当role为assistant时：AI模型输出的答复内容。 ``` {"role": "assistant","content": "9.11大于9.8"} ``` - 当role为tool时：AI模型调用的工具响应信息。 ``` {"role": "tool", "content": "上海今天天气晴，气温10度"} ``` **默认取值：** 不涉及。 | 表4请求参数stream_options说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | include_usage | 否 | Boolean | **参数解释：** 流式响应是否输出Token用量信息。 **约束限制：** 不涉及。 **取值范围：** - True：输出Token用量信息。在每一个chunk会输出一个usage字段，显示累计消耗的Token统计信息。 - False：响应不显示消耗的Token统计信息。 **默认取值：** True | 表5响应参数说明 | **参数名称** | **类型** | 说明 | |:---|:---|:---| | id | String | **参数解释：** 本次请求的唯一标识。 **取值范围：** 不涉及。 | | object | String | **参数解释：** 对话类型。 **取值范围：** chat.completion | | created | Int | **参数解释：** 本次请求的创建时间，时间戳格式，示例：1782271333。 **取值范围：** 不涉及。 | | model | String | **参数解释：** 本次请求使用的模型参数。 **取值范围：** 本次请求使用的模型参数。 | | choices | Array | **参数解释：** 模型答复的内容，包含index和message两个参数，message中： - content为模型的正式答复内容。 - reasoning content为模型的深度思考内容（仅限DeepSeek系列模型）。 | | usage | Object | **参数解释：** 本次请求消耗的Token统计信息： - prompt tokens：输入所消耗的Token数量。 - completion tokens: 输出Token数量。 - total tokens：总Token数量（输入+输出）。 | | prompt_logprobs | Float | **参数解释：** 对数概率。用户可以借此衡量模型对其输出内容的置信度，或者探索模型给出的其他选项。 **取值范围：** 不涉及。 | #### Qwen3-30B-A3B文本生成（非流式）请求示例 此处以使用Qwen3-30B-A3B模型通过Python脚本、Curl命令和OpenAI SDK请求生成文本响应为例，展示文本生成模型的非流式基础用法。 - Python请求示例： ``` import requests import json if __name__ == '__main__': url = "https://api.modelarts-maas.com/v1/chat/completions" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key # Send request. headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {api_key}' } data = { "model": "qwen3-30b-a3b", # model参数 "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "你好"} ], "chat_template_kwargs": { "enable_thinking": False # 是否开启深度思考模式，默认开启 } } response = requests.post(url, headers=headers, data=json.dumps(data), verify=False) # Print result. print(response.status_code) print(response.text) ``` - Curl请求示例： ``` curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MAAS_API_KEY" \ -d '{ "model": "qwen3-30b-a3b", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "你好"} ], "chat_template_kwargs": { "enable_thinking": false } }' ``` - OpenAI SDK请求示例： ``` from openai import OpenAI base_url = "https://api.modelarts-maas.com/v1" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key client = OpenAI(api_key=api_key, base_url=base_url) response = client.chat.completions.create( model="qwen3-30b-a3b", # model参数 messages=[ {"role": "system", "content": "You are a helpful assistant"}, {"role": "user", "content": "你好"}, ], extra_body={ "chat_template_kwargs": { "enable_thinking": False # 是否开启深度思考模式，默认开启 } } ) print(response.choices[0].message.content) ``` #### Qwen2.5-VL-72B图像理解（非流式）请求示例 此处以使用Qwen2.5-VL-72B模型通过Python脚本、Curl命令和OpenAI SDK请求进行图像理解为例，展示图像理解模型的非流式基础用法。 - Python请求示例： ``` import requests import json import base64 # 图片转Base64编码格式 def encode_image(image_path): with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode("utf-8") base64_image = encode_image("test.png") if __name__ == '__main__': url = "https://api.modelarts-maas.com/v1/chat/completions" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key # Send request. headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {api_key}' } data = { "model": "qwen2.5-vl-72b", # model参数 "messages": [ { "role": "user", "content": [ { "type": "text", "text": "描述下图片里的内容" }, { "type": "image_url", # 需要注意，Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。 # Base64编码的PNG图像： f"data:image/png;base64,{base64_image}" # Base64编码的JPEG图像： f"data:image/jpeg;base64,{base64_image}" # Base64编码的WEBP图像： f"data:image/webp;base64,{base64_image}" # 公网图像地址： "https://example/xxx.png" "image_url": { "url": f"data:image/png;base64,{base64_image}" } } ] } ] } response = requests.post(url, headers=headers, data=json.dumps(data), verify=False) # Print result. print(response.status_code) print(response.text) ``` - Curl请求示例： ``` curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MAAS_API_KEY" \ -d '{ "model": "qwen2.5-vl-72b", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "描述下图片里的内容"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,$BASE64_IMAGE"}} ] } ] }' ``` - OpenAI SDK请求示例： ``` import base64 from openai import OpenAI base_url = "https://api.modelarts-maas.com/v1" # API地址 api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key # 图片转Base64编码格式 def encode_image(image_path): with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode("utf-8") base64_image = encode_image("test.png") client = OpenAI(api_key=api_key, base_url=base_url) response = client.chat.completions.create( model = "qwen2.5-vl-72b", # model参数 messages = [ { "role": "user", "content": [ {"type": "text", "text": "描述下图片里的内容"}, { "type": "image_url", # 需要注意，Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。 # Base64编码的PNG图像： f"data:image/png;base64,{base64_image}" # Base64编码的JPEG图像： f"data:image/jpeg;base64,{base64_image}" # Base64编码的WEBP图像： f"data:image/webp;base64,{base64_image}" # 公网图像地址： "https://example/xxx.png" "image_url": { "url": f"data:image/png;base64,{base64_image}" } } ] } ] ) print(response.choices[0].message.content) ```