HTTP URL

https://open.tiktokapis.com/v2/research/video/query/

HTTP 请求方法

POST

权限范围

research.data.basic (必要权限)

Key

类型

描述

示例

是否必填

Content-Type

字符串 (String)

资源的原始媒体类型。

"application/json"

是

Authorization

字符串 (String)

通过 /v2/oauth/token/ 获取的客户端访问令牌。

Bearer clt.example12345Example12345Example

是

Key

类型

描述

示例

是否必填

fields

字符串 (String)

请求的字段。从 Video 对象的字段中选择。

完整列表：

id,video_description,create_time, region_code,share_count,view_count,like_count,comment_count, music_id,hashtag_names, username,effect_ids,playlist_id,voice_to_text, is_stem_verified, favorites_count, video_duration,hashtag_info_list, sticker_info_list, effect_info_list, video_mention_list,video_label,video_tag

是

Key

类型

描述

示例

是否必填

query

Query 对象

（参见下文定义）

JSON 对象，包含 and、or 和 not 三类子项，每个子项代表一个条件列表。有效查询必须至少包含一个非空的 and、or 或 not 条件列表。

{

"and":[

{

"operation":"IN",

"field_name":"region_code",

"field_values":[

"JP",

"US"

]

},

{

"operation":"EQ",

"field_name":"keyword",

"field_values":["animal"]

}

],

"not":[

{

"operation":"LT",

"field_name":"create_date",

"field_values":["20230101"]

}

]

}

是

start_date

字符串 (String)

视频创建时间的 UTC 起始时间。

"20210102"

是

end_date

字符串 (String)

视频创建时间的 UTC 结束时间。

end_date 和 start_date 之间的间隔不得超过 30 天。

"20210123"

是

max_count

int64

响应返回的视频数量。默认值为 20，最大值为 100。

由于用户删除视频或将视频设为私密等原因，接口实际返回的视频数量可能少于 max_count 中设定的最大数量。

20

否

cursor

int64

指定开始检索视频结果的索引位置。

100

否

search_id

字符串 (String)

分配给缓存搜索结果的唯一标识符。后续查询时，可以使用该 search_id，根据相同的查询条件继续检索更多结果。

"7201388525814961198"

否

is_random

布尔值 (Boolean)

该 flag 用于控制是否以随机顺序返回结果：

若设为 true，接口将返回 1–100 条符合查询条件的随机顺序视频。

若设为 false 或未赋值，则返回结果默认按视频 ID 降序排列。

true

否

Key

类型

描述

是否必填

and

list<Condition>

and 条件规定查询结果必须满足列表中的所有条件。

否

or

list<Condition>

or 条件规定查询结果必须满足至少一个列表中的条件。

否

not

list<Condition>

not 条件规定查询结果不能符合任何列表中的条件。

否

字段

类型

描述

field_name

字符串 (String)

此条件限制的字段名。

以下任一：["create_date", "username", "region_code", "video_id", "hashtag_name", "keyword", "music_id", "effect_id", "video_length", "view_count", "comment_count"]

operation

字符串 (String)

以下任一：“EQ”、“IN”、“GT”、“GTE”、“LT”、“LTE”。

field_values

list<string>

限制值列表。

字段

描述

示例

create_date

视频的 UTC 创建时间，格式为 YYYYMMDD。

20220910

username

视频创作者的用户名。

"cookie_love_122"

region_code

视频创作者账号的注册国家/地区的两位数代码。

"FR", "TH", "MM", "BD", "IT", "NP", "IQ", "BR", "US", "KW", "VN", "AR", "KZ", "GB", "UA", "TR", "ID", "PK", "NG", "KH", "PH", "EG", "QA", "MY", "ES", "JO", "MA", "SA", "TW", "AF", "EC", "MX", "BW", "JP", "LT", "TN", "RO", "LY", "IL", "DZ", "CG", "GH", "DE", "BJ", "SN", "SK", "BY", "NL", "LA", "BE", "DO", "TZ", "LK", "NI", "LB", "IE", "RS", "HU", "PT", "GP", "CM", "HN", "FI", "GA", "BN", "SG", "BO", "GM", "BG", "SD", "TT", "OM", "FO", "MZ", "ML", "UG", "RE", "PY", "GT", "CI", "SR", "AO", "AZ", "LR", "CD", "HR", "SV", "MV", "GY", "BH", "TG", "SL", "MK", "KE", "MT", "MG", "MR", "PA", "IS", "LU", "HT", "TM", "ZM", "CR", "NO", "AL", "ET", "GW", "AU", "KR", "UY", "JM", "DK", "AE", "MD", "SE", "MU", "SO", "CO", "AT", "GR", "UZ", "CL", "GE", "PL", "CA", "CZ", "ZA", "AI", "VE", "KG", "PE", "CH", "LV", "PR", "NZ", "TL", "BT", "MN", "FJ", "SZ", "VU", "BF", "TJ", "BA", "AM", "TD", "SI", "CY", "MW", "EE", "XK", "ME", "KY", "YE", "LS", "ZW", "MC", "GN", "BS", "PF", "NA", "VI", "BB", "BZ", "CW", "PS", "FM", "PG", "BI", "AD", "TV", "GL", "KM", "AW", "TC", "CV", "MO", "VC", "NE", "WS", "MP", "DJ", "RW", "AG", "GI", "GQ", "AS", "AX", "TO", "KN", "LC", "NC", "LI", "SS", "IR", "SY", "IM", "SC", "VG", "SB", "DM", "KI", "UM", "SX", "GD", "MH", "BQ", "YT", "ST", "CF", "BM", "SM", "PW", "GU", "HK", "IN", "CK", "AQ", "WF", "JE", "MQ", "CN", "GF", "MS", "GG", "TK", "FK", "PM", "NU", "MF", "ER", "NF", "VA", "IO", "SH", "BL", "CU", "NR", "TP", "BV", "EH", "PN", "TF", "RU"

video_id

视频的唯一标识符。

6978662169214864645

hashtag_name

与视频关联的话题标签。

"arianagrande", "celebrity"

keyword

视频描述中的关键字。

"tiktok"

music_id

视频的音乐 ID。

"8978345345214861235"

effect_id

视频的特效 ID。

"3957392342148643476"

video_length

视频时长。

SHORT: <15s

MID: 15 ~60s

LONG: 1~5min

EXTRA_LONG: >5min

"SHORT", "MID", "LONG", "EXTRA_LONG"

view_count

视频的播放量。

10

comment_count

视频的评论数。

10

Key

类型

示例

data

QueryVideoResponseData

{

"videos": [...],

"cursor": 100,

"has_more": true,

"search_id": ""

}

error

ErrorStruct

Error 对象。

字段

类型

描述

videos

list<Video Object>

匹配查询条件的视频对象列表。

cursor

int64

从指定索引处开始返回视频结果。

has_more

布尔值 (Boolean)

是否还有更多视频。

search_id

字符串 (String)

search_id 是系统为缓存的查询结果分配的唯一标识符。后续查询时，可以使用该 search_id，根据相同的查询条件继续检索更多结果。

字段

类型

描述

"id"

int64

TikTok 视频的唯一标识符，也称为“item_id”或“video_id”。

"create_time"

int64

TikTok 视频发布时的 UTC Unix 时间戳（单位：秒）。

"username"

字符串 (String)

视频作者的用户名。

"region_code"

字符串 (String)

视频创作者账号的注册国家/地区的两位数代码。

"video_description"

字符串 (String)

视频的描述，也称为标题。

"music_id"

int64

视频中使用的 music_id。

"like_count"

int64

视频的获赞数。

"comment_count"

int64

视频的评论数。

"share_count"

int64

视频的分享次数。

"view_count"

int64

视频的播放量。

"effect_ids"

list<string>

视频使用的特效 ID 列表。

"hashtag_names"

list<string>

视频参与的话题标签列表。

"hashtag_info_list"

结构体 (Struct)

包含“hashtag_id”和“hashtag_description”。每个 hashtag_name 对应的唯一 hashtag_id 和 hashtag_description（如有）。

"sticker_info_list"

结构体 (Struct)

包含“sticker_id”和“sticker_name”。视频可用的互动贴纸详情。

"effect_info_list"

结构体 (Struct)

包含“effect_id”、“effect_name”和“effect_photo_url”。视频中所用特效的更多详情。

"video_mention_list"

list<string>

视频中提及的其他用户。

"video_label"

结构体 (Struct)

返回与视频关联的所有信息和标签。

"playlist_id"

int64

视频所属播放列表的 ID。

"voice_to_text"

字符串 (String)

语音转文字和字幕（已开启语音转文字功能的视频将显示生成的文字）。

is_stem_verified

布尔值 (Boolean)

视频是否已验证为高质量 STEM 内容。

video_duration

int64

视频时长（单位：秒）。

favorites_count

int64

视频被收藏的次数。

video_tag

结构体 (Struct)

返回“type”和“number”。

说明：

1. number = 1 且 type = AIGC Type，表示创作者被标记为由 AI 生成。
2. number = 2 且 type = AIGC Type，表示由 AI 生成。
3. number = 1 且 type = Branded Type，表示品牌合作。
4. number = 7 且 type = Branded Type，表示创作者赚取佣金。