Skip to content

MaaS_DB Response

Request URL

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

Request Header

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

Request Body

Request Parameters

model string Required

The ID (Model ID) of the model you need to call.

input string / array Required

The input content, the information that the model needs to process.

instructions string / null

Inserts a system message or developer instruction as the first message in the model context. When used with previous_response_id, instructions from the previous response are not inherited into the next response. This makes it easy to replace system (or developer) messages in a new response.

Cannot be used together with caching. After configuring the instructions field, the current request cannot write to or use cache, which manifests as:

  • An error is reported when the caching field is configured as {"type":"enabled"}.
  • When a cached previous_response_id is passed in, the cached input (cached_tokens) is 0.

previous_response_id string / null

The unique identifier of the previous model response. Using this identifier enables multi-turn conversations.

Note
  • Passing previous_response_id in the request will include the input and response content from the previous turn, and the input tokens for the current request will increase accordingly.
  • In multi-turn continuous conversations, it is recommended to add a delay of approximately 100 milliseconds between each request, otherwise the call may fail.

expire_at integer Default: creation_time+259200

Value range: (creation_time, creation_time+604800], i.e., retained for a maximum of 7 days.

Sets the expiration time for storage. A UTC Unix timestamp (in seconds) must be provided. This applies to both store (context storage) and caching (context caching).

Note: Cache storage time is billed as expiration_time - creation_time, with any period less than 1 hour rounded up to 1 hour.

max_output_tokens integer / null

Maximum number of output tokens for the model, including model response and chain-of-thought content.

thinking object Default: depends on the model called

Controls whether the model enables deep thinking mode. Deep thinking mode is enabled by default and can be manually disabled.

Properties

thinking.type string Required

Value range: enabled, disabled, auto.

  • enabled: Enables thinking mode; the model will always 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.

reasoning object

Limits the workload of deep thinking. Reducing the deep thinking workload results in faster response times and lower token usage for deep thinking.

Properties

reasoning.effort string

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

  • 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-2606
  • 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: glm-5-2-260617

include array

Specifies additional output data to be returned in the model response. Currently supported values are:

  • reasoning.encrypted_content: The original thinking content after encryption and compression processing. This field can be manually passed back to enable multi-turn reuse of the original thinking content.

caching object Default {"type": "disabled"}

Whether to enable caching.

Cannot be used together with the instructions field or the tools field (except for custom Function Calling).

Properties

caching.type string Required

Value range: enabled, disabled.

  • enabled: Enables caching.
  • disabled: Disables caching.

caching.prefix boolean Default false

  • true: Only creates a common prefix cache; the model does not respond.
  • false: Does not create a common prefix cache.

store boolean / null Default true

Whether to store the generated model response for subsequent retrieval via API. - false: Does not store; conversation content cannot be retrieved by subsequent API calls. - true: Stores the current model response; conversation content can be retrieved by subsequent API calls.

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.

temperature float / null Default 1

Value range: [0, 2].

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.

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-code-preview-260215
  • doubao-seed-2-0-pro-260215
  • doubao-seed-2-0-lite-260215

top_p float / null Default 0.7

Value range: [0, 1].

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.

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-code-preview-260215
  • doubao-seed-2-0-pro-260215
  • doubao-seed-2-0-lite-260215
  • doubao-seed-1-8-251228

text object

Format definition for model text output, which can be natural language or structured JSON data (see Structured Output).

Properties

text.format object Default { "type": "text" }

Specifies the format of the model text output.

Natural Language

Response format is natural language.

text.format.type string Required

The type of response format; should be text here.

JSON Object

Response format is a JSON object.

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

text.format.type string Required

The type of response format; should be json_object here.

JSON Schema

Response format is a JSON object that follows the JSON structure defined by the schema field.

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

text.format.type string Required

The type of response format; should be json_schema here.

text.format.name string Required

The user-defined name of the JSON structure.

text.format.schema object Required

The JSON format definition of the response format, described as a JSON Schema object.

text.format.description string / null

Description of the response purpose; the model will use this description to determine how to respond in this format.

text.format.strict boolean / null Default false

Whether to enable strict adherence mode when generating output.

  • true: The model will always follow the format defined in the schema field.
  • false: The model will try its best to follow the structure defined in the schema field.

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.name string Required

The name of the function to call.

tools.description string

Description of the function; the model uses this to determine whether to call the function.

tools.parameters object Required

Function request parameters, described in JSON Schema format, as follows:

```json { "type": "object", "properties": { "parameter_name": { "type": "string | number | boolean | object | array", "description": "parameter description" } }, "required": ["required_parameter"] }

tool_choice string / object

Only Doubao Seed 1.8 and Doubao Seed 2.0 series models support this field.

Whether the model's response for this request contains tools to be called.

When no tools are specified, none is the default value. If tools exist, auto is the default value.

Available Types

Tool Selection Mode (string)

Controls whether the model's response includes tools to be called.

tool_choice string

  • none: The model's response must not contain tools to be called.
  • required: The model's response must contain tools to be called. When selecting this option, please ensure appropriate tools exist to reduce model hallucination.
  • auto: The model autonomously determines whether the response should include tools to be called.

Tool Call (object)

Specifies the scope of tools to be called. The model's response is only allowed to contain the following model information. When selecting this option, please ensure the tool is suitable for the user's needs to reduce model hallucination.

tool_choice.type string Required

The type of call.

  • If it is a custom Function, this should be function, and the tool_choice.name field is required.
  • If it is a built-in tool, fill in the tool name here; please refer to Responses API Built-in Tools.

tool_choice.name string

The name of the tool to be called.

If tool_choice.type is function, this field is required.

max_tool_calls integer

Value range: [1, 10].

Maximum number of tool call rounds (no limit on the number of calls within a single round). After tool calls reach this limit, the model is prompted to stop making more tool calls and provide a response.

Note: This parameter operates on a best effort mechanism and does not guarantee success. The final number of calls may be affected by factors such as model reasoning effectiveness and the validity of tool return results.

  • The default value for Web Search basic internet search tool is 3.
  • The default value for Image Process image processing tool is 10 and cannot be modified.
  • The default value for Knowledge Search private knowledge base search tool is 3.

context_management object

Context management strategy to help the model effectively utilize the context window.

Properties

context_management.edits array

Supported context editing strategies for managing thinking blocks and tool call content in the context.

Thinking Block Clearing

Manages chain-of-thought content when thinking is enabled.

context_management.edits.type string

Context editing strategy type; should be clear_thinking here.

context_management.edits.keep object/string

Chain-of-thought retention policy.

Retain Last N Turns of Chain-of-Thought

context_management.edits.keep.type string

Chain-of-thought retention policy type; should be thinking_turns here.

context_management.edits.keep.value integer Default 1

Retains the chain-of-thought from the last N turns.

Retain All Chain-of-Thought

context_management.edits.keep string

Retains all chain-of-thought; should be all here.

Tool Call Content Clearing

Clears tool call content when the conversation context grows beyond the configured threshold.

context_management.edits.type string

Context editing strategy type; should be clear_tool_uses here.

context_management.edits.keep object

Tool call content retention policy.

Properties

context_management.edits.keep.type string

Tool call content retention policy type; should be tool_uses here.

context_management.edits.keep.value integer Default 3

Retains tool call content from the last N turns.

context_management.edits.exclude_tools array

List of tool names that will not be cleared, used to preserve important context.

context_management.edits.clear_tool_input boolean Default false

Whether to clear tool call parameters.

context_management.edits.trigger object

Threshold that triggers the tool call content clearing strategy.

Properties

context_management.edits.trigger.type string

Trigger type for the tool call content clearing strategy; should be tool_uses here.

context_management.edits.trigger.value integer

Triggers the clearing strategy when tool calls reach N turns.

Request Examples

Streaming

curl --request POST \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "input": "Hello",
    "stream": true
}

Multi-turn Conversation

First Turn

curl --request POST \
    --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "input": "Hi，talk a joke"
}

Second Turn

curl --request POST \
    --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "previous_response_id":"<resp_id>",
    "input": "What is the punchline of this joke?"
}

tools_call

First Call

curl --request POST \
  -  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "store": true,  
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": "Check today's weather in Beijing."
        }
    ],
    "tools": [
        {
            "type": "function",
            "name": "get_weather",
            "description": "Look up the weather for a city on the current day (including temperature and weather conditions) based on the city name.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, such as Beijing or Shanghai (only domestic prefecture-level cities are supported)"
                    }
                },
                "required": ["location"]  
            }
        }
    ]
}

Second Call

curl --request POST \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "previous_response_id": "<resp_id>",  
    "input": [
        {
            "arguments": "{\"location\":\"beijing\"}",
            "call_id": "<call_id>",
            "name": "get_weather",
            "type": "function_call"  
        },
        {
            "type": "function_call_output",  
            "call_id": "<call_id>",  
            "output": "{\"city\":\"beijing\",\"date\":\"2024-05-20\",\"temperature\":\"18~28℃\",\"condition\":\"sunny to cloudy\",\"wind\":\"northeast wind level 2\"}"
        }
    ]
}

Image Understanding

url --request POST \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",

    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_image",
                    "image_url": "<demo_img.png>"
                },
                {
                    "type": "input_text",
                    "text": "waht do you see?"
                }
            ]
        }
    ]
}

Video Understanding

curl --request POST \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MaaS_DB_seed_2.0_pro_20260215",
    "input": [
        {
            "role": "user",
            "content": [
                {    
                    "type": "input_video",
                    "video_url": "<demo_video_input.mp4>",
                    "fps":1
                }
            ]
        }
    ]
}

Get Status

curl --request GET \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses/{responsesId}\
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \

Get Context Conversation

curl --request GET \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses/{responsesId}/input_items \
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \

Delete Conversation

curl --request DELETE \
  --url https://genaiapi.cloudsway.net/v1/ai/{endpoint}/responses/{responsesId}\
  --header 'Authorization: Bearer ${your_ak}' \
  --header 'Content-Type: application/json' \

Response Examples

Response API Response Example

{
    "id": "resp_0217835831274756be565a09cf39c914f18dfcb4ec7b34f3423f1",
    "model": "MaaS_DB_Seed_2.1_pro_20260628",
    "output": [
        {
            "arguments": "{\"title\": \"The Gift of the Magi\"}",
            "call_id": "call_2u438xkxjg9c2iocw4g2uk6u",
            "name": "get_story_info",
            "type": "function_call",
            "id": "fc_02178358312856400000000000000000000ffffac156031561709",
            "status": "completed"
        }
    ],
    "tools": [
        {
            "name": "get_story_info",
            "type": "function",
            "description": "Retrieve basic novel information",
            "parameters": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string",
                        "description": "name"
                    }
                },
                "required": [
                    "title"
                ]
            }
        },
        {
            "name": "get_character_info",
            "type": "function",
            "description": "Retrieve basic novel information",
            "parameters": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "name"
                    }
                },
                "required": [
                    "name"
                ]
            }
        }
    ],
    "status": "completed",
    "usage": {
        "input_tokens": 495,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 37,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 532
    },
    "caching": {
        "type": "enabled",
        "prefix": null
    },
    "thinking": {
        "type": "disabled"
    },
    "store": true,
    "created_at": 1783583128,
    "object": "response",
    "tool_choice": "required",
    "max_output_tokens": 32768,
    "service_tier": "default",
    "expire_at": 1783842327
}