用途：使用随附脚本搜索公开 TikTok 广告，或按广告 ID 获取特定广告详情。仅调用 Frevana 的 /apify/tiktok-ads/tasks 的 create、status、result 三个 API。需 Bash 与 Python 3.9+ 标准库，无需 TikTok 访问令牌或 SDK。
主要能力：支持按关键词（--query）、广告主（--advertiser-name）、受支持国家或 1 至 100 个唯一 --ad-id 值检索。广告 ID 不可与任何搜索筛选条件组合。默认一页（最多 12 条广告）、国家 all、时区 UTC、排序 last_shown_date,desc、quick_search=false。支持的国家筛选覆盖所列欧洲市场，美国不支持。
使用方式：优先用 run 完成创建、等待与取回结果；也可用 create、status、wait、result 分阶段执行。示例：bash {baseDir}/scripts/tiktok_ads_search.sh run --query 'pikoya' --country ES；bash {baseDir}/scripts/tiktok_ads_search.sh run --ad-id 1878055429367345；bash {baseDir}/scripts/tiktok_ads_search.sh status --task-id TASK_UUID。create --wait 等价于 run。--help 列出全部参数。
认证与输出：使用 FREVANA_TOKEN（JWT）或 FREVANA_API_KEY，一次性 --token 或 --api-key 可覆盖环境凭据，两者同时存在时 JWT 优先。默认基址 https://ai-factory.frevana.com，可用 FREVANA_API_BASE_URL 或 --api-base-url 覆盖。不跟随重定向。create 与 status 原样打印任务 JSON，result 打印原样 JSON 数组；run、create --wait、wait 默认将最终数组保存到 ./out/。进度与 ID 输出到 stderr。
限制：创建视为计费，服务器检查预估额度并异步结算实际用量；需记录 client_task_id 与 task_id。创建响应不确定时，仅用相同选项与相同 client ID 重试，不可自动创建替代任务；相同 ID 配不同参数返回 HTTP 409。需等待 status=READY 且 result_available=true，遵循 next_poll_after_ms，为零则停止自动轮询；遇 FAILED、REVIEW_REQUIRED 或 RESULT_EXPIRED 停止。quick_search=true 及不可用广告可能缺少详情字段，不得编造。媒体链接不被本 API 归档，可能过期。Windows 需在 Git Bash 或 WSL 中运行并确保 Python 3 可用。