# Upload media in blocks-Pre­uploading

Send an initialization request to obtain the upload transaction ID and shard strategy, in preparation for [Uploading media](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_part). The platform segments media into fixed 4MB shards. For a complete understanding of the shard upload process, refer to [Media overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction).

## Note

The upload ID and upload progress take effect within 24 hours. You can resume uploading if needed.

## Limits

This API's call frequency limit is 5 QPS, 10,000 times/day.

## Request

Facts |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/drive/v1/medias/upload_prepare
HTTP Method | POST
Rate Limit | [Special Rate Limit](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes<br>**To use this API, you must have at least 1 of the listed scopes.**<br>Enable any scope from the list | View, comment, edit and manage Base(bitable:app)<br>View, comment, edit, and manage Docs(docs:doc)<br>Upload image and file to document(docs:document.media:upload)<br>View, comment, edit, and manage all files in My Space(drive:drive)<br>View, comment, edit, and manage Sheets(sheets:spreadsheet)

### Request header

Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`<br>or<br>`user_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"

For more information about how to call the AccessToken in the Docs API, see [Get started with the Docs API](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN).

### Request body

Parameter | Type | Required | Description
---|---|---|---
file_name | string | Yes | File name<br>**Example value**: "demo.jpeg"<br>**Data validation rules**:<br>- Maximum length: `250` characters
parent_type | string | Yes | Type of upload point. You can determine the type of upload point based on the file type and the type of cloud document. For example, to insert an image into a new document (file type `docx`), specify the upload point as `docx_image`; to upload an attachment to a new document, specify the upload point as `docx_file`.<br>**Example value**: "doc_image"<br>**Optional values are**:<br>- doc_image：Image of a document.<br>- docx_image：Upgraded docs image.<br>- sheet_image：Image of a sheet.<br>- doc_file：Doc file.<br>- docx_file：Upgraded docs file.<br>- sheet_file：Sheet file.<br>- vc_virtual_background：VC virtual background (This feature is under canary release).<br>- bitable_image：Image of a bitable.<br>- bitable_file：Bitable file.<br>- moments：Moments (This feature is under canary release).<br>- ccm_import_open：File to import into Docs.
parent_node | string | Yes | The token of the upload point, which is the token of the cloud document to be uploaded, used to specify the cloud document or location where the media will be uploaded. Refer to [Media Overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction) to understand the relationship between the upload point type and the upload point token.<br>**Example value**: "doccnFivLCfJfblZjGZtxgabcef"
size | int | Yes | The size of the file, in bytes。<br>**Example value**: 1024<br>**Data validation rules**:<br>- Minimum value: `0`
extra | string | No | The upload points in the following scenarios need to pass the token of the cloud document where the material is located through this parameter. The format of the extra parameter is `"{\"drive_route_token\":\"token of the cloud document where the material is located\"}"`. For details, refer to [Material Overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction).<br>**Example value**: "{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}"

### Request body example
```json
{
    "file_name": "demo.jpeg",
    "parent_type": "doc_image",
    "parent_node": "doccnFivLCfJfblZjGZtxgabcef",
    "size": 1024,
    "extra": "{\"drive_route_token\":\"doxcnXgNGAtaAraIRVeCfmabcef\"}"
}
```

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
upload_id | string | ID of the block upload transaction
block_size | int | Size of blocks into which you need to split the file
block_num | int | Number of blocks

### Response body example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "upload_id": "7111211691345512356",
        "block_size": 4194304,
        "block_num": 1
    }
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
200 | 1061001 | internal error. | Internal service error, such as timeout or failure in processing error codes.
400 | 1061002 | params error. | Check whether the request parameters are correct.
404 | 1061003 | not found. | Check whether the resource exists.
403 | 1061004 | forbidden. | Confirm whether the current access identity has permission to read or edit files or folders. Please refer to the following methods to resolve this:<br>- When uploading materials, please ensure that the current caller has edit permissions for the target cloud document.<br>- When uploading files, please ensure that the current caller has edit permissions for the folder.<br>- When performing operations such as adding, deleting, or modifying files or folders, please ensure that the caller has sufficient document permissions:<br>- For the "create file" interface, the caller needs edit permissions for the target folder.<br>- For the "copy file" interface, the caller needs read or edit permissions for the file and edit permissions for the target folder.<br>- For the "move file" interface, the caller must have the following permissions:<br>- Manage permission for the document or folder being moved. <br>- Edit permission for current location of the document or folder.<br>- Edit permission for the new location.<br>- For the "delete file" interface, the caller must have one of the following two permissions:<br>- The app or user is the owner of the file and has edit permissions for the parent folder where the file is located.<br>- The app or user is not the owner of the file, but the owner of the parent folder where the file is located or has full access to the parent folder.<br>For information on how to grant permissions, refer to [How to Grant Permissions for Cloud Document Resources to an App](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-add-permissions-to-app).
401 | 1061005 | auth failed. | Assume the correct user or app mode to access the API.
200 | 1061006 | internal time out. | Internal service timeout. Please try again later.
404 | 1061007 | file has been delete. | Check whether the node has been deleted.
400 | 1061008 | invalid file name. | Check whether the file name has reached the maximum length or is empty.
400 | 1061021 | upload id expire. | The upload transaction has expired. Please upload again.
400 | 1061041 | parent node has been deleted. | Check whether the upload point has been deleted.
400 | 1061042 | parent node out of limit. | The number of materials to upload to the current upload node has reached the limit. Please change the upload point.
400 | 1061043 | file size beyond limit. | Check whether the length of the file is within the limit. For more information, see [File size limits in Drive](https://www.feishu.cn/hc/zh-CN/articles/360049067549).
400 | 1061044 | parent node not exist. | `parent_node` does not exist. Please verify if the upload point token is incorrect:<br>- For the file upload interface, refer to [Folder Token Retrieval Method](https://open.feishu.cn/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/folder-overview#-717d325) to ensure the correct folder token is provided.<br>- For the media upload interface, refer to [Upload Point Types and Upload Point Token](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/introduction#cc82be3c) to verify if the `parent_node` is correctly filled out.
200 | 1061045 | can retry. | Internal error. Please try again later.
400 | 1061109 | file name cqc not passed. | Make sure that the file to upload and the file name meet compliance.
400 | 1061113 | file cqc not passed. | Make sure that the file to upload and the file name meet compliance.
400 | 1061101 | file quota exceeded. | The tenant has reached the maximum capacity. Make sure that the tenant has sufficient capacity and then upload again.
202 | 1062004 | cover generating. | Generating thumbnails. Please try again later.
202 | 1062005 | file type not support cover. | The system cannot generate thumbnails for this type of file.
202 | 1062006 | cover no exist. | Generating thumbnails. Please try again later.
400 | 1062007 | upload user not match. | Make sure that the current request is sent by the same user or app as the upload task.
400 | 1062008 | checksum param Invalid. | Make sure that the checksum of the file or file block is correct.
400 | 1062009 | the actual size is inconsistent with the parameter declaration size. | The size of the file to transfer is inconsistent with that specified in the parameter.
400 | 1062010 | block missing, please upload all blocks. | Some file blocks are missing. Make sure that all file blocks are uploaded.
400 | 1062011 | block num out of bounds. | The number of file blocks to upload has reached the limit. Make sure that the file blocks belong to the specified file.
400 | 1061547 | attachment parent-child relation number exceed. | The material to upload to Docs has reached the limit.
400 | 1061061 | user quota exceeded. | You have reached your maximum personal capacity. Make sure that you have sufficient capacity and then upload again.
403 | 1061073 | no scope auth. | You have no access to the API.
400 | 1062012 | file copying. | Copying the file.
400 | 1062013 | file damaged. | Failed to copy the file.
403 | 1062014 | dedupe no support. | Instant transfer is not allowed.
400 | 1062051 | client connect close. | Disconnected from the client.
400 | 1062505 | parent node out of size. | The single tree in My Space has reached the maximum size of 400,000.
400 | 1062506 | parent node out of depth. | My Space supports up to 15 levels of directories.
400 | 1062507 | parent node out of sibling num. | The number of nodes mounted to the directory in My Space has reached the limit of **1,500** nodes per level.