跳转至

MaaS_DB /chat/completions

请求url

POST
https://genaiapi.cloudsway.net/v1/ai/{endpoint}/chat/completions
参数名 值
Authorization Bearer
Content-Type multipart/form-data

请求Body

请求参数

model string 必选

调用的模型 ID (Model ID)。 多个应用及精细管理场景，推荐使用 Endpoint ID 调用。

messages object[] 必选

消息列表，不同模型支持不同类型的消息，如文本、图片、视频、音频等。

消息类型

系统消息 (system)

模型需遵循的指令，包括扮演的角色、背景信息等。

messages.role string 必选

发送消息的角色，此处应为 system。

messages.content string / object[] 必选

系统消息的内容。

内容类型

纯文本内容 string

纯文本消息内容。

多模态内容 object[]

支持文本、图片、视频、音频等模态内容。

各模态内容对象

文本部分 (text)

messages.content.text string 必选

文本模态部分的内容。

messages.content.type string 必选

内容模态，此处应为 text。

图片部分 (image_url)

messages.content.type string 必选

内容模态，此处应为 image_url。

messages.content.image_url object 必选

图片模态的内容。图片输入支持 file_id、url 两个字段，需二选一传入。

属性

messages.content.image_url.file_id string

文件 ID。通过 Files API 上传文件后返回的 id。

注意：Chat API 支持通过 file_id 传入火山引擎 TOS Bucket 中的文件，支持该能力的模型范围如下： - doubao-seed-2.0-mini 系列：doubao-seed-2-0-mini-260428 及后续版本。 - doubao-seed-2.0-lite 系列：全版本支持。 - doubao-seed-2.0-pro 系列：全版本支持。

messages.content.image_url.url string

发给模型的图片 URL。支持格式：图片链接 或 图片的 Base64 编码。

messages.content.image_url.detail string

取值范围：low、high、xhigh。控制图片理解的精细度。

messages.content.image_url.image_pixel_limit object / null 默认值 null

输入给模型的图片的像素范围，如不在此范围，图片会被等比例缩放。

注意：图片像素范围需在 [196, 36,000,000]，否则会直接报错。生效优先级高于 detail 字段。

  • max_pixels integer: 传入图片最大像素限制。
  • min_pixels integer: 传入图片最小像素限制。

视频部分 (video_url)

messages.content.type string 必选

内容模态，此处应为 video_url。

messages.content.video_url object 必选

视频消息的内容部分。视频输入支持 file_id、url 两个字段，需二选一传入。

属性

messages.content.video_url.file_id string

文件 ID。

注意：Chat API 支持通过 file_id 传入火山引擎 TOS Bucket 中的文件，支持该能力的模型范围同图片部分。

messages.content.video_url.url string

发给模型的视频 URL。支持格式：视频链接 或 视频的 Base64 编码。

messages.content.video_url.fps float / null 默认值 1

取值范围：[0.2, 5]。抽帧频率，详见视频理解。取值越高，对画面变化越敏感。

音频部分 (input_audio)

messages.content.type string 必选

内容模态，此处应为 input_audio。

messages.content.input_audio object 必选

音频模态的内容。音频输入支持 file_id、url、data 三个字段，需三选一传入。

属性

messages.content.input_audio.file_id string

文件 ID。

注意：Chat API 支持通过 file_id 传入火山引擎 TOS Bucket 中的文件，支持该能力的模型范围同图片部分。

messages.content.input_audio.url string

音频内容的 URL。

messages.content.input_audio.data string

音频内容的 Base64 编码。

messages.content.input_audio.format string

音频格式。当使用 data 时，该参数必填。支持的音频格式 MIME 类型如下：

  • 纯音频格式：mp3、wav、aac、m4a、pcm、ac3、alac
  • 视频内嵌音频格式：mp3、wav、aac、m4a

注意： - 文件大小不超过 25 MB。 - 单次请求音频总时长不超过 120 分钟，仅统计纯音频时长。

文件部分 (file)

messages.content.type string 必选

消息模态，此处应为 file。

messages.content.file object 必选

文件模态的内容，当前仅支持 PDF 文件。文件输入支持 file_id、file_data、file_url 三个字段，需三选一传入。

属性

messages.content.file.file_id string

文件 ID。

注意：Chat API 支持通过 file_id 传入火山引擎 TOS Bucket 中的文件，支持该能力的模型范围同图片部分。

messages.content.file.file_data string

文件内容的 Base64 编码。单个文件大小要求不超过 50 MB。

messages.content.file.filename string

文件名。当使用 file_data 时该参数必填。

messages.content.file.file_url string

文件的可访问 URL。对应文件的大小要求不超过 50 MB。

用户消息 (user)

用户角色发送的消息。不同模型支持的字段类型不同。

messages.role string 必选

发送消息的角色，此处应为 user。

messages.content string / object[] 必选

用户信息内容。支持纯文本或多模态内容，具体结构与系统消息中的 content 字段一致。

模型消息 (assistant)

历史对话中，模型角色返回的消息。用以保持对话一致性。

属性

messages.role string 必选

发送消息的角色，此处应为 assistant。

messages.content string / array

模型消息的内容。

messages.reasoning_content string

模型消息中思维链内容。仅模型 doubao-seed-1.8、deepseek-v3.2、doubao-seed-2.0、doubao-seed-2.1 支持该字段。

messages.encrypted_content string

经加密及压缩处理后的思考内容原文。自 doubao-seed-2-0-lite-260428 版本起，支持该字段输出。

注意： - 回传 encrypted_content 内容需有效，篡改或无法还原时返回错误：Invalid signature。 - encrypted_content 优先级高于 reasoning_content，回传 encrypted_content 时，将忽略 reasoning_content 内容。

messages.tool_calls object[]

模型消息中工具调用部分。

属性

messages.tool_calls.function object 必选

模型返回的需调用的函数信息。

  • name string 必选: 需调用的函数的名称。
  • arguments string 必选: 需调用的函数的入参，JSON 格式。

说明：模型并不总是生成有效的 JSON，可能会虚构出未定义的参数。建议在调用函数前，验证参数是否有效。

messages.tool_calls.id string 必选

需调用的工具的 ID，由模型生成。

messages.tool_calls.type string 必选

消息类型，当前仅支持 function。

工具消息 (tool)

历史对话中，调用工具返回的消息。工具调用场景中使用。

messages.role string 必选

发送消息的角色，此处应为 tool。

messages.content string / array 必选

工具返回的消息。

messages.tool_call_id string 必选

模型生成的需调用工具请求时，生成的 ID。在程序调用工具的返回需要附上同一 ID，来关联工具结构与模型请求。避免多工具调用时混淆信息。

thinking object 默认值 {"type":"enabled"}

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

不同模型是否支持以及默认取值不同。

属性

thinking.type string 必选

取值范围：enabled， disabled， auto。

  • enabled：开启思考模式，模型强制先思考再回答。
  • disabled：关闭思考模式，模型直接回答问题，不进行思考。
  • auto：自动思考模式，模型根据问题自主判断是否需要思考，简单题目直接回答。

stream boolean / null 默认值 false

响应内容是否流式返回：

  • false：模型生成完所有内容后一次性返回结果。
  • true：按 SSE 协议逐块返回模型生成内容，并以一条 data: [DONE] 消息结束。当 stream 为 true 时，可设置 stream_options 字段以获取 token 用量统计信息。

stream_options object / null 默认值 null

流式响应的选项。当 stream 为 true 时，可设置 stream_options 字段。

属性

stream_options.include_usage boolean / null 默认值 false

模型流式输出时，是否在输出结束前输出本次请求的 token 用量信息。

  • true：在 data: [DONE] 消息之前会返回一个额外的 chunk。此 chunk 中，usage 字段中输出整个请求的 token 用量，choices 字段为空数组。
  • false：输出结束前，没有一个 chunk 来返回 token 用量信息。

stream_options.chunk_include_usage boolean / null 默认值 false

模型流式输出时，输出的每个 chunk 中是否输出本次请求到此 chunk 输出时刻的累计 token 用量信息。

  • true：在返回的 usage 字段中，输出本次请求到此 chunk 输出时刻的累计 token 用量。
  • false：不在每个 chunk 都返回 token 用量信息。

max_tokens integer / null 默认值 4096

取值范围：各个模型不同。

模型回答最大长度（单位 token）。

说明： - 模型回答不包含思维链内容，模型回答 = 模型输出 - 模型思维链（如有） - 输出 token 的总长度还受模型的上下文长度限制。

max_completion_tokens integer / null

取值范围：[1, 65,536]。

控制模型输出的最大长度（包括模型回答和模型思维链内容长度，单位 token）。

配置了该参数后，可以让模型输出超长内容，max_tokens 默认值失效，模型按需输出内容（回答和思维链），直到达到 max_completion_tokens 值。

不可与 max_tokens 字段同时设置。

stop string / string[] / null 默认值 null

模型遇到 stop 字段所指定的字符串时将停止继续生成，这个词语本身不会输出。最多支持 4 个字符串。

深度思考能力模型不支持该字段。

["你好", "天气"]

reasoning_effort string / null

限制思考的工作量。减少思考深度可提升速度，思考花费的 token 更少。

取值范围：none（仅部分模型支持），minimal，low，medium，high，xhigh（仅部分模型支持），max（仅部分模型支持）。

  • none：关闭思考。该参数仅对指定模型生效，非适配模型传入将不生效。支持模型：glm-5-2-260617。
  • minimal：关闭思考，直接回答。
  • low：轻量思考，侧重快速响应。
  • medium：均衡模式，兼顾速度与深度。
  • high：深度分析，处理复杂问题。
  • xhigh：更高程度思考。该参数仅对指定模型生效，非适配模型传入将不生效。支持模型：glm-5-2-260617。
  • max：最高程度思考，适配高难度推理任务。该参数仅对指定模型生效，非适配模型传入将不生效。支持模型列表：
  • glm-5-2-260617
  • deepseek-v4-pro-260425
  • deepseek-v4-flash-260425

response_format object 默认值 {"type": "text"} beta阶段

指定模型回答格式。

回答格式说明

文本格式 (text)

模型默认回复文本格式内容。

response_format.type string 必选

此处应为 text。

JSON Object 格式 (json_object)

模型回复内容以 JSON 对象结构来组织。

该能力尚在 beta 阶段，请谨慎在生产环境使用。

response_format.type string 必选

此处应为 json_object。

JSON Schema 格式 (json_schema)

模型回复内容以 JSON 对象结构来组织，遵循 schema 字段定义的 JSON 结构。

response_format.type string 必选

此处应为 json_schema。

response_format.json_schema object 必选

JSON 结构体的定义。

  • name string 必选: 用户自定义的 JSON 结构的名称。
  • description string / null: 回复用途描述，模型将根据此描述决定如何以该格式回复。
  • schema object 必选: 回复格式的 JSON 格式定义，以 JSON Schema 对象的形式描述。
  • strict boolean / null 默认值 false: 是否在生成输出时，启用严格遵循模式。
  • true：模型将始终严格遵循 schema 字段中定义的格式。
  • false：模型会尽可能遵循 schema 字段中定义的结构。

frequency_penalty float / null 默认值 0

取值范围为 [-2.0, 2.0]。

注意：doubao-seed-1.8、doubao-seed-2.0 系列模型不支持该字段。

频率惩罚系数。如值为正，根据新 token 在文本中的出现频率对其进行惩罚，从而降低模型逐字重复的可能性。

presence_penalty float / null 默认值 0

取值范围为 [-2.0, 2.0]。

注意：doubao-seed-1.8、doubao-seed-2.0 系列模型不支持该字段。

存在惩罚系数。如果值为正，会根据新 token 到目前为止是否出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。

temperature float / null 默认值 1

取值范围为 [0, 2]。

注意：当调用下列模型，字段取值固定为 1，手动指定的参数值将被忽略。 - doubao-seed-2-0-pro-260215 - doubao-seed-2-0-lite-260215

采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。当取值为 0 时模型仅考虑对数概率最大的一个 token。

较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）会使输出更加集中确定。

通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。

top_p float / null 默认值 0.7

取值范围为 [0, 1]。

注意：当调用下列模型，字段取值固定为 0.95，手动指定的参数值将被忽略。 - doubao-seed-2-0-pro-260215 - doubao-seed-2-0-lite-260215 - doubao-seed-1-8-251228

核采样概率阈值。模型会考虑概率质量在 top_p 内的 token 结果。当取值为 0 时模型仅考虑对数概率最大的一个 token。

0.1 意味着只考虑概率质量最高的前 10% 的 token，取值越大生成的随机性越高，取值越低生成的确定性越高。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。

logprobs boolean / null 默认值 false

带深度思考能力模型不支持该字段。

是否返回输出 tokens 的对数概率。

  • false：不返回对数概率信息。
  • true：返回消息内容中每个输出 token 的对数概率。

top_logprobs integer / null 默认值 0

带深度思考能力模型不支持该字段。 取值范围为 [0, 20]。

指定每个输出 token 位置最有可能返回的 token 数量，每个 token 都有关联的对数概率。仅当 logprobs 为 true 时可以设置 top_logprobs 参数。

logit_bias map / null 默认值 null

带深度思考能力模型不支持该字段。

调整指定 token 在模型输出内容中出现的概率，使模型生成的内容更加符合特定的偏好。logit_bias 字段接受一个 map 值，其中每个键为词表中的 token ID（使用 tokenization 接口获取），每个值为该 token 的偏差值，取值范围为 [-100, 100]。

-1 会减少选择的可能性，1 会增加选择的可能性；-100 会完全禁止选择该 token，100 会导致仅可选择该 token。该参数的实际效果可能因模型而异。

{"<Token_ID>": -100}

tools array

模型可以调用的工具，当您需要让模型调用工具时，需要配置该结构体。

函数调用 (Function Calling)

tools.type string 必选

工具类型，此处应为 function。

tools.function object 必选

模型返回中可包含待调用的工具。

  • name string 必选: 调用的函数的名称。
  • description string: 调用的函数的描述，大模型会使用它来判断是否调用这个工具。
  • parameters object: 函数请求参数，以 JSON Schema 格式描述。

请求示例

基础对话

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!"
        }
    ]
  }'

流式输出

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
}'

续写模式

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"
}'

图片理解

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"
        }
    ]
}'

视频理解

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
  }'

响应示例

Chat completions API 响应示例

{
    "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
    }
}