model

String

是

-

您创建的应用 ID。支持零代码应用和高代码应用：

• 获取零代码应用 ID，请参见 零代码应用操作指南
• 获取高代码应用 ID，请参见 高代码应用创建部署指南

bot-202406040*****-*****

messages

Array of MessageParam

是

-

由目前为止的对话组成的消息列表
当指定了 tools 参数以使用模型的 function call 能力时，请确保 messages 列表内的消息满足如下要求：

• 如果 message 列表中前文出现了带有 n 个 tool_calls 的 Assistant Message，则后文必须有连续 n 个分别和每个 tool_call_id 相对应的 Tool Message，来回应 tool_calls 的信息要求。

-

stream

Boolean

否

false

响应内容是否流式返回

• false：模型生成完所有内容后一次性返回结果
• true：按 SSE 协议逐块返回模型生成内容，并以一条 data: [DONE] 消息结束

false

stream_options

Object of StreamOptionsParam

否

-

流式响应的选项。仅当 stream: true 时可以设置 stream_options 参数。

-

max_tokens

Integer

否

4096

模型可以生成的最大 token 数量。输入 token 和输出 token 的总长度还受模型的上下文长度限制。
具体取值范围，取决于配置的模型支持的长度，具体请参见模型列表。

4096

stop

Array or String

否

-

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

["你好", "天气"]

frequency_penalty

Float

否

0

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

1

temperature

Float

否

1

采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。取值范围为 [0, 1]。0 特殊处理
较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）会使输出更加集中确定。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。

0.8

top_p

Float

否

0.7

核采样概率阈值。模型会考虑概率质量在 top_p 内的 token 结果。取值范围为 [0, 1]。
如 0.1 意味着只考虑概率质量最高的前 10% 的 token，取值越大生成的随机性越高，取值越低生成的确定性越高。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。

0.8

logprobs

Boolean

否

false

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

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

false

top_logprobs

Integer

否

0

指定每个输出 token 位置最有可能返回的 token 数量，每个 token 都有关联的对数概率。仅当 logprobs: true 时可以设置 top_logprobs 参数，取值范围为 [0, 20]。

2

logit_bias

Map<String, Integer>

否

-

调整指定 token 在模型输出内容中出现的概率，使模型生成的内容更加符合特定的偏好。logit_bias 字段接受一个 map 值，其中每个键为词表中的 token ID，每个值为该 token 的偏差值，取值范围为 [-100, 100]。
-1 会减少选择的可能性，1 会增加选择的可能性；-100 会完全禁止选择该 token，100 会导致仅可选择该 token。该参数的实际效果可能因模型而异。

{
    "1234": -100
}

tools

Array of ToolParam

否

-

模型可以调用的工具列表。目前，仅函数作为工具被支持。用这个来提供模型可能为其生成 JSON 输入的函数列表。

-

metadata

Metadata

否

-

额外参数

-

role

String

是

-

发出该消息的对话参与者角色，可选值包括：

• system：System Message 系统消息
• user：User Message 用户消息
• assistant：Assistant Message 对话助手消息
• tool：Tool Message 工具调用消息

user

name

String

否

-

仅在群聊模式下生效
标记此条信息是哪个角色的发言，应当和配置中的角色名称保持一致

孙悟空

content

String

否

-

消息内容

• 当 role 为 system、user、tool时，参数必填
• 当 role 为 assistant 时，content 与 tool_calls 参数二者至少填其一

世界第一高山是什么？

tool_calls

Array of MessageToolCallParam

否

-

模型生成的工具调用。当 role 为 assistant 时，content 与 tool_calls 参数二者至少填其一

-

tool_call_id

String

否

-

此消息所回应的工具调用 ID，当 role 为 tool 时必填

call_5y**********************

id

String

是

-

当前工具调用 ID

call_5y**********************

type

String

是

-

工具类型，当前仅支持function

function

function

FunctionParam

是

-

模型需要调用的函数

-

name

String

是

-

模型需要调用的函数名称

get_current_weather

arguments

String

是

-

模型生成的用于调用函数的参数，JSON 格式。请注意，模型并不总是生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。

{"location": "Boston, MA"}

type

String

是

-

工具类型，当前仅支持 function

function

function

FunctionDefinition

是

-

模型可以调用的工具列表。

-

name

String

是

-

函数的名称

get_current_weather

description

String

否

-

对函数用途的描述，供模型判断何时以及如何调用该工具函数

获取指定城市的天气信息

parameters

Object

否

-

函数请求参数，以 JSON Schema 格式描述。具体格式请参考 JSON Schema 文档

{
    "type": "object",
    "properties": {
        "location": {
            "type": "string",
            "description": "城市，如：北京",
        },
    },
    "required": ["location"],
}

-

include_usage

Boolean

否

false

是否包含本次请求的 token 用量统计信息

• false：不返回 token 用量信息
• true：在 data: [DONE] 消息之前返回一个额外的块，此块上的 bot_usage 字段代表整个请求的 token 用量，choices 字段为空数组。所有其他块也将包含 bot_usage 字段，但值为 null。

false

user_info

String

否

-

可以被反序列化成 json 的字符串，需要包含 city 和 district 两个字段

"{\"city\":\"北京\",\"district\":\"海淀区\"}"

-

emit_intention_signal_extra

String

否

"false"

值是 "true" 时，会中途返回intention状态 "正在搜索"

-

target_character_name

String

否

-

群聊Bot对话时填写，指定本次要发言的角色名，必须是存在于characters里的角色

-

group_chat_config

object

是

-

运行时动态传入的角色配置，包含参数characters、description、user_name：

• characters：array类型的群聊角色列表，需要填写：
  • name：群聊角色名称
  • system_prompt：群聊角色设定，用于告知应用需要扮演的角色
  • model_desc.endpoint_id：您创建的推理接入点ID

注：单次请求传入的角色上限为50个

• description：非必填，群聊场景描述，可设定群聊的主题、时间地点、事件场景、用户扮演的角色等信息
• user_name: 非必填，表示“我”所扮演的角色名称 ，默认值为“用户”

{
  "characters": [
    {
      "name": "孙悟空",
      "system_prompt": "降妖除魔的大师兄",
      "model_desc": {
        "endpoint_id": "{your endpoint id}"//此处为您创建的推理接入点ID
      }
    },
    {
      "name": "猪八戒",
      "system_prompt": "天蓬元帅下凡",
      "model_desc": {
        "endpoint_id": "{your endpoint id}"//此处为您创建的推理接入点ID
      }
    }
  ],
  "description": "西天取经之路",
  "user_name": "唐僧"
}

-

id

String

本次请求的唯一标识

021718049470528d92fcbe0865fdffdde********************

model

String

本次请求实际使用的模型名称和版本

Doubao 1.5 代模型的模型名称格式为 doubao-1-5-**，如调用部署doubao-1.5-pro-32k 250115模型的推理接入点，返回model字段信息doubao-1-5-pro-32k-250115。

doubao-pro-32k-241215

created

Integer

本次请求创建时间的 Unix 时间戳（秒）

1718049470

object

String

固定为 chat.completion

chat.completion

choices

Array of Choice

本次请求的模型输出内容

-

bot_usage

BotUsage

本次请求的 tokens 和插件消耗

-

references

Array of Reference

• 知识库/联网的引用结果，表示调用插件的返回值
• 首chunk返回

-

metadata

Metadata

请求时附带的额外参数信息

-

id

String

本次请求的唯一标识

021718049470528d92fcbe0865fdffdde********************

model

String

本次请求实际使用的模型名称和版本

Doubao 1.5 代模型的模型名称格式为 doubao-1-5-**，如调用部署doubao-1.5-pro-32k 250115模型的推理接入点，返回model字段信息doubao-1-5-pro-32k-250115。

doubao-pro-32k-241215

created

Integer

本次请求创建时间的 Unix 时间戳（秒）

1718049470

object

String

固定为 chat.completion.chunk

chat.completion.chunk

choices

Array of StreamChoice

本次请求的模型输出内容

-

bot_usage

BotUsage

本次请求的 tokens 和插件消耗

-

references

Array of Reference

• 知识库/联网的引用结果，表示调用插件的返回值
• 首chunk返回

-

metadata

Metadata

额外参数

-

index

Integer

当前元素在 choices 列表的索引

0

finish_reason

String

模型停止生成 token 的原因。可能的值包括：

• stop：模型输出自然结束，或因命中请求参数 stop 中指定的字段而被截断
• length：模型输出因达到请求参数 max_token 指定的最大 token 数量而被截断
• content_filter：模型输出被内容审核拦截
• tool_call：模型调用了工具

stop

message

Message

模型输出的内容

-

logprobs

ChoiceLogprobs

当前内容的对数概率信息

-

role

String

固定为 assistant

assistant

content

String

模型生成的消息内容，content 与 tool_calls 字段二者至少有一个为非空

"你好"

tool_calls

Array of MessageToolCall

模型生成的工具调用，content 与 tool_calls 字段二者至少有一个为非空

-

id

String

当前工具调用 ID

call_5y**********************

type

String

工具类型，当前仅支持function

function

function

Function

模型需要调用的函数

-

name

String

模型需要调用的函数名称

get_current_weather

arguments

String

模型生成的用于调用函数的参数，JSON 格式。请注意，模型并不总是生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。

{"location": "Boston, MA"}

content

Array of TokenLogprob

message列表中每个 content 元素中的 token 对数概率信息

-

token

String

当前 token

The

bytes

Array of Integer

当前 token 的 UTF-8 值，格式为整数列表。当一个字符由多个 token 组成（表情符号或特殊字符等）时可以用于字符的编码和解码。如果 token 没有 UTF-8 值则为空。

[84, 104, 101]

logprob

Float

当前 token 的对数概率

-0.0155029296875

top_logprobs

Array of TopLogprob

在当前 token 位置最有可能的标记及其对数概率的列表。在一些情况下，返回的数量可能比请求参数 top_logprobs 指定的数量要少。

-

token

String

当前 token

The

bytes

Array of Integer

当前 token 的 UTF-8 值，格式为整数列表。当一个字符由多个 token 组成（表情符号或特殊字符等）时可以用于字符的编码和解码。如果 token 没有 UTF-8 值则为空。

[84, 104, 101]

logprob

Float

当前 token 的对数概率

-0.0155029296875

model_usage

Array of ModelUsage

本次请求不同 endpoint 的 token 消耗

-

name

String

endpoint id

-

prompt_tokens

Integer

输入的 prompt token 数量

130

completion_tokens

Integer

模型生成的 token 数量

100

total_tokens

Integer

本次请求消耗的总 token 数量（输入 + 输出）

-

index

Integer

当前元素在 choices 列表的索引

0

finish_reason

String

模型停止生成 token 的原因。可能的值包括：

• stop：模型输出自然结束，或因命中请求参数 stop 中指定的字段而被截断
• length：模型输出因达到请求参数 max_token 指定的最大 token 数量而被截断
• content_filter：模型输出被内容审核拦截
• tool_call：模型调用了工具

stop

delta

ChoiceDelta

模型输出的内容

-

logprobs

ChoiceLogprobs

当前内容的对数概率信息

-

role

String

固定为 assistant

assistant

content

String

模型生成的消息内容，content 与 tool_calls 字段二者必有一个为非空

"你好"

tool_calls

Array of ChoiceDeltaToolCall

模型生成的工具调用列表，content 与 tool_calls 字段二者必有一个为非空

-

index

Interger

当前元素在 tool_calls 列表的索引

0

id

String

当前工具调用 ID

call_5y**********************

type

String

工具类型，当前仅支持function

function

function

Function

模型需要调用的函数

-

400

BadRequest

SensitiveContentDetected

The request failed because the input text may contain sensitive information.

输入文本可能包含敏感信息，请您使用其他 prompt。

curl -X POST https://ark.cn-beijing.volces.com/api/v3/bots/chat/completions \ # 注意此处存在差异
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ea764f0f-3b60-45b3-****-************" \
  -d '{
    "model": "<YOUR_BOT_ID>",# 注意此处为您的应用ID
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
  }'

curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \ # 注意此处存在差异
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ea764f0f-3b60-45b3-****-************" \
  -d '{
    "model": "<YOUR_ENDPOINT_ID>",# 注意此处为您的推理接入点ID
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
  }'