Docs

API Reference

Illustrated below is the overall process for integrating with media asset management capabilities. Media asset library access requires use of the open APIs listed in this guide to upload and manage assets, submit them for moderation, and receive results.

Authorization acquisition

Note: All open API calls require obtaining client authorization credentials. When calling an open API, add the authorization credentials to the header. TikTok will verify the client's identity information based on the authorization credentials.

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/oauth/token/
HTTP Method	POST
HTTP Header	`Content-Type`: pass a fixed value `application/x-www-form-urlencoded`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
client_secret	string	Yes	Client Key	xxxxxxxxxxxxxx
grant_type	string	Yes	Type of authorization token Fixed entryclient_credentials	client_credentials

Request Example

curl --location --request POST 'https://open.tiktokapis.com/v2/oauth/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'client_key=CLIENT_KEY' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'grant_type=client_credentials'

Return Value

Field Name	Type	Description	Sample Value
access_token	string	Mini Programs Client Authentication Token	clt.example12345Example12345Example
expires_in	string	The expiration time of the access_token (in seconds). It is valid within 2 hours after being called.	7200
token_type	string	Fixed to:Bearer	client_credentials

Open APIs

All the following interfaces have use cases, and you can import the following curl call example intoPostmanor similar software, and modifyAuthorizationin the header to the corresponding client_auth_token of the calling Mini Program

Resource Management

Resource Upload

Create Image

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/image
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
image_url	string	Yes	Image URL. Note: The provided image URL needs to be publicly downloadable.	https://tiktok.com/5d1c6fee2b2ad23d3466708/63ec5da3f441a7bb0ca9067f_janan-lagerwall-p2UbTX6Uoig-xxx.jpg

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/image' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "image_url": "https://cdn.prod.website-files.com/5d1c6fee2b2ad23d3b466708/63ec5da3f441a7bb0ca9067f_janan-lagerwall-p2UbTX6Uoig-xxx.jpg"
}'

Return Value

Field Name	Type	Description	Sample Value
open_pic_id	string	Image ID after upload	b4c45eb643861b84b3b678a2f20e7acd
tiktok_pic_url	string	Preview link of TikTok image after upload	https://tosv.byted.org/obj/ttop-governance-material-sg/mn4mln19zm56yje7short_drama_image202605081720_2919.jpg

Upload Video - Asynchronous

This interface is an asynchronous upload interface. Please use the returned job_id to call the "Query Video" interface for polling the upload results.

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/video
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
url	string	Yes	Video download address, which must be publicly accessible `http` or `https` link	https://example.com/demo.mp4
title	string	Yes	Video Title	episode_01
space_name	string	Yes	Name of the BytePlus space to which the video needs to be uploaded	test_space
byteplus_account_id	string	Yes	BytePlus account ID to which the video needs to be uploaded	333234234

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/video' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "client_key": "mnxxxxxxxxxxxxx",
    "url": "https://example.com/demo.mp4",
    "title": "episode_01",
    "space_name": "shortdrama-sg",
    "byteplus_account_id":"234234234"
}'

Return Value

Field Name	Type	Description	Sample Value
result_type	int	Upload task acceptance result. 1: Success; 2: Asynchronous upload success; 3: Failure. This interface usually returns `2 when it is normally accepted.`	2
job_id	string	Asynchronous upload task ID, used for subsequent polling to query the upload result	vod:job:1234567890
byteplus_vid	string	BytePlus video ID after video upload is completed. It may be empty during the asynchronous acceptance stage	v188ebg00018d7v1vpf3ksl0c0f9goig
byteplus_url	string	Video playback address. The asynchronous acceptance stage is usually empty	https://vod.example.com/play/xxx.m3u8

Query Video

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/video
HTTP Method	GET
HTTP Header	`Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
job_id	string	No	Either job_id or vid must be passed, at least one of them. It is recommended to use this field for polling after uploading.	vod:job:1234567890
vid	string	No	At least one of job_id and vid must be provided. After the upload is completed, video details can be queried via vid	v188ebg00018d7v1vpf3ksl0c0f9goig
byteplus_account_id	string	Yes	byteplus account ID to which the video needs to be uploaded	333234234

Request Example

curl --location --request GET 'https://open.tiktokapis.com/v2/sg/shortdrama/video?client_key=mnxxxxxxxxxxxxx&job_id=vod%3Ajob%3A1234567890&byteplus_account_id=4324234' \
--header 'Authorization: Bearer xxxxx'

Return Value

Field Name	Type	Description	Sample Value
upload_status	int	Upload status. 1: Processing; 2: Success; 3: Failure	1
vid	string	BytePlus Video ID after video upload is completed	v188ebg00018d7v1vpf3ksl0c0f9goig
job_id	string	Upload Task ID	vod:job:1234567890
byteplus_url	string	Video Playback Address	https://vod.example.com/play/xxx.m3u8
title	string	Video Title	episode_01
duration_ms	int64	Video duration, unit: milliseconds	60000
cover_url	string	Video cover address	https://vod.example.com/cover/xxx.jpg
raw_video_info_json	string	Underlying video information raw JSON, facilitating debugging and troubleshooting	{"Vid":"xxx"}

Create a play

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/create/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name

Type

Required

Description

Sample Value

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/create/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
}'

Return Value

Field Name	Type	Description	Sample Value
result_type	int	Creation result. 1: Success; 2: Partial success; 3: Failure	1
album_id	int64	New Play ID	7637420375425239060
version	int64	Initial version number	1

Edit Play

This interface will generate a new version of the play, without overwriting historical versions in place.

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/update/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
album_id	int64	Yes	Play ID	7637420375425239060
operation_type	int	No	Operation type. 1: Draft addition/updating; 2: Only update the editing status of the play. Defaults to `1 when not passed`	1
version	int	No	The current version number of the expected edit, used for concurrency protection	1
album_status	int	No	Required when `operation_type=2`. 1: Not launched; 2: Updating; 3: Completed	3
album_info	object(AlbumInfoInput)	No	Required when `operation_type=1` and it is the first time to upload show information	See example
episode_info_list	array(object(EpisodeInfoInput))	No	Required when `operation_type=1`	See example

AlbumInfoInput

Field Name	Type	Description	Sample Value
language	int	Language Enumeration Value	2
title	string	Drama Title	demo drama
seq_num	int	Total number of episodes in the series	40
cover_list	array(string)	List of Play Cover Image IDs	["b4c45eb643861b84b3b678a2f20e7acd"]
year	int	Launch Year	2026
album_status	int	Play editing status. 1: Not published; 2: Updating; 3: Completed	3
desp	string	Play Description	demo description
drama_type	int	Drama Type. 1: AIGC; 2: Comic Drama; 3: Live-Action Dubbing; 4: Live-Action Localization	2
tag_list	array(int)	Tag ID List	[101]
publish_status	int	Play listing and delisting status. 0: Default; 1: Listed; 2: Delisted	0

EpisodeInfoInput

Field Name	Type	Description	Sample Value
episode_id	string	Episode ID. It can be passed when updating an existing episode; it can be omitted when creating a new episode	7637437361307027476
title	string	Episode Title	episode_01
seq	int	Episode Number	1
cover_list	array(string)	Episode Cover Image ID List	["b4c45eb643861b84b3b678a2f20e7acd"]
byteplus_vid	string	BytePlus Video Unique Identifier	v188ebg00018d7v1vpf3ksl0c0f9goig

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/update/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "album_id": 7637420375425239060,
    "operation_type": 1,
    "version": 1,
    "album_info": {
        "language": 2,
        "title": "demo drama",
        "seq_num": 40,
        "cover_list": ["b4c45eb643861b84b3b678a2f20e7acd"],
        "year": 2026,
        "album_status": 3,
        "desp": "demo description",
        "drama_type": 2,
        "tag_list": [101]
    },
    "episode_info_list": [
        {
            "title": "episode_01",
            "seq": 1,
            "cover_list": ["b4c45eb643861b84b3b678a2f20e7acd"],
            "byteplus_vid": "v188ebg00018d7v1vpf3ksl0c0f9goig"
        }
    ]
}'

Return Value

Field Name	Type	Description	Sample Value
album_id	int64	Play ID	7637420375425239060
version	int	Newly generated play version number	2
episode_id_map	map(string,string)	Newly generated episode ID mapping. The key may be the episode_id passed in by the caller, or a placeholder key generated based on seq when episode_id is not passed	{"seq_1":"7637437361307027476"}
album_status	int	Play editing status. 1: Unpublished; 2: Updating; 3: Completed	3
publish_status	int	Play listing and delisting status. 0: Default; 1: Listed; 2: Delisted	0

Query Plays

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/query/
HTTP Method	GET
HTTP Header	`Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
album_id	int64	Yes	Play ID	7637420375425239060
version	int	No	Specify to query a specific version. When not passed, all version information of the show will be returned.	2

Request Example

curl --location --request GET 'https://open.tiktokapis.com/v2/sg/shortdrama/album/query/?album_id=7637420375425239060&version=2' \
--header 'Authorization: Bearer xxxxx'

Return Value

Field Name	Type	Description	Sample Value
album_version_list	array(object(AlbumVersionInfo))	List of Play Versions

AlbumVersionInfo

Field Name	Type	Description	Sample Value
album_id	int64	Play ID	7637420375425239060
version	int	Version Number	2
album_info	object(AlbumInfo)	Show Information
episode_info_list	array(object(EpisodeInfo))	Episode Information List
current_version	int	Current draft version number	2
online_version	int	Current online version number; empty when not set	1
publish_status	int	Play listing and delisting status. 0: Default; 1: Listed; 2: Delisted	1
review_status	int	Play moderation status. 0: Not submitted for moderation; 1: Under moderation; 2: Approved; 3: Rejected; 4: Withdrawn; 5: Appealing; 6: Appeal approved; 7: Appeal rejected	2

Upload subtitles

This interface is for asynchronous upload, please use the returned job_id to call the "Query Subtitles" interface for polling results.

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/subtitle/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
subtitle_url	string	Yes	Subtitle file download address, which must be a publicly accessible http or https link	https://vod.example.com/subtitle/xxx.srt
language	string	Yes	For subtitle language, it is recommended to use ISO 639-1 language codes	en
space_name	string	Yes	Name of the BytePlus space to which the video needs to be uploaded	test_space
byteplus_account_id	string	Yes	BytePlus account ID to which the video needs to be uploaded	333234234

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/subtitle/' \
--header 'Authorization: Bearer xxxxx' \
--header 'client-key: mnxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "subtitle_url": "https://vod.example.com/subtitle/xxx.srt",
    "language": "en",
    "byteplus_account_id":"234234234"
}'

Return Value

Field Name	Type	Description	Sample Value
job_id	string	Asynchronous upload task ID, used for subsequent polling to query the subtitle upload result	subtitle:job:1234567890

Query subtitles

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/subtitle/
HTTP Method	GET
HTTP Header	`Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
job_id	string		At least one of job_id and vid must be passed. It is recommended to use job_id for polling subtitle processing results after uploading.	subtitle:job:1234567890
vid	string		At least one of job_id and vid must be provided. After subtitle upload is completed, subtitle information can be queried via vid.	v188ebg00018d7v1vpf3ksl0c0f9goig
byteplus_account_id	string	Yes	BytePlus account ID to which the video needs to be uploaded	333234234

Request Example

curl --location --request GET 'https://open.tiktokapis.com/v2/sg/shortdrama/subtitle/?job_id=subtitle%3Ajob%3A1234567890&byteplus_account_id=xxxx' \
--header 'Authorization: Bearer xxxxx' \
--header 'client-key: mnxxxxxxxxxxxxx'

Return Value

Field Name	Type	Description	Sample Value
job_id	string	Subtitle Processing Task ID	subtitle:job:1234567890
upload_status	int	Subtitle upload status. 1: Processing; 2: Success; 3: Failure	1
vid	string	BytePlus Video ID of the associated video	v188ebg00018d7v1vpf3ksl0c0f9goig
subtitle_info_list	array(object(SubtitleInfo))	Subtitle list, see SubtitleInfo object definition	See SubtitleInfo

Bind Subtitles

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/subtitle/bind/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
vid	string	Yes	Video BytePlus Video ID	v188ebg00018d7v1vpf3ksl0c0f9goig
subtitle_id	string	Yes	Subtitle ID to be bound	subtitle_123

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/subtitle/bind/' \
--header 'Authorization: Bearer xxxxx' \
--header 'client-key: mnxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "vid": "v188ebg00018d7v1vpf3ksl0c0f9goig",
    "subtitle_id": "subtitle_123"
}'

Return Value

Field Name	Type	Description	Sample Value
vid	string	BytePlus Video ID of the video after subtitle binding	v188ebg00018d7v1vpf3ksl0c0f9goig
subtitle_id	string	Bound subtitle ID	subtitle_123

Episode Authorization

This interface is a batch operation interface. Please check the returned client_key_result_list item by item.

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/authorize/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
album_id	int64	Yes	Play ID	7637420375425239060
operate_type	int	Yes	Authorization operation type. 1: Add authorization; 2: Remove authorization	1
target_client_key_list	array(string)	Yes	List of target Mini Programs client_key	["mnabc123","mndef456"]

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/authorize/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "album_id": 7637420375425239060,
    "operate_type": 1,
    "target_client_key_list": ["mnabc123", "mndef456"]
}'

Return Value

Field Name	Type	Description	Sample Value
client_key_result_list	array(object(ClientKeyResult))	List of processing results for each target client_key

ClientKeyResult

Field Name	Type	Description	Sample Value
client_key	string	Target client_key	mnabc123
auth_status	int	Authorization status. 1: Authorized; 2: Removed	1
error_code	int	Error code when processing a single target fails	22010
error_message	string	Error message when a single target fails to process	authorization already exists

Set the online version

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/online_version/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
album_id	int64	Yes	Play ID	7637420375425239060
version	int	Yes	Needs to be set to the version number of the online version. This version must have passed moderation	2

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/online_version/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "album_id": 7637420375425239060,
    "version": 2
}'

Return Value

Field Name	Type	Description	Sample Value
album_id	int64	Play ID	7637420375425239060
online_version	int	Current online version number	2

Show listing and delisting

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/status/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
album_id	int64	Yes	Play ID	7637420375425239060
status	int	Yes	Status of play listing and delisting. 1: Listed; 2: Delisted	1

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/status/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "album_id": 7637420375425239060,
    "status": 1
}'

Return Value

Field Name	Type	Description	Sample Value
album_id	int64	Play ID	7637420375425239060
status	int	Current status of the play's availability. 1: Available; 2: Unavailable	1

Moderation

Submitted Drama for Moderation

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/review/submit/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
album_id	int64	Yes	Play ID	7637420375425239060
version	int	Yes	Version number of the play to be submitted for moderation	2
priority_score	int	No	Priority. 1: Urgent; 2: Normal For cases where a show requires advertising investment, etc., the priority can be set to urgent , and an organization can have a maximum of 35 submissions for moderation marked as urgent per day Moderation will be completed within 1-3 working days	2

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/review/submit/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "album_id": 7637420375425239060,
    "version": 2,
    "priority_score": 2
}'

Return Value

Field Name

Type

Description

Sample Value

result_type

int

Moderation result. 1: Success; 2: Partial success; 3: Failure

review_id

int64

Moderation Task ID

7637437361307027000

Appeal

Only appeals for rejected moderation items are supported.

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/review/appeal/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
client_key	string	Yes	Unique Identifier of Mini Programs Client	mnxxxxxxxxxxxxx
album_id	int64	Yes	Play ID	7637420375425239060
review_id	int64	Yes	Moderation Task ID	7637437361307027000
appeal_item_type	int	Yes	Type of object being appealed. 1: Play; 2: TV Series	2
item_id	string	Yes	Appeal object ID. When appealing for a drama, pass album_id; when appealing for an episode, pass the corresponding episode_id	7637437361307027476
appeal_reason	string	Yes	Reason for Appeal	this content should pass policy review
attachment_urls	array(string)	No	List of appeal attachment URLs, up to 10 items, with a maximum size of 200M per file	["https://example.com/appeal-1.png"]

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/review/appeal/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "client_key": "mnxxxxxxxxxxxxx",
    "album_id": 7637420375425239060,
    "review_id": 7637437361307027000,
    "appeal_item_type": 2,
    "item_id": "7637437361307027476",
    "appeal_reason": "this content should pass policy review",
    "attachment_urls": ["https://example.com/appeal-1.png"]
}'

Return Value

Field Name	Type	Description	Sample Value
No business data fields	-	After a successful appeal, only a generic success response will be returned, and the business result will be indicated through `BaseResp` / `Error`	-

Withdraw for review

Basic Information

HTTP URL	https://open.tiktokapis.com/v2/sg/shortdrama/album/review/withdraw/
HTTP Method	POST
HTTP Header	`Content-Type`: Pass a fixed value`application/json` `Authorization` : Bearer `access_token`

Request Parameters

Field Name	Type	Required	Description	Sample Value
album_id	int64	Yes	Play ID	7637420375425239060
version	int	Yes	The version number to be recalled for review	2

Request Example

curl --location 'https://open.tiktokapis.com/v2/sg/shortdrama/album/review/withdraw/' \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "album_id": 7637420375425239060,
    "version": 2
}'

Was this document helpful?