MaaS Standard API V1

Constraints

This function is only available in the CN-Hong Kong region.

API Information

Supported Models

You can log in to the MaaS console and enable the following models on the Model Inference > Real-Time Inference > Built-in Services page. On the model details page in the Model Square, you can view detailed information about the models.

Creating a Chat Request

• Authentication description

  MaaS inference services support API key authentication. The authentication header is in the following format:

  'Authorization': 'Bearer API key of the region where the service is deployed'

• The request and response parameters are as follows.

  Table 2 Request parameters

  Parameter	Mandatory	Type	Description
  model	Yes	String	Definition Model to call. For details about the value, see Table 1. Constraints N/A Range For details about the options of model, see Supported Models. Default Value N/A
  messages	Yes	Array	Definition Input question. role shows the role, and content shows the dialog content. Example: "messages": [ {"role": "system","content": "You are a helpful AI assistant."}, {"role": "user","content": "Which number is larger, 9.11 or 9.8?"} ] For more information, see Table 3. Constraints N/A
  messages.prefix	No	Boolean	Definition Controls whether to enable continuation mode. In this mode, the user provides a message starting with assistant, and the model completes the rest based on that beginning and the input instruction. Constraints To use this feature, ensure that the last message in the messages list has the role set to assistant and the prefix parameter set to true. Example: messages = [ {"role": "user", "content": "Write a snippet of Python code"}, {"role": "assistant", "content": "```python\n", "prefix": True} ] Range True: Enable prefix continuation. False: Disable prefix continuation. Default Value False
  stream_options	No	Object	Definition Specifies whether to display the number of used tokens during streaming output. Constraints This parameter is only valid when stream is set to True. You need to set stream_options to {"include_usage": true} to print the number of tokens used. For more information, see Table 4.
  max_tokens	No	Int	Definition Maximum number of tokens that can be generated for the current task, including tokens generated by the model and reasoning tokens for deep thinking. Constraints N/A Range The value varies depending on the model. For details, see the maximum output length on the model details page of the MaaS console. Default Value N/A
  top_k	No	Int	Definition Controls the model to select only from the top k most probable tokens, influencing the randomness of the generated text. Higher values increase randomness, while lower values enhance determinism. Constraints N/A Range >=0 Default Value N/A
  top_p	No	Float	Definition Nucleus sampling probability threshold, used to control the diversity of the content generated by the model. Similar to the temperature parameter, it influences randomness, but offers finer control by dynamically adjusting the pool of possible tokens. Setting this value near 0 restricts sampling to the highest-probability tokens, yielding highly predictable and deterministic text. Setting this value near 1 allows the model to sample from virtually the entire vocabulary, resulting in higher randomness and more creative, divergent outputs. Constraints It is recommended that you adjust either temperature or top_p. Range (0,1.0] Default Value 1.0: All tokens are considered.
  temperature	No	Float	Definition Model sampling temperature. The higher the value, the more random the model output; the lower the value, the more deterministic the output. Constraints Adjust either temperature or top_p separately for best results, not both at once. Range 0 to 2.0 Recommended value of temperature: 0.6 for DeepSeek-V3 and Qwen3 series, and 0.2 for Qwen2.5-VL series. Default Value 1.0
  stop	No	None/String/List	Definition A list of strings used to stop generation. The output does not contain the stop strings. For example, if the value is set to ["You," "Good"], text generation will stop once either You or Good is reached. Constraints N/A
  stream	No	Boolean	Definition Controls whether to enable streaming inference. Constraints N/A Range False: Disable streaming inference. true: Enable streaming inference. Default Value False
  n	No	Int	Number of responses generated for each input message. If beam_search is not used, the recommended value range of n is 1 ≤ n ≤10. If n is greater than 1, ensure that greedy_sample is not used for sampling, that is, top_k is greater than 1 and temperature is greater than 0. If beam_search is used, the recommended value range of n is 1 < n ≤ 10. If n is 1, the inference request will fail. NOTE: For optimal performance, keep n at 10 or below. Large values of n can significantly slow down processing. Inadequate video RAM may cause inference requests to fail. You cannot set n higher than 1 for DeepSeek-V3.
  use_beam_search	No	Boolean	Definition Controls whether to use beam_search to replace sampling. Constraints When this parameter is used, the following parameters must be configured as required: n: > 1 top_p: 1.0 top_k: -1 temperature: 0.0 NOTE: You cannot set n higher than 1 for DeepSeek-V3. Range False: Do not replace sampling with beam search. True: Replace sampling with beam search. Default Value False
  presence_penalty	No	Float	Definition Presence penalty coefficient, which is an important parameter used to control the diversity of model outputs. This reduces the probability that the model will repeatedly use previously mentioned tokens or topics, thereby encouraging it to generate new content. As long as a token has appeared at least once in the previously generated text, the model imposes a fixed penalty on it to reduce the probability of it being selected again. The model determines this penalty based solely on whether the token has appeared so far. A positive value increases the likelihood of the model generating novel content. Constraints N/A Range [-2,2] 0: No penalty is applied. Positive value: Increases the penalty. A larger value makes the model more likely to introduce new tokens and topics to avoid repetition. Negative value: Reduces the penalty (acting as a reward). The model becomes more inclined to reuse previously generated words, which often results in repetitive and verbose text (generally not recommended). Default Value 0.0
  frequency_penalty	No	Float	Definition Frequency penalty coefficient, which is an important parameter used to control the diversity of model outputs. The probability of a token reappearing decreases proportionally based on its frequency in the generated text. The more frequently a token appears, the lower its likelihood of being used again. Constraints N/A Range [-2.0,2.0] 0: No penalty is applied. Positive value: Increases the penalty. A larger value makes the model more likely to introduce new tokens and topics to avoid repetition. Negative value: Reduces the penalty (acting as a reward). The model becomes more inclined to reuse previously generated words, which often results in repetitive and verbose text (generally not recommended). Default Value 0.0
  length_penalty	No	Float	Definition Imposes a larger penalty on longer sequences in a beam search process. Constraints When this parameter is used, the following parameters must be configured as required: top_k: -1 use_beam_search: true best_of: > 1 NOTE: You cannot set length_penalty for DeepSeek-V3. Range N/A Default Value 1.0
  thinking	No	Object	Definition Controls whether to enable the deep thinking mode for a model. Constraints N/A
  thinking.type	Yes	String	Definition Controls whether to enable the deep thinking mode for a model. Constraints N/A Range enabled: The deep thinking mode is enabled. The model must think before answering. disabled: The deep thinking mode is disabled. The model directly answers questions without thinking. Default Value The default value varies depending on the model. You can log in to the MaaS console and view the description of the deep thinking mode in the Version area on the Model Square > Model Details page. Figure 1 Checking the deep thinking mode

  Table 3 Request parameter messages

  Parameter	Mandatory	Type	Description
  role	Yes	String	Definition Role that sends a message. Constraints N/A Range system: developer-entered instructions like response formats and roles for the model to follow. user: user-entered messages including prompts and context information. assistant: responses generated by the model. tool: information returned by the tool when the model calls it. Default Value N/A
  content	Yes	String	Definition Message content of the corresponding role. Constraints N/A Range When role is set to system, this parameter indicates the AI model's personality. { "role": "system", "content": "You are a helpful AI assistant." } When role is set to user, this parameter indicates the question asked by the user. Text-based dialogue: { "role": "user", "content": "Which one is larger, 9.11 or 9.8?" } Image understanding: Supported image formats: PNG, JPEG, JPG, WEBP, BMP, and TIFF. Supported input methods: You can use either the Base64-encoded content of the image or a publicly accessible image URL. Below are code examples for both methods: Using Base64-encoded image content: { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": f"data:image/png;base64,{base64_image}" } }, { "type": "text", "text": "What does the image show?" } ] } The Base64-encoded image format (image/{format}) must match the Content Type in the supported image list. The f denotes a string formatting method used to embed the Base64-encoded image data into the URL. Example: # PNG image f"data:image/png;base64,{base64_image}" # JPEG image f"data:image/jpeg;base64,{base64_image}" # WEBP image: f"data:image/webp;base64,{base64_image}" Using a publicly accessible image URL: { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/xxx.jpeg" } }, { "type": "text", "text": "What does the image show?" } ] } When role is set to assistant, this parameter indicates the content generated by the AI model. {"role": "assistant","content": "9.11 is larger than 9.8."} When role is set to tool, this parameter indicates the responses returned by the tool when the model calls it. {"role": "tool", "content": "The weather in Shanghai is sunny today. The temperature is 10°C."} Default Value N/A

  Table 4 Request parameter stream_options

  Parameter	Mandatory	Type	Description
  include_usage	No	Boolean	Definition Specifies whether the streaming response includes token usage information. Constraints N/A Range True: The token usage information is included in the response. Each chunk contains a usage field that shows the total token usage. False: The token usage information is not included in the response. Default Value True

  Table 5 Response parameters

  Parameter	Type	Description
  id	String	Definition Unique identifier of this request. Range N/A
  object	String	Definition Dialog type. Range chat.completion
  created	Int	Definition Time when the request is created, in timestamp format, for example, 1782271333. Range N/A
  model	String	Definition Model ID used in this request. Range Model ID used in this request.
  choices	Array	Definition Model output, including the index and message parameters. In message: content is the model's final reply. reasoning content is the model's deep thinking content (for DeepSeek models only).
  usage	Object	Definition Statistics on tokens consumed by this request: prompt tokens: number of input tokens. completion tokens: number of output tokens. total tokens: total number of tokens (including input and output tokens).
  prompt_logprobs	Float	Definition Log probability. You can use this to measure the model's confidence in its output or to explore other options the model provides. Range N/A

DeepSeek-V3 Text Generation (Non-Streaming) Request Example

This section demonstrates the basic non-streaming usage of a text generation model, using the DeepSeek-V3 model as an example to request a text response via a Python script, cURL command, or OpenAI SDK.

• Python request example:

  import requests
  import json
  
  if __name__ == '__main__':
      url = "https://api-ap-southeast-1.modelarts-maas.com/v1/chat/completions" # API address
      api_key = "MAAS_API_KEY"  # Replace MAAS_API_KEY with the obtained API key.
  
      # Send a request.
      headers = {
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {api_key}' 
      }
      data = {
          "model":"deepseek-v3", # Model name
          "messages": [
              {"role": "system", "content": "You are a helpful assistant."},
              {"role": "user", "content": "Hello"}
          ]
      }
      response = requests.post(url, headers=headers, data=json.dumps(data), verify=False)
  
      # Print result.
      print(response.status_code)
      print(response.text)

• cURL request example:

  curl -X POST "https://api-ap-southeast-1.modelarts-maas.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{ 
      "model": "deepseek-v3",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"}
      ]
  }'

• OpenAI SDK request example:

  from openai import OpenAI
  
  base_url = "https://api-ap-southeast-1.modelarts-maas.com/v1" # API address
  api_key = "MAAS_API_KEY" # Replace MAAS_API_KEY with the obtained API key.
  
  client = OpenAI(api_key=api_key, base_url=base_url)
  
  response = client.chat.completions.create(
      model="deepseek-v3", # Model name
      messages=[
          {"role": "system", "content": "You are a helpful assistant"},
          {"role": "user", "content": "Hello"}
      ]
  )
  
  print(response.choices[0].message.content)

DeepSeek-V3 Text Generation (Streaming) Request Example

This section demonstrates the basic streaming usage of a text generation model, using the DeepSeek-V3 model as an example to request a text response via a Python script or cURL command.

• Python request example:

  from openai import OpenAI
  
  base_url = "https://api-ap-southeast-1.modelarts-maas.com/v1" # API address
  api_key = "MAAS_API_KEY" # Replace MAAS_API_KEY with the obtained API key.
  
  client = OpenAI(api_key=api_key, base_url=base_url)
  
  response = client.chat.completions.create(
      model="deepseek-v3", # Model name
      messages=[
          {"role": "system", "content": "You are a helpful assistant"},
          {"role": "user", "content": "Hello"}
      ],
      stream = True
  )
  
  for chunk in response:
      if not chunk.choices:
          continue
  
      print(chunk.choices[0].delta.content, end="")

• cURL request example:

  curl -X POST "https://api-ap-southeast-1.modelarts-maas.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{ 
      "model": "deepseek-v3",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"}
      ],
      "stream": true,
      "stream_options": { "include_usage": true }
  }'

DeepSeek-V3.1 Text Generation (Non-Streaming) Request Example

This section demonstrates the basic non-streaming usage of a text generation model, using the DeepSeek-V3.1 model as an example to request a text response via a Python script, cURL command, or OpenAI SDK.

• Python request example:

  import requests
  import json
  
  if __name__ == '__main__':
      url = "https://api-ap-southeast-1.modelarts-maas.com/v1/chat/completions"  # API address
      api_key = "MAAS_API_KEY"  # Replace MAAS_API_KEY with the obtained API key.
  
      # Send a request.
      headers = {
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {api_key}'
      }
      data = {
          "model": "deepseek-v3.1-terminus",  # Model
          "messages": [
              {"role": "system", "content": "You are a helpful assistant."},
              {"role": "user", "content": "Hello"}
          ],
         "thinking": {   
             "type": "enabled" 
         }  
      }
      response = requests.post(url, headers=headers, data=json.dumps(data), verify=False)
  
      # Print result.
      print(response.status_code)
      print(response.text)

• cURL request example:

  curl -X POST "https://api-ap-southeast-1.modelarts-maas.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{
      "model": "deepseek-v3.1-terminus",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"}
      ],
      "thinking": {   
             "type": "enabled" 
       }
    }'

• OpenAI SDK request example:

  from openai import OpenAI
  
  base_url = "https://api-ap-southeast-1.modelarts-maas.com/v1"  # API address
      api_key = "MAAS_API_KEY"  # Replace MAAS_API_KEY with the obtained API key.
  
  client = OpenAI(api_key=api_key, base_url=base_url)
  
  response = client.chat.completions.create(
      model="deepseek-v3.1-terminus",  # Model
      messages=[
          {"role": "system", "content": "You are a helpful assistant"},
          {"role": "user", "content": "Hello"},
      ],
      extra_body={
          "chat_template_kwargs": {
              "thinking": True  # Specifies whether to enable deep thinking. It is disabled by default.
          }
      }
  )
  
  print(response.choices[0].message.content)

Response Example

{
    "id":"chat-71406e38b0d248c9b284709f8435****",
    "object":"chat.completion",
    "created":1740809549,
    "model":"deepseek-v3",
    "choices":[
        {
            "index":0,
            "message":{
                "role":"assistant",
                "content":"\n\n Compare 9.11 and 9.8.:\n\n1. **Compare the integer part**: The integer part of both is 9, which is equal.\n2. **Compare the tenths place**:\n - The tenths place of 9.11 is **1**\n - 9.8 can be considered as 9.80, and its tenths place is **8**\n - **8 > 1**, so 9.8 is larger.\n\n**Conclusion**:\n**9.8 > 9.11**\n(When comparing decimals, line up the digits and compare them directly.)",
                "reasoning_content": "Well, I now need to compare 9.11 and 9.8 which is larger. First of all, I have to recall the method of comparing decimals. When comparing decimals, start by comparing the integer parts. If the integer parts are the same, compare the tenths and hundredths of the decimal parts in sequence until the larger number is determined.\n\nThe integer parts of the two numbers are both 9, so they are the same. Next, compare the tenths. The tenth digit of 9.11 is 1, while the tenth digit of 9.8 is 8. This can be problematic, as some people might directly treat 9.8 as 9.80, or focus on comparing the digits in the tenths place.\n\nNow, comparing the tenths place, 9.8 has an 8, while 9.11 has a 1. Clearly, 8 is greater than 1. So, should we conclude that 9.8 is greater than 9.11? \n\n However, it is important to note that some people might incorrectly assume that the more decimal places a number has, the larger its value. But this is not true; for instance, 0.9 is greater than 0.8999. Thus, having more decimal places does not necessarily mean a larger value. \n\n Additionally, the decimal parts of the two numbers can be aligned to have the same number of digits for comparison. For instance, 9.8 can be written as 9.80, where the tenths place is 8 and the hundredths place is 0. On the other hand, for 9.11, the tenths place is 1 and the hundredths place is 1. Since 8 in the tenths place is greater than 1, 9.80 (which is 9.8) is greater than 9.11.\n\nTherefore, the final conclusion is that 9.8 is larger than 9.11.\n",
                "tool_calls":[]
                },
                "logprobs":null,
                "finish_reason":"stop",
                "stop_reason":null        
        }
    ],
    "usage":{
        "prompt_tokens":21,
        "total_tokens":437,
        "completion_tokens":416
        },
    "prompt_logprobs":null
}