Developer resources

Get suggested thumbnails for a video — TikTok Business API

Get suggested thumbnails for a video · 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

Get suggested thumbnails for a video

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

Description

Use this endpoint to get a list of suggested video thumbnails based on a video creative. You can preview the thumbnails using the URLs in the response, and then you can set one of the images as the thumbnail for your video ad.

> Note

> If you want to get video thumbnail suggestions for a recently uploaded video, we recommend waiting for 30 seconds to five minutes before calling this endpoint. This allows the video to be transcoded and processed. Calling the endpoint before the transcoding process is complete may result in an Insufficient permissions for some videos error.

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/suggestcover/|/v1.3/file/video/suggestcover/|
|Request parameter data type |`advertiser_id`: number|`advertiser_id`: string|

Request

Endpoint

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

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	Sample	Description
video_id	query	string	Yes		Video ID.
poster_number	query	number	No		Number of cover candidates you want to get. Range: `1-10`. Default value: `10` .If the total number of cover candidates is less than the number given, all candidates will be returned.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/file/video/suggestcover/?video_id=" \
  -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/suggestcover/",
    params={
        "video_id": ""
    },
    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/suggestcover/');
for (const [k, v] of Object.entries({"video_id":""})) 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/suggestcover/' . '?' . http_build_query(['video_id' => '']);
$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 image information.
width	number	Image width.
height	number	Image height.
id	string	Image ID.
url	string	Picture preview address, valid for an hour and needs to be re-acquired after expiration.
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": {
        "list": [
          {
            "url": "http://p1.ipstatp.com/large/tos-useast2a-p-0000/8cc546a4b96a4933a27b0c7fefdd66a9_1584964597",
            "width": 560,
            "id": "tos-useast2a-p-0000/8cc546a4b96a4938a27b0c7fefdd66a9_1584964597",
            "height": 320
          },
          {
            "url": "http://p1.ipstatp.com/large/tos-useast2a-p-0000/36973f6fd2344c9fa5889db57d743ac6_1584964597",
            "width": 560,
            "id": "tos-useast2a-p-0000/36973f6fd2344c90a5889db57d743ac6_1584964597",
            "height": 320
          }
        ]
    },
    "request_id": "2020032312235001018904922349195A66"
}
(/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