Developer resources

Search for videos — TikTok Business API

Search for videos · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Open in the API index TikTok Business platform page

Search for videos

GET/file/video/ad/search/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/file/video/ad/search/

Description

Use this endpoint to search for video creatives that can be used in ads in the Asset Library of an ad account.

The response will only include the 10,000 most recently modified videos.

Comparing v1.2 and v1.3

The following table outlines the differences between v1.2 and v1.3 endpoints.

 |Changes{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|Endpoint path|/v1.2/file/video/ad/search/|/v1.3/file/video/ad/search/|
|Request parameter data type |`advertiser_id`: number|`advertiser_id`: string|
|Request parameters deprecated in v1.3|/|`height`
`ratio`
`width`
`displayable`|
|Response parameter name|`poster_url`
`url` |`video_cover_url`
`preview_url`|
|Response parameters deprecated in v1.3|/|`id`|
|New request parameters|/|`video_name`
`video_material_sources`
`sort_field`|
|New response parameters|/|`preview_url_expire_time`|

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/file/video/ad/search/

Authentication & shop

Name	In	Type	Sample	Description
Authorization	header	header	Bearer q360_live_ab12cd34_…	Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_id	query	string	7000000000000000001	Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

Name	In	Type	Required	Description
filtering	query	object	No	Filters on the data. This parameter is an array of filter objects.
sort_field	query	string	No	The sorting criteria for the video list. Enum values: - `CREATE_TIME`: To sort the results by video creation time in descending order, returning the most recently created videos at the top of the list. - `MODIFY_TIME`: To sort the results by the time the video was last updated in descending order, returning the most recently updated videos at the top of the list. Default value: `CREATE_TIME`.
page	query	number	No	Current page number. Default value: 1. Value range: ≥ 1.
page_size	query	number	No	Page size. Default value: 20. Value range: 1-100.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/file/video/ad/search/" \
  -H "Authorization: Bearer $KEY"

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/file/video/ad/search/",
    params={},
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())

Node.js

const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/file/video/ad/search/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());

PHP

<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/file/video/ad/search/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

Name	Type	Description
code	number	Return code, see Appendix-Return code.
message	string	Return Message, see Appendix-Return Information.
data	object	Returned data.
list	object[]	A list of video information.
video_id	string	Video ID, which can be used to create ads. Note: If the filter field `video_ids` is not passed, and multiple video IDs have been generated for the same video due to multiple uploads, only one valid video ID will be returned for the video.
video_cover_url	string	Temporary URL for video cover, valid for six hours and needs to be re-acquired after expiration. The expiration time is included in the URL after the `x-expires` parameter, in the format of an Epoch/Unix timestamp in seconds. Example: `
format	string	video Format
preview_url	string	Video preview link, valid for six hours and needs to be re-acquired after expiration. To find out the expiration time of the preview link, see `preview_url_expire_time`.
preview_url_expire_time	string	The expiration time of the video preview link, in the format of `YYYY-MM-DD HH:MM:SS`(UTC+0).
duration	float	Video duration, in seconds.
height	number	Video height.
width	number	Video width.
bit_rate	float	Bit rate, in bps
signature	string	MD5 of the video file.
size	number	Video size.
material_id	string	Material ID.
allowed_placements	string[]	Available placements. Due to music copyright, some materials generated by creative tools can only be shown on TikTok. It won't pass when they are created on other placements. For enum values, see Enumerations-Ad Management-Placement.
allow_download	boolean	Whether the video is downloadable. Due to the music copyright, some materials generated by creative tools are only allowed to preview. It is prohibited to download and disseminate them.
file_name	string	Video name.
create_time	string	Creation time. UTC time. Format: 2020-06-10T07:39:14Z.
modify_time	string	Modification time. UTC time. Format: 2020-06-10T07:39:14Z
displayable	boolean	Whether it can be displayed on the platform.
page_info	object	Pagination information.
page	number	Current page number.
page_size	number	Page size.
total_number	number	Total number of results.
total_page	number	Total pages of results.
request_id	string	The log id of a request, which uniquely identifies the request.

Response sample

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "page_info": {
            "total_number": 1,
            "page": 1,
            "page_size": 20,
            "total_page": 1
        },
        "list": [
            {
                "video_cover_url": "http://p16-sign-sg.tiktokcdn.com/v0201/94ebe1a3e6734559a16f3e81c43787ec~tplv-noop.image?x-expires=1607260002&x-signature=falvnSNOT94w4gjeB8PGGFyAdys%3D",
                "format": "mp4",
                "preview_url": "http://v16m-default.akamaized.net/64d28cac783ab57b70c2d91c30fb1b5d/5fccd762/video/tos/alisg/tos-alisg-v-0000/9a0033884eab42248ad6b46f7b11e44c/?a=0&br=3114&bt=1557&cd=0%7C0%7C0&cr=0&cs=0&dr=0&ds=3&er=&l=2020120607063701011517615517A19974&lr=ad&mime_type=video_mp4&qs=0&rc=anNlbnRuOWU2eDMzZjYzM0Apdjh3ZHJuOWZzZTMzNDY6eWdwMnFebGgzYG1fLS0uMDRzc2RtX2huaDNfMHItLWAwLS06Yw%3D%3D&vl=&vr=",
                "file_name": "wanfadong_test.mp4",
                "displayable": true,
                "height": 720,
                "width": 1280,
                "bit_rate": 1594584,
                "create_time": "2020-11-16T08:19:57Z",
                "modify_time": "2020-11-16T08:19:57Z",
                "signature": "b24f08f569b73a33eec93edb8f4423e2",
                "duration": 5.312,
                "video_id": "v070331c0000bup3cb66kkoqaktb5psg",
				"material_id": "6895633277416374000",
            	"allowed_placements": [
                    "PLACEMENT_TOPBUZZ",
                    "PLACEMENT_TIKTOK",
                    "PLACEMENT_HELO",
                    "PLACEMENT_PANGLE"
            	],
            	"allow_download": true,
                "size": 1058804
            }
        ]
    },
    "request_id": "2020120607063701011517615517A19974"
}
(/code);

Get started

Sign up for Partner
Enable a data type of the Ads (Marketing API) group on the platform page
Create an API key (tick the TikTok Business channel)
Call it as in the examples above