文档首页/ MaaS模型即服务/ 模型调用/ 模型API调用规范/ 对话Chat/Post/ MaaS标准API V1
更新时间：2026-08-20 GMT+08:00
查看PDF
分享

MaaS标准API V1

本文介绍对话Chat相关API的调用规范。

MaaS标准API V1接口不再演进，建议优先使用MaaS标准API V2接口。

接口信息

表1 接口信息

名称

说明

取值

API地址

调用模型服务的API地址。

https://api-ap-southeast-1.modelarts-maas.com/v1/chat/completions

model参数

model参数调用名称。

model取值请参见如何获取模型参数。

创建聊天对话请求

  • 鉴权说明

    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。

    默认取值：

    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<n≤10。如果n=1，会导致推理请求失败。
      说明：
      • n建议取值不超过10，n值过大会导致性能劣化，显存不足时，推理请求会失败。

    use_beam_search

    否

    Boolean

    参数解释：

    是否使用beam_search替换采样。

    约束限制：

    使用该参数时，如下参数必须按要求设置。

    • n：大于1
    • top_p：1.0
    • top_k：-1
    • temperature：0.0

    取值范围：

    • False：不使用beam_search替换采样。
    • True：使用beam_search替换采样。

    默认取值：

    False

    presence_penalty

    否

    Float

    参数解释：

    存在惩罚系数，是一个用于控制模型输出多样性的重要参数。降低模型重复谈论已经出现过的话题或词汇的概率，从而鼓励模型去谈论“新事物”。

    只要某个词在之前已经生成的文本中出现过至少一次，模型就会对该词施加一个固定的惩罚，降低它再次被选中的概率。模型会根据新Token截止目前是否已出现对其进行惩罚。如果值为正，会增加模型生成新内容的可能性。

    约束限制：

    不涉及。

    取值范围：

    [-2,2]

    • 0：不做任何惩罚
    • 正值：增加惩罚，值越大，模型越倾向于引入新的词汇和话题，避免内容重复。
    • 负值：减少惩罚（实际上是奖励）。模型更倾向于重复使用已经出现过的词汇，这通常会导致文本极其啰嗦和重复（一般不推荐使用）。

    默认取值：

    0.0

    frequency_penalty

    否

    Float

    参数解释：

    频率惩罚系数，是一个用于控制模型输出多样性的重要参数。

    根据词语已经出现的次数，按比例降低该词再次出现的概率。出现的次数越多，再次被使用的概率就越低。

    约束限制：

    不涉及。

    取值范围：

    [-2.0,2.0]

    • 0：不做任何惩罚。
    • 正值：增加惩罚，值越大，模型越倾向于引入新的词汇和话题，避免内容重复。
    • 负值：减少惩罚（实际上是奖励）。模型更倾向于重复使用已经出现过的词汇，这通常会导致文本极其啰嗦和重复（一般不推荐使用）。

    默认取值：

    0.0

    length_penalty

    否

    Float

    参数解释：

    表示在beam search过程中，对于较长的序列，模型会给予较大的惩罚。

    约束限制：

    使用该参数时，必须添加如下三个参数，且必须按要求设置。

    • top_k：-1
    • use_beam_search：true
    • best_of：大于1

    取值范围：

    不涉及。

    默认取值：

    1.0

    thinking

    否

    Object

    参数解释：

    控制模型是否开启或关闭深度思考模式。

    约束限制：

    不涉及。

    thinking.type

    是

    String

    参数解释：

    控制模型是否开启或关闭深度思考模式。

    约束限制：

    不涉及。

    取值范围：

    • enabled：开启思考模式，模型一定先思考后回答。
    • disabled：关闭思考模式，模型直接回答问题，不会进行思考。

    默认取值：

    不同模型的默认值不同，您可以登录MaaS控制台，在“模型广场 > 模型详情”页面的“版本”区域，查看“深度思考模式”对应的说明。
    表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

    参数解释：

    对数概率。用户可以借此衡量模型对其输出内容的置信度，或者探索模型给出的其他选项。

    取值范围：

    不涉及。
父主题： 对话Chat/Post