Multipart Upload

The Multipart Upload allows you to split a single video into multiple parts (blocks) and upload them concurrently or sequentially. This method is recommended for uploading large videos as it offers better reliability and supports resuming uploads (breakpoint continuation).

1. Overview & Concepts

To successfully upload a video using this method, you need to understand two key concepts: Blocks and Chunks.

• Block: The video is divided into blocks of a fixed size.
  • Size Constraint: The block size must be a multiple of 4 MB (e.g., 4 MB, 8 MB, 12 MB). This is critical because the server uses this alignment to calculate the ETag and checksums. Deviating from this size will result in validation errors.
  • Last Block: The final block is the actual remaining size of the video (it does not need to be a multiple of 4 MB).
  • Small Videos: If the entire video is smaller than the configured block size, the video consists of a single block.
• Chunk: Inside each block, data is uploaded sequentially in “chunks”. A chunk is a slice of data within a block used for transmission.

Basic Workflow:

1. Split Video: Divide the entire video into blocks based on the chosen size (must be a multiple of 4 MB).
2. Slice Blocks: Further divide each block into smaller “chunks” for transfer.
3. Initialize Block (/mkblk): Create the corresponding block on the server by uploading its first chunk.
4. Upload Remaining Chunks (/bput): Upload all subsequent chunks for that specific block until the block is complete.
5. Repeat: Perform steps 3 and 4 for every block in the video (blocks can be uploaded in parallel).
6. Merge (/mkfile): Once all blocks are uploaded, instruct the server to combine the block information in the specified order to form the final video.

2. Prerequisites

Before calling any endpoints in this document, you must obtain upload credentials.

1. Call the Get Upload Token (/vod/videoManage/getUploadToken).
2. Extract the following values from the response to use in the Multipart Upload requests:

3. API Reference

Step 1: Create Block & Upload First Chunk

This endpoint initializes a new block and uploads the first chunk of data for that block.

Endpoint:POST <uploadUrl>/mkblk/<BlockSize>/<BlockIndex>

Path Parameters

Request Headers

Request Body

• Binary Data: The raw binary content of the first chunk.

Response Example

{
    "ctx": "ExampleContextStringForNextChunk...",
    "checksum": "checksum_string",
    "crc32": 123456789,
    "offset": 4194304
}

• ctx: Context string required for the next bput request. Must be preserved by the client to link the next chunk.
• checksum: The checksum of the uploaded block.
• crc32: The CRC32 value of the uploaded block. You can use this to verify the integrity of the uploaded data.
• offset: The next expected offset for this block.

Step 2: Upload Subsequent Chunks

Use this endpoint to upload the remaining chunks for a specific block. You must repeat this call until the current block is completely uploaded.

Endpoint:POST <uploadUrl>/bput/<Ctx>/<NextChunkOffset>

Path Parameters

Request Headers

Request Body

• Binary Data: The raw binary content of the current chunk.

Response Example

{
    "ctx": "ExampleContextStringForNextChunk...",
    "checksum": "checksum_string",
    "crc32": 123456789,
    "offset": 8388608
}

• ctx: Updated context string required for the next bput request.
• checksum: The checksum of the uploaded block.
• crc32: The CRC32 value.
• offset: The next expected offset for this block.

Step 3: Complete Upload (Make Video File)

Once all blocks have been successfully uploaded, call this endpoint to merge them into the final video.

Endpoint:POST <uploadUrl>/mkfile/<FileSize>

Note: You can append optional parameters to the URL format: <uploadUrl>/mkfile/<FileSize>/x:<UserParam>/<EncodedValue>.

Path Parameters

Request Headers

Request Body

A comma-separated list of the final ctx string returned for each block, sorted strictly by the block index (e.g., Block 0, Block 1…).

Format:

<LastCtxOfBlock0>,<LastCtxOfBlock1>,<LastCtxOfBlock2>

Response Example

{
    "hash": "FqlKj-9023...",
    "key": "video/2023/example.mp4"
}

4. Best Practices & Notes

• Concurrency: You can upload different Blocks in parallel to speed up the process. However, Chunks within a single block must be uploaded sequentially.
• Resuming Uploads: If an upload fails, you do not need to restart from scratch. You can resume from the last successful block or chunk by checking the local progress against the server’s offset response.
• Cleanup: The server periodically cleans up incomplete blocks (approx. every 30 days). Ensure you complete the /mkfile step to finalize the video.