上传素材

将文件、图片、视频等素材上传到指定云文档中。素材将显示在对应云文档中，在云空间中不会显示。

使用限制

• 素材大小不得超过 20 MB。要上传大于 20 MB 的文件，你需使用分片上传素材相关接口。详情参考素材概述。
• 该接口调用频率上限为 5 QPS，10000 次/天。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
HTTP Method	POST
接口频率限制	特殊频控
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	bitable:app 查看、评论、编辑和管理多维表格 docs:doc 查看、评论、编辑和管理文档 docs:document.media:upload 上传图片和附件到云文档中 drive:drive 查看、评论、编辑和管理云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	示例值："multipart/form-data; boundary=---7MA4YWxkTrZu0gW"

请求体

名称	类型	必填	描述
file_name	string	是	要上传的素材的名称 示例值："demo.jpeg" 数据校验规则： - 最大长度：250 字符
parent_type	string	是	上传点的类型。你可根据上传的素材类型与云文档类型确定上传点类型。例如，要将一张图片插入到新版文档（文件类型为 docx）中，需指定上传点为 docx_image ；要将一个附件上传到新版文档中，需指定上传点为 docx_file。 示例值："docx_image" 可选值有： - doc_image: 旧版文档图片 - docx_image: 新版文档图片 - sheet_image: 电子表格图片 - doc_file: 旧版文档文件 - docx_file: 新版文档文件 - sheet_file: 电子表格文件 - vc_virtual_background: vc 虚拟背景（灰度中，暂未开放） - bitable_image: 多维表格图片 - bitable_file: 多维表格文件 - moments: 同事圈（灰度中，暂未开放） - ccm_import_open: 云文档导入文件
parent_node	string	是	上传点的 token，即要上传的云文档的 token，用于指定素材将要上传到的云文档或位置。参考素材概述了解上传点类型与上传点 token 的对应关系
size	int	是	文件的大小，单位为字节 示例值：1024 数据校验规则： - 最大值：20971520
checksum	string	否	文件的 Adler-32 校验和 示例值："3248270248"
extra	string	否	以下场景的上传点需通过该参数传入素材所在云文档的 token。extra 参数的格式为"{"drive_route_token":"素材所在云文档的 token"}"。详情参考素材概述-extra 参数说明。 示例值："{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}"
file	file	是	文件的二进制内容 示例值：file binary

cURL示例

curl --location --request POST 'https://open.feishu.cn/open-apis/drive/v1/medias/upload_all' \
--header 'Authorization: Bearer t-43b270c035ddffdcf79c9eb548d06318ca4abcef' \
--form 'file_name="demo.jpeg"' \
--form 'parent_type="doc_image"' \
--form 'parent_node="doccnFivLCfJfblZjGZtxgabcef"' \
--form 'size="1024"' \
--form 'file=@"/Path/demo.jpeg"'
--form 'extra="{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}"'

Python示例

import os
import requests
from requests_toolbelt import MultipartEncoder

def upload_media():
    file_path = "path/demo.jpeg"
    file_size = os.path.getsize(file_path)
    url = "https://open.feishu.cn/open-apis/drive/v1/medias/upload_all"
    form = {'file_name': 'demo.jpeg',
            'parent_type': 'doc_image',
            'parent_node': 'doccnFivLCfJfblZjGZtxgabcef',
            'size': str(file_size),
            'file': (open(file_path, 'rb'))}  
    multi_form = MultipartEncoder(form)
    headers = {
        'Authorization': 'Bearer t-e13d5ec1954e82e458f3ce04491c54ea8c9abcef',  ## 获取tenant_access_token, 需要替换为实际的token
    }
    headers['Content-Type'] = multi_form.content_type
    response = requests.request("POST", url, headers=headers, data=multi_form)

if __name__ == '__main__':
    upload_media()

请求体示例

---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file_name";

demo.jpeg
---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="parent_type";

docx_image
---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="parent_node";


---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="size";

1024
---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="checksum";

3248270248
---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="extra";

{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}
---7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file";
Content-Type: application/octet-stream

file binary
---7MA4YWxkTrZu0gW

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ file_token	string	素材文件的 token。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "file_token": "boxcnrHpsg1QDqXAAAyachabcef"
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
200	1061001	internal error.	服务内部错误，包括超时，错误码没处理。
400	1061002	params error.	请检查请求参数是否正确。
404	1061003	not found.	请确认对应资源是否存在。
403	1061004	forbidden.	当前调用身份没有文件或文件夹的阅读或编辑等权限。请参考以下方式解决： - 若上传素材，请确保当前调用身份具有目标云文档的编辑权限 - 若上传文件，请确保当前调用身份具有文件夹的编辑权限 - 若对文件或文件夹进行增删改等操作，请确保调用身份具有足够文档权限： - 对于新建文件接口，调用身份需要有目标文件夹的编辑权限 - 对于复制文件接口，调用身份需要有文件的阅读或编辑权限、并且具有目标文件夹的编辑权限 - 对于移动文件接口，调用身份需要有被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限 - 对于删除文件接口，调用身份需要具有以下两种权限之一： - 该应用或用户是文件所有者并且具有该文件所在父文件夹的编辑权限 - 该应用或用户并非文件所有者，但是该文件所在父文件夹的所有者或者拥有该父文件夹的所有权限（full access） 了解开通权限步骤，参考如何为应用开通云文档相关资源的权限。
401	1061005	auth failed.	请使用正确身份访问该接口。
200	1061006	internal time out.	服务内部超时，可稍后再试。
404	1061007	file has been delete.	请确认对应节点未被删除。
400	1061008	invalid file name.	请检查文件名，当前文件名过长或者为空。
400	1061021	upload id expire.	上传事务过期，请重头开始上传。
400	1061041	parent node has been deleted.	请确认上传点未被删除。
400	1061042	parent node out of limit.	在当前上传点上传过多素材，请更换上传点。
400	1061043	file size beyond limit.	请检查文件长度以避免超出限制。具体限制请参考
400	1061044	parent node not exist.	parent_node 不存在。请确认上传点 token 是否有误： - 对于上传文件接口，请参考文件夹 token 获取方式确认是否填写了正确的文件夹 token - 对于上传素材接口，请参考上传点类型和上传点 token 确认 parent_node 是否填写正确
200	1061045	can retry.	内部可重试错误，请稍后重试。
400	1061109	file name cqc not passed.	请确保上传的文件和文件名合规。
400	1061113	file cqc not passed.	请确保上传的文件和文件名合规。
400	1061101	file quota exceeded.	租户容量超限，请确保租户有足够容量进行上传。
202	1062004	cover generating.	缩略图正在生成中，请稍后再试。
202	1062005	file type not support cover.	此文件类型不支持生成缩略图。
202	1062006	cover no exist.	缩略图正在生成中，请稍后再试。
400	1062007	upload user not match.	请确保当前请求身份和上传任务的身份为同一个。
400	1062008	checksum param Invalid.	请确保文件/文件块的checksum正确。
400	1062009	the actual size is inconsistent with the parameter declaration size.	实际传输的文件大小和参数说明的大小不符合一致。
400	1062010	block missing, please upload all blocks.	部分文件分片缺失，请确保所有文件分片上传完成。
400	1062011	block num out of bounds.	上传过多文件分片，请确保上传的为对应文件。
400	1061547	attachment parent-child relation number exceed.	特指上传到文档的素材超出限制。
400	1061061	user quota exceeded.	个人容量超限，请确保个人有足够容量进行上传。
403	1061073	no scope auth.	没有申请接口权限。
400	1062012	file copying.	文件正在拷贝中。
400	1062013	file damaged.	文件拷贝失败。
403	1062014	dedupe no support.	不允许秒传。
400	1062051	client connect close.	客户端断开连接。
400	1062505	parent node out of size.	云空间中所有层级的节点总和超限。上限为 40 万个，请检查节点数量。了解更多，参考云空间概述。
400	1062506	parent node out of depth.	云空间目录深度超限制（15限制）。
400	1062507	parent node out of sibling num.	云空间中根目录或文件夹的单层节点超限。上限为 1500 个，你可通过将文件新建到不同文件夹中解决。