TikTok 视频详情 & 列表 API 接口技术文档（带全套 JSON 样例・核心章节）

原创

Anzexi58

修改于 2026-06-04 16:59:04

190

前言

一、接口整体说明

TikTok 视频接口分两类：①用户作品列表接口（批量拉取多视频）、②单条视频详情接口（指定 aweme_id 查单品），通用cursor游标分页，不使用 page 页码；鉴权统一 Header：Authorization: Bearer ApiKey，单页上限 20~35 条，QPS 官方限流 3 次 /s。

1. 接口地址与入参

（1）用户作品列表（批量列表）

请求：GET /api/v1/tiktok/user/post/list

// 请求入参JSON
{
    "sec_user_id": "MS4wLjABAAAA8fKxxxxxxx",
    "max_cursor": "0",
    "limit": 20,
    "region": "US"
}

表格

参数	必填	释义
sec_user_id	是	创作者唯一安全 ID，主页链接提取
max_cursor	否	分页游标，首次 = 0，下一页用上轮返回 max_cursor
limit	否	单页条数，1~35
region	否	地区码 US/GB/JP 等

（2）单视频详情接口

请求：GET /api/v1/tiktok/video/detail

{
    "aweme_id":"7528963259874125698"
}

二、接口原生返回 JSON（脱敏真实原版・列表 + 单详情）

1. 用户作品列表原始返回 JSON

原生嵌套层级深：作者信息、视频资源、音乐、互动统计多层内嵌，含大量冗余扩展字段，无法直接入库。

{
    "code":0,
    "msg":"success",
    "request_id":"tk_req_95632187",
    "data":{
        "has_more":true,
        "max_cursor":"1750236985000",
        "min_cursor":"0",
        "aweme_list":[
            {
                "aweme_id":"7528963259874125698",
                "desc":"Summer daily outfit✨ #fashion #ootd #summerlook",
                "create_time":1750212365,
                "is_private":false,
                "author":{
                    "uid":"6952369874521",
                    "unique_id":"lily_fashion_us",
                    "nickname":"Lily Fashion",
                    "avatar":"https://p3.tiktokcdn.com/tos-maliva-avt/xxx.jpg",
                    "signature":"Daily fashion sharing | US blogger",
                    "is_verified":true
                },
                "video":{
                    "duration":12800,
                    "width":1080,
                    "height":1920,
                    "cover":{
                        "url_list":["https://p3.tiktokcdn.com/tos-maliva-video/cover1.jpg"]
                    },
                    "play_addr":{
                        "url_list":["https://v16-web.tiktok.com/xxx.mp4"]
                    }
                },
                "music":{
                    "music_id":"7489562135987",
                    "title":"Sunny Day Vibe",
                    "author":"DJ Mark",
                    "cover":"https://p3.tiktokcdn.com/tos-maliva-music/msc.jpg"
                },
                "statistics":{
                    "digg_count":12589,
                    "comment_count":892,
                    "share_count":326,
                    "collect_count":1563,
                    "play_count":215689
                },
                "text_extra":[
                    {"hashtag_name":"fashion","hashtag_id":"523698"},
                    {"hashtag_name":"ootd","hashtag_id":"256987"}
                ]
            },
            {
                "aweme_id":"7528959874125369852",
                "desc":"Affordable casual clothes haul🛒 #clothes #shopping",
                "create_time":1750198652,
                "is_private":false,
                "author":{
                    "uid":"6952369874521",
                    "unique_id":"lily_fashion_us",
                    "nickname":"Lily Fashion",
                    "avatar":"https://p3.tiktokcdn.com/tos-maliva-avt/xxx.jpg",
                    "signature":"Daily fashion sharing | US blogger",
                    "is_verified":true
                },
                "video":{
                    "duration":9600,
                    "width":1080,
                    "height":1920,
                    "cover":{"url_list":["https://p3.tiktokcdn.com/tos-maliva-video/cover2.jpg"]},
                    "play_addr":{"url_list":["https://v16-web.tiktok.com/xxx2.mp4"]}
                },
                "music":{
                    "music_id":"7489561236954",
                    "title":"Shopping Mood",
                    "author":"Luna Band",
                    "cover":"https://p3.tiktokcdn.com/tos-maliva-music/msc2.jpg"
                },
                "statistics":{
                    "digg_count":9856,
                    "comment_count":632,
                    "share_count":215,
                    "collect_count":986,
                    "play_count":159632
                },
                "text_extra":[
                    {"hashtag_name":"clothes","hashtag_id":"326985"},
                    {"hashtag_name":"shopping","hashtag_id":"159874"}
                ]
            }
        ]
    }
}

2. 单条视频详情原生 JSON（精简）

{
    "code":0,
    "msg":"success",
    "data":{
        "aweme_detail":{
            "aweme_id":"7528963259874125698",
            "desc":"Summer daily outfit✨ #fashion #ootd #summerlook",
            "create_time":1750212365,
            "author":{
                "unique_id":"lily_fashion_us",
                "nickname":"Lily Fashion",
                "is_verified":true
            },
            "statistics":{
                "digg_count":12589,
                "comment_count":892,
                "share_count":326,
                "collect_count":1563,
                "play_count":215689
            },
            "video":{
                "duration":12800,
                "cover":{"url_list":["https://p3.tiktokcdn.com/cover1.jpg"]},
                "play_addr":{"url_list":["https://v16-web.tiktok.com/xxx.mp4"]}
            },
            "music":{
                "title":"Sunny Day Vibe","author":"DJ Mark"
            }
        }
    }
}

三、原生 JSON 现存痛点

时间是 Unix 时间戳，无法直接展示、按日期统计；
话题标签text_extra为数组嵌套，标签和 ID 混存，关键词提取繁琐；
视频封面、播放地址放在url_list数组内，多链接冗余，仅取首图即可；
作者信息深度内嵌，不利于创作者、视频分表存储；
空字段（无音乐 / 无话题）字段结构不一致，遍历易空指针异常；
分页游标分散在顶层 data，批量采集需单独存储max_cursor。

四、结构化解析后标准 JSON（业务落地模型，可直接入库 MySQL/ES）

扁平化字段、时间格式化、标签数组提取、资源精简，是竞品分析、爆款筛选、达人数据统计标准格式：

{
    "next_cursor":"1750236985000",
    "has_more":true,
    "video_list":[
        {
            "aweme_id":"7528963259874125698",
            "video_desc":"Summer daily outfit✨ #fashion #ootd #summerlook",
            "publish_ts":1750212365,
            "publish_time":"2025-03-19 14:06:05",
            "is_private":false,
            "author_info":{
                "uid":"6952369874521",
                "unique_id":"lily_fashion_us",
                "nickname":"Lily Fashion",
                "avatar":"https://p3.tiktokcdn.com/tos-maliva-avt/xxx.jpg",
                "signature":"Daily fashion sharing | US blogger",
                "is_verified":true
            },
            "video_resource":{
                "duration_ms":12800,
                "duration_sec":12.8,
                "width":1080,
                "height":1920,
                "cover_img":"https://p3.tiktokcdn.com/tos-maliva-video/cover1.jpg",
                "play_url":"https://v16-web.tiktok.com/xxx.mp4"
            },
            "music_info":{
                "music_id":"7489562135987",
                "music_name":"Sunny Day Vibe",
                "music_author":"DJ Mark",
                "music_cover":"https://p3.tiktokcdn.com/tos-maliva-music/msc.jpg"
            },
            "stats":{
                "play":215689,
                "like":12589,
                "comment":892,
                "share":326,
                "collect":1563
            },
            "hashtags":["fashion","ootd","summerlook"]
        },
        {
            "aweme_id":"7528959874125369852",
            "video_desc":"Affordable casual clothes haul🛒 #clothes #shopping",
            "publish_ts":1750198652,
            "publish_time":"2025-03-19 09:37:32",
            "is_private":false,
            "author_info":{
                "uid":"6952369874521",
                "unique_id":"lily_fashion_us",
                "nickname":"Lily Fashion",
                "avatar":"https://p3.tiktokcdn.com/tos-maliva-avt/xxx.jpg",
                "signature":"Daily fashion sharing | US blogger",
                "is_verified":true
            },
            "video_resource":{
                "duration_ms":9600,
                "duration_sec":9.6,
                "width":1080,
                "height":1920,
                "cover_img":"https://p3.tiktokcdn.com/tos-maliva-video/cover2.jpg",
                "play_url":"https://v16-web.tiktok.com/xxx2.mp4"
            },
            "music_info":{
                "music_id":"7489561236954",
                "music_name":"Shopping Mood",
                "music_author":"Luna Band",
                "music_cover":"https://p3.tiktokcdn.com/tos-maliva-music/msc2.jpg"
            },
            "stats":{
                "play":159632,
                "like":9856,
                "comment":632,
                "share":215,
                "collect":986
            },
            "hashtags":["clothes","shopping"]
        }
    ]
}

五、异常返回 JSON（错误码参考，异常捕获必备）

// Token失效
{
    "code":401,
    "msg":"ApiKey invalid or expired",
    "request_id":"tk_err_125698",
    "data":{}
}
// 接口限流
{
    "code":429,
    "msg":"Request frequency limit, wait 15s",
    "data":{}
}
// 无效用户ID
{
    "code":400,
    "msg":"sec_user_id not found",
    "data":{}
}

六、核心解析实战要点

时间标准化：create_time时间戳转yyyy-MM-dd HH:mm:ss，新增秒数字段duration_sec便于筛选短视频；
话题标签提取：遍历text_extra数组，只提取hashtag_name生成纯标签数组；
资源地址精简：封面、播放链接只取url_list[0]首地址，剔除冗余备用 CDN 链接；
空值容错：无音乐时music_info设为空对象，无话题hashtags=[]，规避索引报错；
分页采集逻辑：has_more=true则带入max_cursor循环翻页，直到 false 结束全量抓取。

七、极简 Python 解析示例（配套实战代码）

import time

def parse_tiktok_video(raw_json):
    res = {}
    resp = raw_json.get("data",{})
    res["next_cursor"] = resp.get("max_cursor","")
    res["has_more"] = resp.get("has_more",False)
    video_arr = []
    for item in resp.get("aweme_list",[]):
        video = {}
        video["aweme_id"] = item["aweme_id"]
        video["video_desc"] = item["desc"]
        ts = item["create_time"]
        video["publish_ts"] = ts
        video["publish_time"] = time.strftime("%Y-%m-%d %H:%M:%S",time.localtime(ts))
        video["is_private"] = item["is_private"]
        #作者信息
        au = item["author"]
        video["author_info"] = au
        #视频资源
        vd = item["video"]
        video["video_resource"] = {
            "duration_ms":vd["duration"],
            "duration_sec":round(vd["duration"]/1000,1),
            "width":vd["width"],
            "height":vd["height"],
            "cover_img":vd["cover"]["url_list"][0],
            "play_url":vd["play_addr"]["url_list"][0]
        }
        #互动数据
        st = item["statistics"]
        video["stats"] = {
            "play":st["play_count"],
            "like":st["digg_count"],
            "comment":st["comment_count"],
            "share":st["share_count"],
            "collect":st["collect_count"]
        }
        #话题标签
        tags = [i["hashtag_name"] for i in item.get("text_extra",[])]
        video["hashtags"] = tags
        video_arr.append(video)
    res["video_list"] = video_arr
    return res

八、落地业务场景

海外达人监控：批量抓取博主作品播放 / 点赞，筛选潜力达人；
爆款内容挖掘：按播放、互动率筛选高流量短视频，复盘爆款标签；
跨境选品分析：穿搭 / 好物类视频统计热门品类、关键词，辅助选品；
竞品账号跟踪：定时拉取竞品作品数据，监控上新与流量变化。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

api-key

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

api-key

登录后参与评论

0 条评论

热度

TikTok 视频详情 & 列表 API 接口技术文档（带全套 JSON 样例・核心章节）

TikTok 视频详情 & 列表 API 接口技术文档（带全套 JSON 样例・核心章节）

一、接口整体说明

1. 接口地址与入参

（1）用户作品列表（批量列表）

（2）单视频详情接口

二、接口原生返回 JSON（脱敏真实原版・列表 + 单详情）

1. 用户作品列表原始返回 JSON

2. 单条视频详情原生 JSON（精简）

三、原生 JSON 现存痛点

四、结构化解析后标准 JSON（业务落地模型，可直接入库 MySQL/ES）

五、异常返回 JSON（错误码参考，异常捕获必备）

六、核心解析实战要点

七、极简 Python 解析示例（配套实战代码）

八、落地业务场景

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐