tiktok-research

TikTok 研究

使用 Crawlora 的标准化 REST 端点回答 TikTok 相关研究问题。结论应以返回的公开数据为依据：信息流或搜索样本并不等于完整普查，指标也不能证明视频或广告表现出色的原因。

设置和请求

将 CRAWLORA_API_KEY 设置为从 crawlora.net 获取的密钥，然后运行此技能附带的辅助工具。它会向 https://api.crawlora.net/api/v1 发送 x-api-key；请将密钥保存在环境变量中，切勿将其放入 URL、提示词输出或保存的文件中。

Set `CRAWLORA_API_KEY` in the environment before running the helper.

scripts/crawlora.sh /tiktok/profile/chatgpt | jq '.'
scripts/crawlora.sh /tiktok/search keyword="ai agents" count=20 | jq '.'
scripts/crawlora.sh /tiktok/post/7444278905264983342 | jq '.'

阅读 reference/endpoints.md，查看完整的端点列表和当前参数名称。检查 HTTP 结果和 JSON 信封：HTTP 请求成功时，应用层 code 仍可能非零，也可能包含嵌套的上游错误，或没有可用结果。

选择工作流

个人资料、视频和评论

1. 调用 /tiktok/profile/{handler}，句柄中不要包含 @。
2. 要获取个人资料的视频，请将返回的 user.secUid 原样传递给 /tiktok/posts。不要替换成数字用户 ID 或显示名称。sort_type 可设为 0（最新）、1（最热门）或 2（最早）。
3. 使用 /tiktok/post/{id} 获取单个视频的详情。使用 /tiktok/comments 和该视频的 aweme_id（URL 中的视频 ID）获取顶层评论。
4. 仅在用户要求的范围内跟进返回的游标。保留游标类型，并在 has_more/hasMore 为 false 时停止；不要假设每个 TikTok 响应都使用相同的大小写格式。

搜索和发现

• /tiktok/search 按关键词查找视频。
• /tiktok/search/hashtag 查找话题标签／挑战候选项。
• /tiktok/search/user 按关键词查找用户。
• /tiktok/hashtag/{name} 解析话题标签并返回其 ID；将该 ID 传递给 /tiktok/hashtags 以获取相关视频。
• /tiktok/category 用于发现 Explore 类别；将返回的类别 type 传递给 /tiktok/explore/{id}。

使用前一步调用返回的标识符。搜索匹配结果和话题标签计数反映的是 TikTok 当前索引中的信息，并不能证明每个结果都与指定品牌或主题相关。作出明确归因前，请通过返回的个人资料、说明文字、来源 URL 或详情记录核实身份。

趋势和 Creative Center

• /tiktok/trending 返回当前推荐／热门信息流。
• /tiktok/creative-center/hashtags 返回按国家／地区和时间段排名的话题标签。
• /tiktok/creative-center/videos 返回排名视频，可按内容标签或 organic_only 筛选，也可按 views、engagement 或 six_second_views 排序。
• /tiktok/popular-trend/country-industry-meta 在需要说明 Creative Center 上下文时提供国家／地区和行业元数据。

务必报告国家／地区、时间段、排序／筛选选项、获取时间和样本量。“热门”取决于展示位置和时间；不要将其描述为全球或历史排名。

移动应用发现

/tiktok/mobile/* 路由提供独立于网页端/Creative Center 路由的 TikTok 应用界面：

• /tiktok/mobile/feed 是个性化且因地区而异的 For You 样例。它没有国家或历史时期筛选条件，也不是全球趋势排名。
• /tiktok/mobile/search、/search/music 和 /search/user 分别搜索移动应用的视频、声音和用户界面。请将移动端结果标识和游标与相应的网页端搜索结果分开保存。
• /tiktok/mobile/music/trending 和 /music/pick 返回声音榜单界面；使用返回的 music_id 调用 /music/posts，获取使用该声音的视频。music/posts 为兼容性接受 count，但上游会自行选择页面大小，因此请继续使用返回的游标。/music/related 从视频 aweme_id 开始。
• /tiktok/mobile/music/beats 返回一个包含实测声音榜单的页面，不带分页字段；count 并非经过验证的页面大小控制项。/music/collections 返回第一页合集动态；其公布的游标无法重复使用，因此不要声称已覆盖所有合集。
• /tiktok/mobile/trending/categories 和 /trending/effects 是当前应用发现动态，支持游标分页，并非固定的类别分类体系或跨市场排名。请保留返回的地区/主机上下文和检索时间；不要将其中的数量等同于 Creative Center 指标。
• /tiktok/mobile/live/search 需要关键词，并返回用于搜索发现的 LIVE 直播间锚点。它不是直播目录，也不能保证直播间当前可用；请保留返回的直播间 ID 和观察到的观众字段。
• /tiktok/mobile/live/gifts 返回完整的 LIVE 礼物目录及配置/资源映射；/tiktok/mobile/live/effects 返回完整的特效/贴纸资源目录。二者都是大型、无分页且不带筛选条件的快照。请将其用于目录元数据，而非趋势排名、当前使用情况，或根据 diamond_count 推断现实价格。
• 标签详情需要配置好的应用会话。没有会话时，热门标签帖子仅通过美国出口节点填充；使用 fresh 获取最新帖子，并将地区外热门页面为空视为覆盖数据不可用，而非标签活动量为零。

scripts/crawlora.sh /tiktok/mobile/music/trending count=10
scripts/crawlora.sh /tiktok/mobile/music/collections
scripts/crawlora.sh /tiktok/mobile/live/search keyword="lofi" count=10
scripts/crawlora.sh /tiktok/mobile/live/gifts
scripts/crawlora.sh /tiktok/mobile/live/effects
scripts/crawlora.sh /tiktok/mobile/trending/categories count=10
scripts/crawlora.sh /tiktok/mobile/trending/effects count=5

Top Ads 情报分析

对于匹配广告研究，请先调用 /tiktok/top-ads/filters，以发现当前动态的国家、行业、目标、语言和模式标签 ID。比较时请保持时期、国家、目标和排序方式一致。然后：

1. 使用约定的筛选条件和有界的 limit 搜索 /tiktok/top-ads/list。在输出中注明 period（7、30 或 180）和 order_by（for_you、impression、ctr、play_2s_rate、play_6s_rate、cvr 或 like）。
2. 对返回的素材去重，并将每个返回的 id 作为 material_id 传给 /tiktok/top-ads/detail。这是 Top Ads 素材 ID，不是广告的 TikTok 视频 ID；详情端点不接受 id 和 materialId。
3. 使用 /tiktok/top-ads/analysis 获取互动时长图表和百分位数。请确保各广告的 metric 和 period_type 一致。支持的指标包括 retain_ctr、retain_cvr、click_cnt、convert_cnt 和 play_retain_cnt。
4. 仅将 /tiktok/top-ads/recommend 或 /tiktok/top-ads/spotlight 用于补充发现。未经标注，不要将这些精选/相关素材混入按筛选条件匹配的样本。

对于专门的竞品广告比较或创意简报，范围更聚焦的 tiktok-ad-research 技能提供相同的 Top Ads 端点，并生成更有针对性的交付成果。

解读与限制

• 仅限公开数据：不包括登录信息、私密内容、隐藏联系人或受众人口统计数据。认证徽章并不能证明受众的真实性。
• 匿名访问 Creative Center 的能力有限：话题标签最多返回 3 条记录；视频只返回第一页（4 个视频），无论上游显示的总数是多少。应将这些总数视为上游报告的背景信息，而非可访问数据的覆盖范围。
• Creative Center 中的视频可用性因国家/地区而异。美国、日本、印度尼西亚、越南和泰国均能稳定返回非空样本；在其他市场中，合法的空响应可能意味着 TikTok 没有该市场的匿名数据。不要无限重试，也不要在缺乏其他证据时将其称为服务中断。
• Creative Center 的 engagement_rate 和 six_seconds_vtr 是比率，不是百分比。不得将限定时间段的数据字段与全生命周期字段视为涵盖相同时间窗口并进行比较。
• Top Ads 百分位数不是原始 CTR/CVR、花费、转化次数或 ROI。应准确保留返回的指标标签、周期和单位。
• 签名图片/视频 URL 可能会过期。应保留稳定的 TikTok 来源链接和 ID，以便重复研究。除非环境确实提供了媒体，否则不要声称已观看或听过创意内容。
• 缺失字段表示未知，而非零。实时刷新失败时，可以提供明确标注的过时数据/数据集观察，但不得将其悄然当作当前事实。

输出与可靠性

返回所请求的答案，并附上来源 URL 或稳定 ID、检索时间、筛选条件和样本量。进行比较时，所有行必须使用相同的定义和时间窗口。将观察到的事实与解读分开，并将假设标注为假设。

使用有界请求。遇到 429 时，应退避；在有必要时，对暂时性的 5xx 重试一次。遇到 401/403 时应停止，并报告访问限制。若部分详情或评论获取失败，应保留并明确标注不完整结果；将空响应或嵌套响应视为有效数据前，应检查应用层的 code。