TikTok Video Search 用于按条件检索公开 TikTok 视频，属于 Frevana 的异步视频接口技能，通过命令行脚本调用。
用途与检索方式 每次任务需严格选择一种来源类型：--query/--keyword 用于关键词视频搜索，--hashtag 用于话题视频搜索（不带 #），--username 用于指定创作者的视频（不带 @，不能填个人主页 URL）。所选标志可重复 1 至 5 个值。关键词模式会发送 search_queries 并附带 search_section=/video；话题标签模式发送 hashtags；用户名模式发送 profiles，并按最新优先排序。精确帖子采集、Top/用户搜索和广告属于其他独立工作流，不在本技能范围内。
主要能力 支持按日期和热度排序筛选（仅关键词模式），可控制每页结果数（默认 20，最大 100），可指定输出文件。服务器默认启用视频下载并产生额外费用，仅需元数据时可通过 --should-download-videos false 关闭下载。返回结果中常用字段包括 id、text、webVideoUrl、authorMeta、playCount、diggCount 和 video_url 等。
使用方式 需准备 Bash 与 Python 3.9+，无需浏览器扩展、守护进程、Apify SDK 或服务商令牌。认证通过 FREVANA_TOKEN 或 FREVANA_API_KEY 环境变量，或一次性 --token/--api-key 参数完成；显式凭据优先于环境凭据，令牌优先。run 提交并等待，create 立即返回；应保留输出的 client_task_id 与 task_id。按 next_poll_after_ms 轮询，仅在 status=READY 且 result_available=true 时获取结果；遇到 FAILED、REVIEW_REQUIRED、RESULT_EXPIRED 或零轮询间隔且无结果时停止。超时可用 wait --task-id 恢复，不要自动重新提交付费任务；创建状态不确定时，只能用相同 client_task_id 和相同选项重试，变更输入会返回 HTTP 409。items 命令返回单页结果，需按 count 推进 offset 直到 total；完整结果使用 result 命令。
常用命令示例： bash {baseDir}/scripts/tiktok_video_search.sh run --query 'artificial intelligence' --results-per-page 20 bash {baseDir}/scripts/tiktok_video_search.sh run --hashtag 'skincare' --hashtag 'beauty' bash {baseDir}/scripts/tiktok_video_search.sh run --username 'tiktok' bash {baseDir}/scripts/tiktok_video_search.sh run --query 'skincare' --query 'beauty routine' --video-search-sorting MOST_LIKED --video-search-date-filter PAST_WEEK --output ./out/videos.json bash {baseDir}/scripts/tiktok_video_search.sh run --query 'coffee' --should-download-videos false bash {baseDir}/scripts/tiktok_video_search.sh create --query 'robotics' --client-task-id caller-stable-id --max-total-charge-usd 2.50 bash {baseDir}/scripts/tiktok_video_search.sh status --task-id TASK_UUID bash {baseDir}/scripts/tiktok_video_search.sh wait --task-id TASK_UUID --timeout 1800 bash {baseDir}/scripts/tiktok_video_search.sh result --task-id TASK_UUID --output ./out/videos.json bash {baseDir}/scripts/tiktok_video_search.sh items --task-id TASK_UUID --offset 0 --limit 100
run/wait 默认将完整 JSON 数组保存到 ./out/，也可用 --output 指定；进度输出到 stderr。--timeout 为等待预算（默认 21600 秒，0 表示不限），HTTP 请求另有 600 秒上限。基础 URL 默认为 https://ai-factory.frevana.com，可由 FREVANA_API_BASE_URL 或 --api-base-url 覆盖。
适用场景 适合按关键词、话题或创作者查找公开视频并汇总元数据，或按需下载视频文件用于后续分析。
限制与注意事项 下载的 video_url 为 Apify 签名直链，video_url_expires_at 为 null，服务器不设固定 24 小时过期，但可用性取决于存储文件，不能承诺永久保存。访问媒体或辅助数据集 URL 时不要附带 Frevana 凭据。评论保存在由 commentsDatasetUrl/commentsDatasetURL 关联的独立数据集中，不合并到主结果。任务就绪不代表每个条目都有可下载视频。可离线运行测试：PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s {baseDir}/tests -v，测试使用本地模拟服务器，不调用付费服务商。具体参数与费用语义见 references/api.md。