开场白

流式对话

知识库&记忆管理

大模型调用

向量化模型调用

召回记忆

代理外部能力请求

卡片

原子服务

大模型调用

我的收藏

接口说明

本文介绍Doubao语言大模型API的输入输出参数，帮助您使用接口向大模型发起文字对话请求。服务会将输入的文字信息输入给模型，并返回模型生成的内容。

该接口仅限调用语言大模型（doubao-lite-32k、doubao-pro-32k），无法调用向量化模型（doubao-embedding-large、

doubao-embedding）。

Doubao-embedding 模型是一款字节跳动研发的语义向量化模型，主要面向向量检索场景，可以将文本转化为向量，以方便后续的语义分析。您可以调用服务向模型输入待向量化的文本，服务会将模型处理后的向量信息返回给您。

使用限制

注意
dev 和 prod 环境的资源隔离，大模型推理节点 ID 不同，如在 prod 生产环境中无法调用 dev 开发环境的推理节点 ID。
​
请点击顶部导航栏的环境，切换到 dev/prod 环境，获取大模型推理节点ID并将其写入服务的环境变量中。

基本信息

HTTP URL	http://ark-vg.dyc.ivolces.com/api/v3/chat/completions
HTTP Method	POST
Scope	无
权限要求	无

请求头

参数	描述
content-type	`application/json`

请求参数

body

参数名称	类型	是否必填	默认值	描述	示例值
model	String	是	-	创建的推理接入点ID。推理接入点需为语言大模型（doubao-lite-32k、doubao-pro-32k），请勿填入向量化模型的推理接入点。	ep-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	StreamOptionsParam	否	-	流式响应的选项。仅当 stream: true 时可以设置 stream_options 参数。	-
max_tokens	Integer	否	4096	模型可以生成的最大 token 数量。取值范围为 [0, 4096]。输入 token 和输出 token 的总长度还受模型的上下文长度限制。	4096
stop	String or Array	否	-	模型遇到 stop 字段所指定的字符串时将停止继续生成，这个词语本身不会输出。最多支持 4 个字符串。	["你好", "天气"]
frequency_penalty	Float	否	0	频率惩罚系数。如果值为正，会根据新 token 在文本中的出现频率对其进行惩罚，从而降低模型逐字重复的可能性。取值范围为 [-2.0, 2.0]。	1
presence_penalty	Float	否	0	存在惩罚系数。如果值为正，会根据新 token 到目前为止是否出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。取值范围为 [-2.0, 2.0]。	1
temperature	Float	否	1	采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。取值范围为 [0, 1]。当取值为 0 时模型仅考虑对数概率最大的一个 token。较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）会使输出更加集中确定。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。	0.8
top_p	Float	否	0.7	核采样概率阈值。模型会考虑概率质量在 top_p 内的 token 结果。取值范围为 [0, 1]。当取值为 0 时模型仅考虑对数概率最大的一个 token。如 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<Integer, Float>	否	-	调整指定 token 在模型输出内容中出现的概率，使模型生成的内容更加符合特定的偏好。logit_bias 字段接受一个 map 值，其中每个键为词表中的 token ID（使用 tokenization 接口获取），每个值为该 token 的偏差值，取值范围为 [-100, 100]。 -1 会减少选择的可能性，1 会增加选择的可能性；-100 会完全禁止选择该 token，100 会导致仅可选择该 token。该参数的实际效果可能因模型而异。	{"1234": -100}json
tools	Array of ToolParam	否	-	模型可以调用的工具列表。目前，仅函数作为工具被支持。用这个来提供模型可能为其生成 JSON 输入的函数列表。	-

MessageParam

参数名称	类型	是否必填	默认值	描述	示例值
role	String	是	-	发出该消息的对话参与者角色，可选值包括：system：System Message 系统消息user：User Message 用户消息assistant：Assistant Message 对话助手消息tool：Tool Message 工具调用消息	user
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**********************

MessageToolCallParam

参数名称	类型	是否必填	默认值	描述	示例值
id	String	是	-	当前工具调用 ID	call_5y**********************
type	String	是	-	工具类型，当前仅支持function	function
function	FunctionParam	是	-	模型需要调用的函数	-

FunctionParam

参数名称	类型	是否必填	默认值	描述	示例值
name	String	是	-	模型需要调用的函数名称	get_current_weather
arguments	String	是	-	模型生成的用于调用函数的参数，JSON 格式。请注意，模型并不总生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。	{\"location\": \"Boston, MA\"}

ToolParam

参数名称	类型	是否必填	默认值	描述	示例值
type	String	是	-	工具类型，当前仅支持 function	function
function	FunctionDefinition	是	-	模型可以调用的工具列表。	-

FunctionDefinition

参数名称	类型	是否必填	默认值	描述	示例值
name	String	是	-	函数的名称	get_current_weather
description	String	否	-	对函数用途的描述，供模型判断何时以及如何调用该工具函数	获取指定城市的天气信息
parameters	Object	否		函数请求参数，以 JSON Schema 格式描述。具体格式请参考 JSON Schema 文档	{"type": "object","properties": {"location": {"type": "string","description": "城市，如：北京",},},"required": ["location"],}json

StreamOptionsParam

参数名称	类型	是否必填	默认值	描述	示例值
include_usage	Boolean	否	FALSE	是否包含本次请求的 token 用量统计信息false：不返回 token 用量信息true：在 data: [DONE] 消息之前返回一个额外的块，此块上的 usage 字段代表整个请求的 token 用量，choices 字段为空数组。所有其他块也将包含 usage 字段，但值为 null。	FALSE

请求示例

curl http://ark-vg.dyc.ivolces.com/api/v3/chat/completions\
  -H "Content-Type: application/json" \
  -d '{
    "model": "ep-20240704******-*****",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
  }'
bash

响应参数

非流式调用

参数名称	类型	描述	示例值
id	String	本次请求的唯一标识	021718049470528d92fcbe0865fdffdde********************
model	String	本次请求实际使用的模型名称和版本	doubao-pro-4k-240515
created	Integer	本次请求创建时间的 Unix 时间戳（秒）	1718049470
object	String	固定为 chat.completion	chat.completion
choices	Array of Choice	本次请求的模型输出内容	-
usage	Usage	本次请求的 tokens 用量	-

流式调用

参数名称	类型	描述	示例值
id	String	本次请求的唯一标识	021718049470528d92fcbe0865fdffdde********************
model	String	本次请求实际使用的模型名称和版本	doubao-pro-4k-240515
created	Integer	本次请求创建时间的 Unix 时间戳（秒）	1718049470
object	String	固定为 chat.completion.chunk	chat.completion.chunk
choices	Array of StreamChoice	本次请求的模型输出内容	-
usage	Usage	本次请求的 tokens 用量	-

choice

参数名称	类型	描述	示例值
index	Integer	当前元素在 choices 列表的索引	0
finish_reason	String	模型停止生成 token 的原因。可能的值包括：stop：模型输出自然结束，或因命中请求参数 stop 中指定的字段而被截断length：模型输出因达到请求参数 max_token 指定的最大 token 数量而被截断content_filter：模型输出被内容审核拦截tool_calls：模型调用了工具	stop
message	Message	模型输出的内容	-
logprobs	ChoiceLogprobs	当前内容的对数概率信息	-

message

参数名称	类型	描述	示例值
role	String	固定为 assistant	assistant
content	String	模型生成的消息内容，content 与 tool_calls 字段二者至少有一个为非空	"你好"
tool_calls	Array of MessageToolCall	模型生成的工具调用，content 与 tool_calls 字段二者至少有一个为非空	-

MessageToolCall

参数名称	类型	描述	示例值
id	String	当前工具调用 ID	call_5y**********************
type	String	工具类型，当前仅支持function	function
function	Function	模型需要调用的函数	-

Function

参数名称	类型	描述	示例值
name	String	模型需要调用的函数名称	get_current_weather
arguments	String	模型生成的用于调用函数的参数，JSON 格式。请注意，模型并不总生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。	{\"location\": \"Boston, MA\"}

ChoiceLogprobs

参数名称	类型	描述	示例值
content	Array of TokenLogprob	message列表中每个 content 元素中的 token 对数概率信息	-

TokenLogprob

参数名称	类型	描述	示例值
token	String	当前 token	The
bytes	Array of Integer	当前 token 的 UTF-8 值，格式为整数列表。当一个字符由多个 token 组成（表情符号或特殊字符等）时可以用于字符的编码和解码。如果 token 没有 UTF-8 值则为空。	[84, 104, 101]
logprob	Float	当前 token 的对数概率	-0.01550293
top_logprobs	Array of TopLogprob	在当前 token 位置最有可能的标记及其对数概率的列表。在一些情况下，返回的数量可能比请求参数 top_logprobs 指定的数量要少。	-

TopLogprob

参数名称	类型	描述	示例值
token	String	当前 token	The
bytes	Array of Integer	当前 token 的 UTF-8 值，格式为整数列表。当一个字符由多个 token 组成（表情符号或特殊字符等）时可以用于字符的编码和解码。如果 token 没有 UTF-8 值则为空。	[84, 104, 101]
logprob	Float	当前 token 的对数概率	-0.01550293

Usage

参数名称	类型	描述	示例值
prompt_tokens	Integer	输入的 prompt token 数量	130
completion_tokens	Integer	模型生成的 token 数量	100
total_tokens	Integer	本次请求消耗的总 token 数量（输入 + 输出）	240

StreamChoice

参数名称	类型	描述	示例值
index	Integer	当前元素在 choices 列表的索引	0
finish_reason	String	模型停止生成 token 的原因。可能的值包括：stop：模型输出自然结束，或因命中请求参数 stop 中指定的字段而被截断length：模型输出因达到请求参数 max_token 指定的最大 token 数量而被截断content_filter：模型输出被内容审核拦截tool_calls：模型调用了工具	stop
delta	ChoiceDelta	模型输出的内容	-
logprobs	ChoiceLogprobs	当前内容的对数概率信息	-

ChoiceDelta

参数名称	类型	描述	示例值
role	String	固定为 assistant	assistant
content	String	模型生成的消息内容，content 与 tool_calls 字段二者必有一个为非空	"你好"
tool_calls	Array of ChoiceDeltaToolCall	模型生成的工具调用列表，content 与 tool_calls 字段二者必有一个为非空	-

ChoiceDeltaToolCall

参数名称	类型	描述	示例值
index	Interger	当前元素在 tool_calls 列表的索引	0
id	String	当前工具调用 ID	call_5y**********************
type	String	工具类型，当前仅支持function	function
function	Function	模型需要调用的函数	-

响应示例

正常示例

{
    "id": "021718067849899d92fcbe0865fdffdde********************",
    "object": "chat.completion",
    "created": 1720582714,
    "model": "doubao-pro-32k-240615",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello, can i help you with something?"
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 22,
        "completion_tokens": 9,
        "total_tokens": 31
    }
}

异常示例

错误码

HTTP 状态码	错误码	描述	排查建议