# 分片上传素材-预上传
发送初始化请求，以获取上传事务 ID 和分片策略，为[上传素材分片](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_part)做准备。平台固定以 4MB 的大小对素材进行分片。了解完整的分片上传素材流程，参考[素材概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction)。
## 注意事项
上传事务 ID 和上传进度在 24 小时内有效。请及时保存和恢复上传。
## 使用限制
该接口调用频率上限为 5 QPS，10000 次/天。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/drive/v1/medias/upload_prepare
HTTP Method | POST
接口频率限制 | [特殊频控](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 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](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
更多云文档接口权限问题，参考[常见问题](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN)。
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
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，用于指定素材将要上传到的云文档或位置。参考 [素材概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction) 了解上传点类型与上传点 token 的对应关系。
**示例值**："doccnFivLCfJfblZjGZtxgabcef"
size | int | 是 | 文件的大小，单位为字节
**示例值**：1024
**数据校验规则**：
- 最小值：`0`
extra | string | 否 | 以下场景的上传点需通过该参数传入素材所在云文档的 token。extra 参数的格式为`"{\"drive_route_token\":\"素材所在云文档的 token\"}"`。详情参考[素材概述-extra 参数说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction#3b8635d3)。
**示例值**："{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}"
### 请求体示例
```json
{
"file_name": "demo.jpeg",
"parent_type": "docx_image",
"parent_node": "doccnFivLCfJfblZjGZtxgabcef",
"size": 1024,
"extra": "{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}"
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
upload_id | string | 分片上传事务 ID
block_size | int | 分片大小策略
block_num | int | 分片数量
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"upload_id": "7111211691345512356",
"block_size": 4194304,
"block_num": 1
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
200 | 1061001 | internal error. | 服务内部错误，包括超时，错误码没处理。
400 | 1061002 | params error. | 请检查请求参数是否正确。
404 | 1061003 | not found. | 请确认对应资源是否存在。
403 | 1061004 | forbidden. | 当前调用身份没有文件或文件夹的阅读或编辑等权限。请参考以下方式解决：
- 若上传素材，请确保当前调用身份具有目标云文档的编辑权限
- 若上传文件，请确保当前调用身份具有文件夹的编辑权限
- 若对文件或文件夹进行增删改等操作，请确保调用身份具有足够文档权限：
- 对于新建文件接口，调用身份需要有目标文件夹的编辑权限
- 对于复制文件接口，调用身份需要有文件的阅读或编辑权限、并且具有目标文件夹的编辑权限
- 对于移动文件接口，调用身份需要有被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限
- 对于删除文件接口，调用身份需要具有以下两种权限之一：
- 该应用或用户是文件所有者并且具有该文件所在父文件夹的编辑权限
- 该应用或用户并非文件所有者，但是该文件所在父文件夹的所有者或者拥有该父文件夹的所有权限（full access）
了解开通权限步骤，参考[如何为应用开通云文档相关资源的权限](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-add-permissions-to-app)。
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. | 请检查文件长度以避免超出限制。[具体限制请参考](https://www.feishu.cn/hc/zh-CN/articles/360049067549)
400 | 1061044 | parent node not exist. | `parent_node` 不存在。请确认上传点 token 是否有误：
- 对于上传文件接口，请参考[文件夹 token 获取方式](https://open.feishu.cn/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/folder-overview#-717d325)确认是否填写了正确的文件夹 token
- 对于上传素材接口，请参考[上传点类型和上传点 token](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction#cc82be3c) 确认 `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 万个，请检查节点数量。了解更多，参考[云空间概述](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/files/guide/introduction)。
400 | 1062506 | parent node out of depth. | 云空间目录深度超限制（15限制）。
400 | 1062507 | parent node out of sibling num. | 云空间中根目录或文件夹的单层节点超限。上限为 1500 个，你可通过将文件新建到不同文件夹中解决。