MaaS_DB /chat/completions

Request URL

POST
https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions

Request Header

Parameter	Value
Authorization	Bearer
Content-Type	multipart/form-data

Request Body

Request Parameters

model string Required

The model ID (Model ID) to call. For multiple applications and fine-grained management scenarios, it is recommended to use Endpoint ID for calling.

messages object[] Required

Message list. Different models support different types of messages, such as text, images, video, audio, etc.

Message Types

System Message (system)

Instructions that the model should follow, including the role to play, background information, etc.

messages.role string Required

The role of the message sender; should be system here.

messages.content string / object[] Required

The content of the system message.

Content Types

Plain Text Content string

Plain text message content.

Multimodal Content object[]

Supports text, image, video, audio, and other modal content.

Modal Content Objects

Text Part (text)

messages.content.text string Required

The content of the text modal part.

messages.content.type string Required

Content modality; should be text here.

Image Part (image_url)

messages.content.type string Required

Content modality; should be image_url here.

messages.content.image_url object Required

The content of the image modality. Image input supports two fields: file_id and url; one of them must be provided.

Properties

messages.content.image_url.file_id string

File ID. The id returned after uploading a file via the Files API.

Note: Chat API supports passing files from Volcengine TOS Bucket via file_id. The models that support this capability are as follows: - doubao-seed-2.0-mini series: doubao-seed-2-0-mini-260428 and later versions. - doubao-seed-2.0-lite series: all versions supported. - doubao-seed-2.0-pro series: all versions supported.

messages.content.image_url.url string

Image URL sent to the model. Supported formats: image link or Base64-encoded image.

messages.content.image_url.detail string

Value range: low, high, xhigh. Controls the granularity of image understanding.

messages.content.image_url.image_pixel_limit object / null Default null

The pixel range of the image input to the model. If not within this range, the image will be proportionally scaled.

Note: The image pixel range must be within [196, 36,000,000], otherwise an error will be reported directly. This takes priority over the detail field.

max_pixels integer: Maximum pixel limit for the input image.
min_pixels integer: Minimum pixel limit for the input image.

Video Part (video_url)

messages.content.type string Required

Content modality; should be video_url here.

messages.content.video_url object Required

The content part of the video message. Video input supports two fields: file_id and url; one of them must be provided.

Properties

messages.content.video_url.file_id string

File ID.

Note: Chat API supports passing files from Volcengine TOS Bucket via file_id. The models that support this capability are the same as the image part.

messages.content.video_url.url string

Video URL sent to the model. Supported formats: video link or Base64-encoded video.

messages.content.video_url.fps float / null Default 1

Value range: [0.2, 5]. Frame extraction frequency; see Video Understanding for details. Higher values are more sensitive to visual changes.

Audio Part (input_audio)

messages.content.type string Required

Content modality; should be input_audio here.

messages.content.input_audio object Required

The content of the audio modality. Audio input supports three fields: file_id, url, and data; one of them must be provided.

Properties

messages.content.input_audio.file_id string

File ID.

Note: Chat API supports passing files from Volcengine TOS Bucket via file_id. The models that support this capability are the same as the image part.

messages.content.input_audio.url string

URL of the audio content.

messages.content.input_audio.data string

Base64 encoding of the audio content.

messages.content.input_audio.format string

Audio format. This parameter is required when using data. Supported audio format MIME types are as follows:

Pure audio formats: mp3, wav, aac, m4a, pcm, ac3, alac
Video embedded audio formats: mp3, wav, aac, m4a

Note: - File size must not exceed 25 MB. - Total audio duration per request must not exceed 120 minutes; only pure audio duration is counted.

File Part (file)

messages.content.type string Required

Message modality; should be file here.

messages.content.file object Required

The content of the file modality. Currently only PDF files are supported. File input supports three fields: file_id, file_data, and file_url; one of them must be provided.

Properties

messages.content.file.file_id string

File ID.

Note: Chat API supports passing files from Volcengine TOS Bucket via file_id. The models that support this capability are the same as the image part.

messages.content.file.file_data string

Base64 encoding of the file content. Single file size must not exceed 50 MB.

messages.content.file.filename string

Filename. This parameter is required when using file_data.

messages.content.file.file_url string

Accessible URL of the file. The corresponding file size must not exceed 50 MB.

User Message (user)

Messages sent by the user role. Different models support different field types.

messages.role string Required

The role of the message sender; should be user here.

messages.content string / object[] Required

User message content. Supports plain text or multimodal content; the specific structure is the same as the content field in system messages.

Model Message (assistant)

Messages returned by the model role in historical conversations. Used to maintain conversation consistency.

Properties

messages.role string Required

The role of the message sender; should be assistant here.

messages.content string / array

The content of the model message.

messages.reasoning_content string

Chain-of-thought content in the model message. Only models doubao-seed-1.8, deepseek-v3.2, doubao-seed-2.0, and doubao-seed-2.1 support this field.

messages.encrypted_content string

The original thinking content after encryption and compression processing. Supported for output since version doubao-seed-2-0-lite-260428.

Note: - The encrypted_content passed back must be valid; tampering or inability to restore will return an error: Invalid signature. - encrypted_content takes priority over reasoning_content; when encrypted_content is passed back, reasoning_content will be ignored.

messages.tool_calls object[]

Tool call part in the model message.

Properties

messages.tool_calls.function object Required

Function information to be called, returned by the model.

name string Required: The name of the function to be called.
arguments string Required: The input parameters of the function to be called, in JSON format.

Note: The model does not always generate valid JSON and may fabricate undefined parameters. It is recommended to validate parameters before calling the function.

messages.tool_calls.id string Required

The ID of the tool to be called, generated by the model.

messages.tool_calls.type string Required

Message type; currently only function is supported.

Tool Message (tool)

Messages returned from tool calls in historical conversations. Used in tool calling scenarios.

messages.role string Required

The role of the message sender; should be tool here.

messages.content string / array Required

Messages returned by the tool.

messages.tool_call_id string Required

The ID generated when the model generates a tool call request. The same ID must be attached to the tool call response to associate the tool structure with the model request, avoiding information confusion during multi-tool calls.

thinking object Default {"type":"enabled"}

Controls whether the model enables deep thinking mode.

Support and default values vary by model.

Properties

thinking.type string Required

Value range: enabled, disabled, auto.

enabled: Enables thinking mode; the model is forced to think before responding.
disabled: Disables thinking mode; the model responds directly without thinking.
auto: Automatic thinking mode; the model autonomously determines whether thinking is needed based on the question, responding directly to simple questions.

stream boolean / null Default false

Whether the response content is returned via streaming:

false: The model returns the result all at once after generating all content.
true: Returns model-generated content chunk by chunk following the SSE protocol, ending with a data: [DONE] message. When stream is true, you can set the stream_options field to obtain token usage statistics.

stream_options object / null Default null

Options for streaming responses. When stream is true, you can set the stream_options field.

Properties

stream_options.include_usage boolean / null Default false

Whether to output token usage information for this request before the output ends during streaming.

true: An additional chunk is returned before the data: [DONE] message. In this chunk, the usage field outputs the token usage for the entire request, and the choices field is an empty array.
false: No chunk returns token usage information before the output ends.

stream_options.chunk_include_usage boolean / null Default false

Whether each output chunk includes cumulative token usage information from the start of this request to the moment this chunk is output during streaming.

true: The returned usage field outputs the cumulative token usage from the start of this request to the moment this chunk is output.
false: Token usage information is not returned in every chunk.

max_tokens integer / null Default 4096

Value range: varies by model.

Maximum length of model response (in tokens).

Note: - Model response does not include chain-of-thought content. Model response = model output - model chain-of-thought (if any) - The total length of output tokens is also limited by the model's context length.

max_completion_tokens integer / null

Value range: [1, 65,536].

Controls the maximum length of model output (including both model response and chain-of-thought content length, in tokens).

After configuring this parameter, the model can output extra-long content. The max_tokens default value becomes ineffective, and the model outputs content (response and chain-of-thought) as needed until reaching the max_completion_tokens value.

Cannot be set simultaneously with the max_tokens field.

stop string / string[] / null Default null

The model will stop generating when it encounters the string specified by the stop field; the stop word itself will not be output. A maximum of 4 strings are supported.

Deep thinking models do not support this field.

["hello", "weather"]

reasoning_effort string / null

Limits the workload of thinking. Reducing thinking depth improves speed and uses fewer tokens for thinking.

Value range: none (only supported by some models), minimal, low, medium, high, xhigh (only supported by some models), max (only supported by some models).

none: Disables thinking. This parameter only takes effect for specified models; passing it to non-compatible models will have no effect. Supported model: glm-5-2-260617.
minimal: Disables thinking; responds directly.
low: Lightweight thinking; focuses on fast response.
medium: Balanced mode; balances speed and depth.
high: Deep analysis; handles complex problems.
xhigh: Higher degree of thinking. This parameter only takes effect for specified models; passing it to non-compatible models will have no effect. Supported model: glm-5-2-260617.
max: Highest degree of thinking; suited for high-difficulty reasoning tasks. This parameter only takes effect for specified models; passing it to non-compatible models will have no effect. Supported model list:
glm-5-2-260617
deepseek-v4-pro-260425
deepseek-v4-flash-260425

response_format object Default {"type": "text"} beta

Specifies the model response format.

Response Format Description

Text Format (text)

The model responds with text format content by default.

response_format.type string Required

Should be text here.

JSON Object Format (json_object)

The model response content is organized as a JSON object structure.

This capability is still in beta; please use with caution in production environments.

response_format.type string Required

Should be json_object here.

JSON Schema Format (json_schema)

The model response content is organized as a JSON object structure, following the JSON structure defined by the schema field.

response_format.type string Required

Should be json_schema here.

response_format.json_schema object Required

Definition of the JSON structure.

name string Required: User-defined name of the JSON structure.
description string / null: Description of the response purpose; the model will use this description to determine how to respond in this format.
schema object Required: JSON format definition of the response format, described as a JSON Schema object.
strict boolean / null Default false: Whether to enable strict adherence mode when generating output.
true: The model will always strictly follow the format defined in the schema field.
false: The model will try its best to follow the structure defined in the schema field.

frequency_penalty float / null Default 0

Value range: [-2.0, 2.0].

Note: doubao-seed-1.8 and doubao-seed-2.0 series models do not support this field.

Frequency penalty coefficient. If the value is positive, it penalizes new tokens based on their frequency of appearance in the text, thereby reducing the likelihood of the model repeating verbatim.

presence_penalty float / null Default 0

Value range: [-2.0, 2.0].

Note: doubao-seed-1.8 and doubao-seed-2.0 series models do not support this field.

Presence penalty coefficient. If the value is positive, it penalizes new tokens based on whether they have appeared in the text so far, thereby increasing the likelihood of the model discussing new topics.

temperature float / null Default 1

Value range: [0, 2].

Note: When calling the following models, the field value is fixed at 1, and manually specified parameter values will be ignored. - doubao-seed-2-0-pro-260215 - doubao-seed-2-0-lite-260215

Sampling temperature. Controls the degree of smoothing applied to the probability distribution of each candidate token during text generation. When set to 0, the model only considers the token with the highest log probability.

Higher values (e.g., 0.8) make the output more random, while lower values (e.g., 0.2) make the output more focused and deterministic.

It is generally recommended to adjust only temperature or top_p, not both.

top_p float / null Default 0.7

Value range: [0, 1].

Note: When calling the following models, the field value is fixed at 0.95, and manually specified parameter values will be ignored. - doubao-seed-2-0-pro-260215 - doubao-seed-2-0-lite-260215 - doubao-seed-1-8-251228

Nucleus sampling probability threshold. The model considers token results within the top_p probability mass. When set to 0, the model only considers the token with the highest log probability.

0.1 means only the top 10% of tokens by probability mass are considered. Higher values increase randomness in generation, while lower values increase determinism. It is generally recommended to adjust only temperature or top_p, not both.

logprobs boolean / null Default false

Models with deep thinking capability do not support this field.

Whether to return log probabilities of output tokens.

false: Does not return log probability information.
true: Returns the log probability of each output token in the message content.

top_logprobs integer / null Default 0

Models with deep thinking capability do not support this field. Value range: [0, 20].

Specifies the number of most likely tokens to return at each output token position, each with an associated log probability. The top_logprobs parameter can only be set when logprobs is true.

logit_bias map / null Default null

Models with deep thinking capability do not support this field.

Adjusts the probability of specified tokens appearing in the model output, making the generated content more aligned with specific preferences. The logit_bias field accepts a map value where each key is a token ID from the vocabulary (obtained via the tokenization API), and each value is the bias value for that token, with a range of [-100, 100].

-1 reduces the likelihood of selection, 1 increases the likelihood of selection; -100 completely prohibits selecting that token, 100 results in only that token being selectable. The actual effect of this parameter may vary by model.

{"<Token_ID>": -100}

tools array

Tools that the model can call. You need to configure this structure when you want the model to call tools.

Function Calling

tools.type string Required

Tool type; should be function here.

tools.function object Required

The model response may contain tools to be called.

name string Required: The name of the function to call.
description string: Description of the function; the model uses this to determine whether to call this tool.
parameters object: Function request parameters, described in JSON Schema format.

Request Examples

Basic Conversation

curl https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $${your_ak}" \
  -d '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
  }'

Streaming Output

curl https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $${your_ak}" \
  -d $'{
    "messages": [
        {
            "content": "You are a helpful assistant.",
            "role": "system"
        },
        {
            "content": "hello",
            "role": "user"
        }
    ],
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "stream": true
}'

Continuation Mode

curl https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $${your_ak}" \
  -d $'{
    "messages": [
        {
            "content": "You are a calculator; please perform the calculation： 1 + 1",
            "role": "user"
        },
        {
            "content": "=",
            "role": "assistant"
        }
    ],
    "model": "MaaS_DB_seed_2.0_pro_20260215"
}'

Image Understanding

curl https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $${your_ak}" \
  -d $'{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "messages": [
        {
            "content": [
                {
                    "image_url": {
                        "url": "<demo_img.png>"
                    },
                    "type": "image_url"
                },
                {
                    "text": "waht this picture see?",
                    "type": "text"
                }
            ],
            "role": "user"
        }
    ]
}'

Video Understanding

curl https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $${your_ak}" \
   -d '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "messages": [
        {
            "role": "user",
            "content": [                
                {"type": "video_url","video_url": {"url":  "<demo_video_input.mp4>"},"fps": "2"},
                {"type": "text", "text": "What is in the video?"}
            ]
        }
    ],
    "max_tokens": 300
  }'

Response Examples

Chat Completions API Response Example

{
    "id": "chatcmpl-jHSjQBZPOTbneWEgIm0XDSdX",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! How can I help you today?",
                "reasoning_content": "We need to parse the user's message. It's \"Hello!\" That's the entire query. The assistant must respond appropriately. The system instructions are: \"You are an AI assistant. Help the user with their queries.\" So I should respond in a friendly, helpful manner. No complex task. Just a greeting. I'll respond with a hello and an offer to help."
            },
            "finish_reason": "stop",
            "native_finish_reason": "stop"
        }
    ],
    "created": 1783583018,
    "model": "MaaS_Deepseek_V4_pro_20260424",
    "object": "chat.completion",
    "system_fingerprint": "fp_9954b31ca7_prod0820_fp8_kvcache_20260402",
    "usage": {
        "prompt_tokens": 6,
        "completion_tokens": 86,
        "total_tokens": 92,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "image_tokens": 0,
            "reasoning_tokens": 76,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0,
            "image_tokens": 0
        },
        "prompt_cache_hit_tokens": 0,
        "prompt_cache_miss_tokens": 6
    }
}