Media Transfer Guide

This guide explains the process of transferring media files to TikTok servers when using the Content Posting API.

File upload

Using this method, you can transfer your media to TikTok using HTTP. Upon initializing your video upload with source=FILE_UPLOAD, an upload_url will be returned. You must send the media binary to this URL.

To learn how to send videos to TikTok servers and for details on the HTTP request (endpoint, request and response schema, and headers), see the API reference for the Upload Video endpoint or the Direct Post endpoint.

Work with chunks

Chunk restrictions

• The value of total_chunk_count should be equal to video_size divided by chunk_size, rounded down to the nearest integer.
• Each chunk must be at least 5 MB but no greater than 64 MB, except for the final chunk, which can be greater than chunk_size (up to 128 MB) to accommodate any trailing bytes.
• Videos with a total size less than 5 MB must be uploaded as a whole, with chunk_size equal to the entire video's byte size. Videos with a total size greater than 64 MB must be uploaded in multiple chunks.
• There must be a minimum of 1 chunk and a maximum of 1000 chunks.
• File chunks must be uploaded sequentially.

Media transfer HTTP schema

PUT {UPLOAD_URL} HTTP /1.1
Content-Type: {MIME_TYPE}
Content-Length: {BYTE_SIZE_OF_THIS_CHUNK}
Content-Range: bytes {FIRST_BYTE}-{LAST_BYTE}/{TOTAL_BYTE_LENGTH}

BINARY_FILE_DATA

Examples

Chunk upload

In this example, there is a file with a size of 50,000,123 bytes. The chunk size is specified to be 10,000,000 bytes. The trailing 123 bytes is merged into the 10,000,000-byte chunk to meet the restriction that each chunk must be greater than 5 MB.

Example UPLOAD_URL=https://upload.us.tiktokapis.com/video/?upload_id=67890&upload_token=chunkexample will be shared across all chunks.

The following is the corresponding source_info for initializing video upload.

"source_info": {
      "source": "FILE_UPLOAD",
      "video_size": 50000123
      "chunk_size":  10000000
      "total_chunk_count": 5
  }

Whole upload

In this example, the media file is 4 MB, which must be uploaded as a whole in one request.

The following is the corresponding source_info for initializing video upload.

"source_info": {
      "source": "FILE_UPLOAD",
      "video_size": 4194304
      "chunk_size":  4194304
      "total_chunk_count": 1
  }

Response

The response header includes the following key-value pair indicating the number of bytes uploaded:

Content-Range:bytes 0-{UPLOADED_BYTES}/{TOTAL_BYTE_LENGTH}.

Pull from URL

By initializing your content post using /init endpoints with source=PULL_FROM_URL, the TikTok server starts to download the media resource using the URL you provide. Learn more about getting post status.

TikTok server's ingress bandwidth for file downloads can reach 100 Mbps.

Prerequisites

• Ensure that the media URL you provided belongs to a path that you own. To confirm ownership, log into the TikTok for Developers website and add your Domain or URL Prefix property to your application in the URL properties widget as shown below. You must have manage or write access to the property.

• The media URL must use "https" and should not redirect to another URL.
• The URL must remain accessible for the entire duration of the download process, which times out one hour after the download task is initiated.

Ownership verification rules

Domain

Definition

A domain can be a base domain (for example, example.com) or a subdomain (for example, subdomain.example.com).

Verification

To verify domain ownership, it is recommended that you add a signature string to the domain's DNS records.

Once the ownership of a domain is verified, all paths under that domain or its subdomains are considered owned by the developer application.

For example, if you have verified the domain static.example.com, then URLs like https://video.static.example.com/tiktok/example.mp4 are considered verified, while URLs like https://example.com/videos/example.mp4 are still considered unverified.

URL Prefix

Definition

A URL prefix consists of: https:// + host + path + /.

The host must be a domain and should not be an IP address.

Redirections are not followed. URLs that return HTTP 3xx are considered invalid.

Verification

Once a URL prefix's ownership is verified, all URLs with the exact prefix are considered owned by the developer application.

For example, if you have already verified the domain https://example.com/videos/user/, then URLs like https://example.com/videos/user/123/example.mp4 are considered verified, while URLs like https://example.com/videos/2023/user/123/example.mp4 are still considered unverified.

Cancel ongoing pull from URL tasks

The API can cancel downloads for both Direct Post and Content Upload endpoints on a best-effort basis.

While it is possible to cancel ongoing slow downloads, it is not feasible to cancel downloads that are nearing completion or already in the file processing state.

Request

POST /v2/post/publish/cancel/ HTTP /1.1
Host: open.tiktokapis.com
Authorization: Bearer {{AccessToken}}
Content-Type: application/json; charset=UTF-8

{
    "publish_id": {PUBLISH_ID}
}

Response

200 OK

{
    "error": {
         "code": "ok",
         "message": "",
         "log_id": "202210112248442CB9319E1FB30C1073F3"
     }
}

response.error.code specification

Video restrictions

Image restrictions