通过 Base 64 上传本地文件

✅
格式支持 pdf、txt、doc、docx 类型。

❌

上传在线网页

✅

❌

通过 上传文件 上传

❌

✅

请求地址

权限

createDocument
确保调用该接口使用的服务令牌开通了 createDocument 权限，详细信息参考鉴权方式。

接口说明

调用此接口向指定知识库中上传文件。

Authorization

Bearer $Access_Token

用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。

Content-Type

application/json

请求正文的方式。

Agw-Js-Conv

str

防止丢失数字类型参数的精度。

dataset_id

String

必选

736356924530694****

扣子知识库 ID。
在扣子编程中打开指定知识库页面，页面 URL 中 knowledge 参数后的数字就是知识库 ID。例如 https://www.coze.cn/space/736142423532160****/knowledge/738509371792341****，知识库 ID 为 738509371792341****。

document_bases

Array of DocumentBase

必选

[ { “name”: “Coze.pdf”, “source_info”: { “file_base64”: “5rWL6K+V5LiA5LiL5ZOm”, “file_type”: “pdf” } } ]

待上传文件的元数据信息。数组最大长度为 10，即每次最多上传 10 个文件。
支持的上传方式如下：

• 文本知识库：
  • 通过 Base64 上传本地文件。
  • 上传在线网页。
• 图片知识库：通过上传文件API 获取的 file_id 上传图片。

chunk_strategy

Object of ChunkStrategy

必选

{
“separator”: “\n\n”,
“max_tokens”: 800,
“remove_extra_spaces”: false,
“remove_urls_emails”: false,
“chunk_type”: 1
}

分段规则。详见 ChunkStrategy object。

format_type

Integer

必选

2

知识库类型。取值包括：

• 0：文本类型
• 2：图片类型

name

String

必选

Coze.pdf

文件名称。

source_info

Object of SourceInfo

必选

{ “file_base64”: “5rWL6K+V5LiA5LiL5ZOm”, “file_type”: “pdf” }

文件的元数据信息。
不同的上传方式需要指定不同参数：

• 本地文件：Base64 形式上传，需要设置参数 file_base64、file_type。
• 在线网页：需要设置参数 web_url、document_source。
• file_id：需要设置参数 source_file_id、document_source。其中 source_file_id 为 上传文件 API 的响应参数 file_id。

update_rule

Object of UpdateRule

可选

{“update_type”: 0}

在线网页的更新策略。默认不自动更新。仅上传在线网页时需要设置。

caption

String

可选

可爱的

当知识库类型为图片类型时，通过该字段设置图片描述。

file_base64

String

可选

5rWL6K+V5LiA5LiL5ZOm

本地文件的 Base64 编码。

file_type

String

可选

pdf

本地文件格式，即文件后缀，例如 txt。格式支持 pdf、txt、doc、docx 类型。
上传的文件类型应与知识库类型匹配，例如 txt 文件只能上传到文档类型的知识库中。

web_url

String

可选

https://docs.coze.cn/developer_guides/upload_files

网页的 URL 地址。

document_source

Integer

可选

1

文件的上传方式。支持设置为：

• 0：本地文件上传。
• 1：上传在线网页。
• 5：通过 上传文件 上传图片。

source_file_id

String

可选

736949598110202****

通过上传文件接口获取的文件 ID。

update_type

Integer

可选

1

在线网页是否自动更新。取值包括：

• 0：（默认）不自动更新
• 1：自动更新

update_interval

Integer

可选

24

在线网页自动更新的频率。单位为小时，最小值为 24。

chunk_type

Integer

可选

0

分段设置。取值包括：

• 0：自动分段与清洗。采用扣子编程预置规则进行数据分段与处理。
• 1：自定义。此时需要通过 separator、max_tokens、remove_extra_spaces 和 remove_urls_emails 分段规则细节。
• 2：层级分段。根据文档的目录结构、章节划分等层级信息，将内容划分为不同层级的文本单元。

separator

String

可选

分段标识符。
在 chunk_type=1 时必选。

max_tokens

Long

可选

800

最大分段长度，取值范围为 100~2000。
在 chunk_type=1 时必选。

remove_extra_spaces

Boolean

可选

true

是否自动过滤连续的空格、换行符和制表符。取值包括：

• true：自动过滤
• false：（默认）不自动过滤

在 chunk_type=1 时生效。

remove_urls_emails

Boolean

可选

true

是否自动过滤所有 URL 和电子邮箱地址。取值包括：

• true：自动过滤
• false：（默认）不自动过滤

在 chunk_type=1 时生效。

caption_type

Integer

可选

0

图片知识库的标注方式：

• 0：（默认）系统自动标注描述信息
• 1：手工标注。上传图片后需要再次调用 API 更新知识库图片描述来手动设置标注。

max_level

Long

可选

5

最大层级数。
在 chunk_type=2 时生效。

save_title

Boolean

可选

true

在检索切片时，是否保留文档段落的层级结构信息，以便在检索结果中展示段落之间的层次关系。
在 chunk_type=2 时生效。

document_infos

Array of DocumentInfo

-

已上传文件的基本信息。

code

Long

0

状态码。
0 代表调用成功。

msg

String

“”

状态信息。API 调用失败时可通过此字段查看详细错误信息。
状态码为 0 时，msg 默认为空。

detail

Object of ResponseDetail

{ “logid”: “20250106172024B5F607030EFFAD653960” }

响应详情信息。

char_count

Integer

4

文件内容的总字符数量。

chunk_strategy

Object of ChunkStrategy

{ “chunk_type”: 1, “max_tokens”: 800, “remove_extra_spaces”: false, “remove_urls_emails”: false, “separator”: “#” }

分段规则。

create_time

Integer

1719907964

文件的上传时间，格式为 10 位的 Unixtime 时间戳。

document_id

String

738694205603010****

文件的 ID。

format_type

Integer

0

文件的格式类型。取值包括：

• 0：文档类型，例如 txt 、pdf 、在线网页等格式均属于文档类型。
• 1：表格类型，例如 xls 表格等格式属于表格类型。
• 2：照片类型，例如 png 图片等格式属于照片类型。

hit_count

Integer

0

被对话命中的次数。

name

String

Coze.pdf

文件的名称。

size

Integer

14164

文件的大小，单位为字节。

slice_count

Integer

1

文件的分段数量。

source_type

Integer

0

文件的上传方式。取值包括：

• 0：上传本地文件。
• 1：上传在线网页。

status

Integer

1

文件的处理状态。取值包括：

• 0：处理中
• 1：处理完毕
• 9：处理失败，建议重新上传

type

String

pdf

本地文件格式，即文件后缀，例如 txt。格式支持 pdf、txt、doc、docx 类型。

update_interval

Integer

0

在线网页自动更新的频率。单位为小时。

update_time

Integer

1719907969

文件的最近一次修改时间，格式为 10 位的 Unixtime 时间戳。

update_type

Integer

0

在线网页是否自动更新。取值包括：

• 0：不自动更新
• 1：自动更新

tos_uri

String

FileBizType.BIZ_BOT_DATASET/847077809337655_1727579972975689529_0ytrdq****.docx

上传的本地文档的唯一标识。

chunk_type

Integer

0

分段设置。取值包括：

• 0：自动分段与清洗。采用扣子编程预置规则进行数据分段与处理。
• 1：自定义。此时需要通过 separator、max_tokens、remove_extra_spaces 和 remove_urls_emails 分段规则细节。
• 2：层级分段。根据文档的目录结构、章节划分等层级信息，将内容划分为不同层级的文本单元。

separator

String

分段标识符。
在 chunk_type=1 时必选。

max_tokens

Long

800

最大分段长度，取值范围为 100~2000。
在 chunk_type=1 时必选。

remove_extra_spaces

Boolean

true

是否自动过滤连续的空格、换行符和制表符。取值包括：

• true：自动过滤
• false：（默认）不自动过滤

在 chunk_type=1 时生效。

remove_urls_emails

Boolean

true

是否自动过滤所有 URL 和电子邮箱地址。取值包括：

• true：自动过滤
• false：（默认）不自动过滤

在 chunk_type=1 时生效。

caption_type

Integer

0

图片知识库的标注方式：

• 0：（默认）系统自动标注描述信息
• 1：手工标注。上传图片后需要再次调用 API 更新知识库图片描述来手动设置标注。

max_level

Long

5

最大层级数。
在 chunk_type=2 时生效。

save_title

Boolean

true

在检索切片时，是否保留文档段落的层级结构信息，以便在检索结果中展示段落之间的层次关系。
在 chunk_type=2 时生效。

logid

String

20241210152726467C48D89D6DB2****

本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此logid及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。