web-crawler

首选入口：调用 exports.py（不要自行编写请求）

现成的辅助函数位于 skills/web-crawler/exports.py。优先使用它们，而不是 自行编写 proxied_get/proxied_post 调用——它们已经注入了代理凭据，因此无需查找 API 密钥（不要读取 $SCRAPECREATORS_API_KEY / $FIRECRAWL_API_KEY，不要检查 .env，也不要询问 用户）。

import sys; sys.path.insert(0, "/data/workspace/skills/web-crawler")
from exports import scrape_markdown, youtube_transcript, sc_get
scrape_markdown("https://example.com/article")          # Firecrawl fallback
youtube_transcript("https://youtube.com/watch?v=ID")     # ScrapeCreators
youtube_video("https://youtube.com/watch?v=ID")          # metadata: title/description/uploader (+ transcript)
sc_get("/v1/tiktok/profile", handle="charlidamelio")     # any SC endpoint

from exports import archive_fallback                      # paywall / Firecrawl-403
archive_fallback("https://www.nytimes.com/.../article.html")  # archive snapshot

转录文本路由——任何媒体链接都使用同一个入口

from core.skill_tools import web_crawler
r = web_crawler.get_transcript(url, caller_id="chat:<thread>")
# {found, kind, source, text, url, title, tried, note}

设计原则：字幕 / 字幕轨道 / 已发布的转录文本属于元数据； 媒体文件属于负载。 先尝试所有元数据提供方；只有在用户明确同意后才访问 媒体文件。claude-video、spoken.md 和 yt-dlp 的 --skip-download 工作流也遵循同一原则。这里的内容并非特定于任何网站：

提供方（按成本排序）	说明	身份 / 有效性检查
media_info(url)	yt-dlp extract_info(download=False)——支持 1800 多个网站，可返回标题、时长、上传日期、频道和字幕轨道 URL。不消耗媒体字节。	获取的轨道必须返回 2xx，且包含有效正文
RSS <podcast:transcript>	Podcasting 2.0 标准，适用于任何播客	按时长 ±5 %、日期 ±3 d 匹配订阅源条目；转录文本 URL 必须返回 2xx、长度 > 500 个字符，且不是错误页面
节目自己的 YouTube 上传内容	频道 = 节目在其 RSS 中声明的 YouTube URL（否则使用搜索结果中频道名称与去掉停用词后的节目名称完全相同的结果）	候选项 = 时长 ±5 % 且日期 ±3 d；身份 = 标题相似度 ≥ 0.6 或节目说明重合（≥ 6 个共同的独特词元，Jaccard ≥ 0.15）。身份检查未通过的候选项会以 candidate 返回，且 found=False——绝不会作为该集的内容交付
scrape_markdown(url)	其他任何页面（发布方、Snipd、博客）——由浏览器渲染，可绕过 WAF 的 403	> 1000 个字符

found=False ⇒ 报告 kind、title、tried、note（如果有， 也包括 candidate），并在进行任何下载前询问用户。YouTube 会根据 URL 识别： 即使 yt-dlp 元数据获取失败，字幕 API 仍会运行；页面抓取结果绝不会被报告为媒体 URL 的转录文本。yt-dlp --skip-download / -J / --list-subs 是 元数据调用，可通过 bash 门禁；yt-dlp <url>、curl … .mp3、ffmpeg、 whisper 则需要确认。

只有标题、没有链接 → web_search("<show> <title> transcript")，然后 get_transcript(<page url>)。

事件记录 2026-09-17：转录文本托管站点两次返回 403，导致一个 Agent 下载了 49 MB mp3，使用 ffmpeg、调用 whisper 4 次，最后只得到不完整的摘要。使用同一链接调用 get_transcript：RSS 没有转录文本 → RSS 声明了 youtube.com/@a16z → 频道列表 → 找到一条时长相差 1.2 %、日期相同的上传内容 → 字幕， 55k 个字符，约 30 s，零音频。

快速触发规则（请先阅读）

出现以下任一情况时，请立即使用此技能：

• web_fetch 返回 HTTP 401/403/429/5xx
• 响应是反机器人验证页面（例如 Cloudflare 的“Attention Required”、“Just a moment”或验证 / CAPTCHA 页面）
• 页面大量依赖 JS，首次抓取未能获取所需的详细字段（例如发布时间、作者、列表代码、更新时间、价格明细）
• 搜索结果不包含所需字段，且必须从目标页面本身提取该值

回退规则：

• 如果普通抓取受阻或不完整，请先尝试此技能中的 Firecrawl 回退方案，再向用户索要截图 / 手动提供的文本。

错误特征 -> 操作

特征	操作
web_fetch HTTP 401/403/429/5xx	使用 formats:["markdown","links"] + onlyMainContent:true 调用一次 Firecrawl POST /v2/scrape
正文中出现 Cloudflare/验证页面文本	执行上述相同的 Firecrawl 调用
Markdown 仍缺少关键字段	使用 formats:["rawHtml"] 重试一次
Firecrawl 对社交媒体 URL 返回 403 / 空结果	查看下方的意图路由表，确认此域名是否有 ScrapeCreators 平台专用端点（例如 sc_get('/v1/instagram/post', url=...)、sc_get('/v2/tiktok/video', url=...)）。如果有，则使用该端点——它们具有专用提取功能，可绕过反机器人机制。如果没有专用端点，则转用 archive_fallback，或询问用户。
Firecrawl 本身返回 403 / 空结果（硬付费墙：NYT、WSJ、Economist、FT、Bloomberg）	调用 archive_fallback(url)——从网页存档快照中恢复全文
需要获取中国应用的结构化数据（抖音/小红书/微博/B站/京东/淘宝/1688/闲鱼/得物等）	调用 apify_run()——Apify Store 中有专为这些平台打造的 actor，可覆盖 Firecrawl/ScrapeCreators 不支持的内容
Instagram 快拍 URL（instagram.com/stories/<user>/<id>）	ScrapeCreators 没有快拍端点，Firecrawl 会遇到登录墙——直接调用 apify_run("data-slayer~instagram-stories-scraper", ...)。详见下文“Instagram 快拍”

付费墙 / Firecrawl 拦截时的回退链（使用 archive_fallback）

如果 Firecrawl 也无法获取页面（返回 403，或返回的 Markdown 为空），说明该网站设有硬付费墙或严格的 WAF。不要继续重试 Firecrawl。请改从网页存档快照中恢复文章：

from exports import archive_fallback
res = archive_fallback("https://www.nytimes.com/.../article.html")
res["markdown"]      # full text, or "" if no snapshot exists anywhere
res["source"]        # "archive.today" | "wayback" | None
res["snapshot_url"]  # the snapshot that was scraped

工作原理（以及为何按此顺序操作）：

• 首先尝试 archive.today（archive.ph / archive.is 镜像）。由用户触发的真实浏览器抓取；历史上会保留付费墙后的全文。 最适合 NYT/WSJ/Economist。我们通过 Firecrawl 抓取其 /newest/ 快照（archive.today 使用自己的 Cloudflare，因此必须通过 Firecrawl 抓取，切勿直接使用 web_fetch）。
• 其次尝试 Wayback Machine（archive.org）。自动爬虫会遵守 robots.txt 和付费墙，因此通常不会提供硬付费墙的全文——但它是未设付费墙的普通 403/Cloudflare 页面的一种不错的回退方案。

限制：存档只能返回他人此前已保存的文本。如果 res["markdown"] == ""，则不存在快照——停止操作，告知用户，并尝试该媒体的官方 API/RSS 或其他来源。不要编造文章内容。

中国应用结构化数据（使用 apify_run）

当你需要获取中国应用的结构化数据——抖音视频搜索、 小红书笔记、微博帖子、Bilibili 视频、京东/淘宝商品价格、 1688 批发商品、闲鱼二手商品、得物运动鞋等——Firecrawl 和 ScrapeCreators 无法覆盖这些平台。请改用 Apify Store 作为回退方案。Apify 是一个无服务器抓取服务市场，拥有数百个由社区维护的 actor，可通过真实浏览器和代理池访问中国平台。

**身份验证：**无需用户提供密钥。sc-proxy 会自动注入平台 Apify 令牌。Authorization: Bearer 标头可以是任意虚假值——代理会将其替换为真实令牌。不要从环境变量中读取 $APIFY_TOKEN，不要检查 .env，也不要向用户索要 Apify 密钥。

何时使用 Apify（与 Firecrawl/ScrapeCreators 比较）：

• ✅ 中国应用：抖音、小红书、微博、B站、京东、淘宝、1688、闲鱼、携程、知乎、豆瓣、雪球、优酷（得物/快手/爱奇艺：没有可获取价格的 actor——请搜索 Store）
• ✅ 东南亚电商：Shopee、Lazada、Temu
• ✅ Instagram 快拍（ScrapeCreators 没有快拍端点）——详见下文“Instagram 快拍”
• ❌ 其他西方社交媒体（TikTok/Instagram 帖子和 Reels/YouTube/X/Reddit）→ 优先使用 ScrapeCreators（成本更低）
• ❌ 通用网页抓取 → 优先使用 Firecrawl（成本更低）
• ❌ 硬付费墙文章 → 使用 archive_fallback（Apify 在此无济于事） **如何选择 Actor：**请先查阅下表——这些 Actor 在 sc-proxy 中按次计费，并已于 2026-10-08 在线验证（括号内为 30 天内的成功运行次数）。对于未列出的平台，请通过代理搜索 Store（proxied_get("https://api.apify.com/v2/store?search=<platform>&limit=10")），优先选择 30 天运行次数较高的 Actor，并按默认价格 $0.007/条结果估算。

平台	Actor ID	输入键
抖音搜索	zen-studio~douyin-search-scraper	{"keywords": [...], "maxResultsPerQuery": N}
抖音创作者主页	zen-studio~douyin-profile-scraper (22k)	（参见 Actor 输入架构）
抖音视频/音频下载	apple_yang~douyin-video-audio-downloader (5k)	（参见 Actor 输入架构）
抖音字幕	apple_yang~douyin-transcripts-scraper (2.6k)	（参见 Actor 输入架构）
小红书搜索	zen-studio~rednote-search-scraper	{"keywords": [...], "maxResults": N}
小红书笔记详情	sian.agency~xiaohongshu-rednote-scraper	{"operation": "noteDetail", "noteId": "...", "xsecToken": "..."}
小红书数据 API	socialdatax~socialdatax-xhs-data-api (64k)	（参见 Actor 输入架构）
微博热搜	gentle_cloud~weibo-hot-search-scraper	{"mode": "hot_band", "includeScores": true}
微博帖子/评论	zhorex~weibo-scraper (5k) 或 sian.agency~weibo-scraper (17k)	（参见 Actor 输入架构）
B 站视频/评论/弹幕	zhorex~bilibili-scraper (17k)	（参见 Actor 输入架构）
知乎问答/文章	sian.agency~zhihu-scraper	（参见 Actor 输入架构）
豆瓣评论/条目	zhorex~douban-scraper	（参见 Actor 输入架构）
雪球股票讨论	zhorex~xueqiu-scraper（低流量）	（参见 Actor 输入架构）
优酷视频	sian.agency~youku-video-scraper（低流量）	（参见 Actor 输入架构）
京东搜索	zen-studio~jd-com-search-scraper	{"keyword": "...", "maxProducts": N}
京东商品	sian.agency~jd-com-product-scraper	{"operation": "productSearch", "keyword": "...", "maxPages": 1}
淘宝搜索/详情	zen-studio~taobao-search-scraper / zen-studio~taobao-detail-scraper (18k)	（参见 Actor 输入架构）
淘宝/天猫商品	sian.agency~taobao-tmall-product-scraper	{"operation": "keywordSearch", "keyword": "...", "maxPages": 1}
1688 批发	zen-studio~1688-wholesale-scraper 或 devcake~1688-com-products-scraper	（参见 Actor 输入架构）
闲鱼搜索	zen-studio~goofish-xianyu-search-scraper	（参见 Actor 输入架构）
Shopee / Lazada / Temu	gio21~shopee-scraper / fatihtahta~lazada-scraper / amit123~temu-products-scraper	（参见 Actor 输入架构）
携程 / Trip.com 评论	knagymate~trip-com-reviews-scraper (89k)	（参见 Actor 输入架构）
Instagram 限时动态	data-slayer~instagram-stories-scraper	{"usernames": [...]} — 参见“Instagram 限时动态”
TikTok	clockworks~tiktok-scraper	{"hashtags": [...]} 或 {"profiles": [...]}

没有任何按次计费 Actor 覆盖的平台：快手、爱奇艺——请搜索 Store，并告知用户该 Actor 尚未验证。

小红书两步工作流（搜索 → 笔记详情）： 搜索爬虫（zen-studio~rednote-search-scraper）仅返回截断后的 desc（约 60 个字符）。如需获取完整正文，请使用 sian.agency~xiaohongshu-rednote-scraper 以 noteDetail 模式发起第二次调用，并传入搜索结果行中的 id 和 xsec_token。这是获取完整笔记文本（包括价格/住宿/行程详情）的唯一可靠方式。

用法：

import sys
sys.path.insert(0, "/data/workspace/skills/web-crawler")
from exports import apify_run

# Sync run (small batches, ≤100 results): blocks until done, returns result list
results = apify_run("zen-studio~douyin-search-scraper",
                     {"keywords": ["MacBook"], "maxResultsPerQuery": 5})
for r in results:
    print(r.get("text", "")[:80])

# To discover the right input fields for an unfamiliar actor, fetch its
# input-schema page via Firecrawl first:
from exports import scrape_markdown
schema_md = scrape_markdown("https://apify.com/<user>/<actor>/input-schema")

计费与成本控制——每次调用 Apify 前请阅读：

Apify 采用按事件付费计费方式：(actor-start + result_count × per_result + add-ons) × 2 积分。 主要成本因素是结果数量 × 单条结果价格，且每个 Actor 的价格各不相同（$0.003–$0.007/条结果）。未知 Actor 默认按最高档（$0.007）计费。完整价格表和估算示例：reference/apify-pricing.md。 调用前必须估算费用：

1. 查找该 Actor 的单条结果价格（见 reference/apify-pricing.md 中的表格；未列出的默认为 $0.007）。
2. 根据输入参数估算结果数量（maxResults、maxProducts 等）。如果未设置限制，则按 100+ 估算。
3. 计算：result_count × per_result × 2 = 预估积分。
4. 如果预估超过 5 积分，继续操作前先告知用户费用。

硬性支出上限——代理默认强制执行 + 每次调用可覆盖：

代理会在每次未指定 maxTotalChargeUsd 的 Actor 运行中自动注入 maxTotalChargeUsd=$2.5（约 5 积分）。达到预算后，Apify 会终止运行，并返回截至当时已收集的结果——不会超额收费，也不会产生失控费用。

apify_run() 也会传入 max_charge_usd（默认值同为 $2.5），其优先级高于代理默认值。因此：

• **默认（不添加额外参数）：**每次调用的上限约为 5 积分。适用于常规搜索、个人资料查询和小批量抓取。
• **需要更多数据？**明确提高上限：max_charge_usd=10（约 20 积分）。仅在用户明确要求获取大型数据集且你已告知预估费用后使用。
• **首次测试：**降低上限：max_charge_usd=0.5（约 1 积分），并将结果限制为 5–10 条。在扩大规模前，先验证输出质量。
• 完全取消上限：max_charge_usd=None。除非用户在获知潜在费用后明确要求不限额运行，否则绝不要这样做。

先进行小批量测试： 首次使用某个 Actor 时，设置 max_charge_usd=0.5（约 1 积分），并将结果限制为 5–10 条。在扩大规模前，先验证输出质量。

错误处理：

• 400 run-failed → 输入错误（字段名称有误）。获取该 Actor 的输入架构页面并修正。
• 401 → 代理配置错误（不应发生）。向用户报告。
• 结果为空 [] → Actor 已运行，但未找到内容。尝试使用其他关键词或其他 Actor。
• 超时 → 增大 timeout 参数（默认值为 180s）。某些 Actor 运行较慢。

Instagram——不同内容对应的路由

内容	路由
个人资料、简介、近期帖子	sc_get('/v1/instagram/profile', handle=...)
所有帖子 / 所有 Reels	/v2/instagram/user/posts / /v1/instagram/user/reels（分页）
单条帖子或 Reel	sc_get('/v1/instagram/post', url=...)
帖子或 Reel 中说了什么	/v2/instagram/media/transcript（≤2 min）
评论	/v2/instagram/post/comments
精选集	/v1/instagram/user/highlights → /v1/instagram/user/highlight/detail
按关键词搜索 Reels	/v2/instagram/reels/search
直播快拍（<24h）	Apify data-slayer~instagram-stories-scraper——见下文
私人账号、私信、关注者列表	不可用——请如实告知

/v1/instagram/song/reels 已在上游弃用（Instagram 已移除音频页面）；请勿调用。

Instagram 快拍（使用 apify_run）

快拍 URL（instagram.com/stories/<user>/<id>）无法通过 ScrapeCreators（没有快拍端点；只有精选快拍）或 Firecrawl（登录墙）访问。 不要重试这些 URL——通过代理直接调用 Apify（无需用户密钥）：

from exports import apify_run
items = apify_run("data-slayer~instagram-stories-scraper",
                  {"usernames": ["rafaelkborges"]}, max_charge_usd=0.5)
story = next(i for i in items if str(i.get("id")) == "4002796791460342130")
video_url = story["video_versions"][0]["url"]   # image-only stories: image_versions2

• 适用于公开账号的活跃快拍（< 24 小时）。没有活跃快拍的账号会返回一行 {"status": "no_active_stories"}。任何人都无法获取私密或已过期的快拍——请说明这一点。
• 根据 id（URL 中的数字）匹配快拍。pk 为 null。
• CDN 链接很快就会过期——请立即下载 mp4。
• 如需了解视频中说了什么，请将 mp4 传给视频分析技能（原生模式可在一次调用中处理约 12 MB / 60 秒的快拍；包含转录文本和屏幕文字）。
• 如果 Apify 没有返回内容：检查 /v1/instagram/user/highlights；否则，如果用户的 Chrome 已连接（control-browser）并登录了 Instagram，就在那里打开快拍；否则请用户提供屏幕录制（不是截图——大多数快拍都是带语音的视频）。
• 已于 2026-10-08 验证：约 8–13 秒处理 5 个账号，Apify 实际费用约为每条结果 $0.0025。

成本控制： Apify Actor 的费用高于 Firecrawl/ScrapeCreators。仅在较便宜的选项无法获取数据时才使用 Apify（中国应用、Instagram 快拍、结构化电商字段）。对于单个网页，务必优先尝试 Firecrawl。

各服务的用途

ScrapeCreators — 社交媒体数据提取（27+ 个平台）

用于涉及社交媒体个人资料、帖子、视频、评论、转录文本、搜索、广告、热门内容或互动指标的任何请求。支持 TikTok、Instagram、YouTube、LinkedIn、Facebook、Twitter/X、Reddit、Threads、Bluesky、Pinterest、Snapchat、Twitch、Kick、Truth Social、TikTok Shop、Google 搜索，以及个人简介链接服务（Linktree、Komi、Pillar、Linkbio、Linkme、Amazon Shop）。

基础 URL： https://api.scrapecreators.com 身份验证： 无需用户提供密钥。sc-proxy 会自动注入平台凭证——只需发送请求即可。x-api-key 标头可以是任意值，也可以完全省略。如果 $SCRAPECREATORS_API_KEY 看起来未设置，不要放弃操作，也不要向用户索要密钥；有意不要求设置此环境变量。 方法： 所有端点均使用带查询参数的 GET 请求。响应为 JSON。

Firecrawl — 网页抓取备用方案

仅当常规抓取失败时，才将其用作单个网页的备用抓取工具。使用 POST /v2/scrape，提供单个 url，并选择 markdown、html、rawHtml、links、summary 等专用格式，或受限的 json/question/highlights 提取。

身份验证： 无需用户提供密钥。通过 core.http_client.proxied_post 调用时，sc-proxy 会自动注入 Firecrawl 凭证——只需发送请求即可。不要从环境变量读取 $FIRECRAWL_API_KEY，不要检查 .env 中是否有该密钥；如果它看起来未设置，不要向用户索要 Firecrawl 密钥。有意不要求设置此环境变量。此处采用与 ScrapeCreators 相同的代理注入模式。

不要使用 Firecrawl 的 crawl/map/search/agent/browser 端点。除非之后扩展代理策略，否则不要请求截图、音频、品牌素材、图片或浏览器操作。

---

ScrapeCreators — 意图路由

将用户意图映射到相应端点。端点路径采用 /v1/platform/action 模式。

重要： 从下表选定端点后，在进行实际 API 调用前，请访问 https://docs.scrapecreators.com/{path}/openapi.json 获取完整的参数详情、类型和示例响应。例如：https://docs.scrapecreators.com/v1/tiktok/profile/openapi.json

个人资料 / 用户信息

平台	端点	主要参数	示例
TikTok	/v1/tiktok/profile	handle	stoolpresidente
Instagram	/v1/instagram/profile	handle	jane
YouTube	/v1/youtube/channel	handle、channelId 或 url	ThePatMcAfeeShow
LinkedIn（个人）	/v1/linkedin/profile	url	https://www.linkedin.com/in/parrsam/
LinkedIn（公司）	/v1/linkedin/company	url	https://linkedin.com/company/shopify
Facebook	/v1/facebook/profile	url	https://www.facebook.com/mantraindianfolsom
Twitter/X	/v1/twitter/profile	handle	elonmusk
Reddit	/v1/reddit/subreddit/details	subreddit 或 url	AskReddit
Threads	/v1/threads/profile	handle	zuck
Bluesky	/v1/bluesky/profile	handle	jay.bsky.team
Pinterest	/v1/pinterest/user/boards	handle	pinterest
Truth Social	/v1/truthsocial/profile	handle	realDonaldTrump
Twitch	/v1/twitch/profile	handle	ninja
Snapchat	/v1/snapchat/profile	handle	djkhaled

帖子 / 内容动态

平台	端点	主要参数	示例
TikTok 视频	/v3/tiktok/profile/videos	handle	stoolpresidente
Instagram 帖子	/v2/instagram/user/posts	handle	jane
Instagram Reels	/v1/instagram/user/reels	handle 或 user_id	jane 或 2700692569
Instagram 快拍精选	/v1/instagram/user/highlights	handle 或 user_id	jane 或 2700692569
YouTube 视频	/v1/youtube/channel/videos	handle 或 channelId	ThePatMcAfeeShow
YouTube Shorts	/v1/youtube/channel/shorts	handle 或 channelId	starterstory
YouTube 播放列表	/v1/youtube/playlist	playlist_id	PLP32wGpgzmIlInfgKVFfCwVsxgGqZNIiS
LinkedIn 帖子	/v1/linkedin/company/posts	url	https://linkedin.com/company/shopify
Facebook 帖子	/v1/facebook/profile/posts	url 或 pageId	https://www.facebook.com/pacemorby
Facebook Reels	/v1/facebook/profile/reels	url	https://www.facebook.com/Spurs
Facebook 照片	/v1/facebook/profile/photos	url	https://www.facebook.com/Spurs
Facebook 群组帖子	/v1/facebook/group/posts	url 或 group_id	742354120555345
Twitter 推文	/v1/twitter/user/tweets	handle	elonmusk
Reddit 帖子	/v1/reddit/subreddit	subreddit	AskReddit
Threads 帖子	/v1/threads/user/posts	handle	zuck
Bluesky 帖子	/v1/bluesky/user/posts	handle 或 user_id	jay.bsky.team
Truth Social 帖子	/v1/truthsocial/user/posts	handle 或 user_id	realDonaldTrump
Pinterest 画板	/v1/pinterest/board	url	https://www.pinterest.com/...

单条帖子 / 视频详情

平台	端点	主要参数	示例
TikTok	/v2/tiktok/video	url	https://www.tiktok.com/@randomspamvideos25/video/7251387037834595630
Instagram	/v1/instagram/post	url	https://www.instagram.com/reel/DOq6eV6iIgD
Instagram 精选集	/v1/instagram/user/highlight/detail	id	18067016518767507
YouTube	/v1/youtube/video	url	https://www.youtube.com/watch?v=Y2Ah_DFr8cw
YouTube 社区帖子	/v1/youtube/community-post	url	https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8
LinkedIn	/v1/linkedin/post	url	https://www.linkedin.com/pulse/being-father-has-made-me-better-leader...
Facebook	/v1/facebook/post	url	https://www.facebook.com/reel/1535656380759655
Twitter/X	/v1/twitter/tweet	url	https://twitter.com/elonmusk/status/...
Twitter/X 社区	/v1/twitter/community	url	https://twitter.com/i/communities/...
Twitter/X 社区推文	/v1/twitter/community/tweets	url	https://twitter.com/i/communities/...
Reddit	/v1/reddit/post/comments	url	https://www.reddit.com/r/AskReddit/comments/...
Threads	/v1/threads/post	url	https://www.threads.net/@zuck/post/...
Bluesky	/v1/bluesky/post	url	https://bsky.app/profile/.../post/...
Truth Social	/v1/truthsocial/post	url	https://truthsocial.com/@realDonaldTrump/posts/...
Pinterest	/v1/pinterest/pin	url	https://www.pinterest.com/pin/...
Twitch 短片	/v1/twitch/clip	url	https://clips.twitch.tv/...
Kick 短片	/v1/kick/clip	url	https://kick.com/...

评论

平台	端点	主要参数	示例
TikTok	/v1/tiktok/video/comments	url	https://www.tiktok.com/@stoolpresidente/video/7499229683859426602
Instagram	/v2/instagram/post/comments	url	https://www.instagram.com/reel/DOq6eV6iIgD
YouTube	/v1/youtube/video/comments	url	https://www.youtube.com/watch?v=dQw4w9WgXcQ
Facebook	/v1/facebook/post/comments	url or feedback_id	https://www.facebook.com/reel/753347914167361
Reddit	/v1/reddit/post/comments	url	https://www.reddit.com/r/AskReddit/comments/...

转录文本

⚠️ 先获取元数据。 转录文本端点仅返回语音文本——不含说话者、标题或上传者。总结视频时，请先调用视频元数据端点（youtube_video / /v1/tiktok/video / …）获取标题、描述和上传者，然后再获取转录文本。切勿仅根据转录内容将说话者或公众人物与内容联系起来——如果元数据不可用，请注明“说话者身份不明”，并在总结中不要提及任何人的姓名。

平台	端点	示例	备注
TikTok	/v1/tiktok/video/transcript	url=https://www.tiktok.com/...&lang=en	也可通过 /v2/tiktok/video 并设置 get_transcript=true 获取
Instagram	/v2/instagram/media/transcript	url=https://www.instagram.com/reel/...	AI 驱动，耗时 10-30s，仅支持 2min 以内的内容
YouTube	/v1/youtube/video/transcript	url=https://www.youtube.com/watch?v=bjVIDXPP7Uk	也包含在 /v1/youtube/video 响应中
Facebook	/v1/facebook/post/transcript	url=https://www.facebook.com/reel/...	仅支持 2min 以内的内容
Twitter/X	/v1/twitter/tweet/transcript	url=https://twitter.com/...	AI 驱动，速度较慢

搜索

平台	端点	主要参数	示例
TikTok 用户	/v1/tiktok/search/users	query	funny
TikTok 视频（关键词）	/v1/tiktok/search/keyword	query	funny
TikTok 视频（话题标签）	/v1/tiktok/search/hashtag	hashtag	fyp
TikTok 热门内容（照片+视频）	/v1/tiktok/search/top	query	funny
Instagram Reels	/v2/instagram/reels/search	query	dogs
YouTube	/v1/youtube/search	query	funny
YouTube 话题标签	/v1/youtube/search/hashtag	hashtag	funny
Reddit（全部）	/v1/reddit/search	query	best programming languages
Reddit（版块内）	/v1/reddit/subreddit/search	subreddit + query	AskReddit + funny
Threads 帖子	/v1/threads/search	query	AI
Threads 用户	/v1/threads/search/users	query	zuck
Pinterest	/v1/pinterest/search	query	home decor
Google	/v1/google/search	query	best restaurants in NYC

广告资料库

平台	端点	主要参数	示例
Facebook 广告搜索	/v1/facebook/adLibrary/search/ads	query	running
Facebook 公司广告	/v1/facebook/adLibrary/company/ads	pageId or companyName	Lululemon
Facebook 广告详情	/v1/facebook/adLibrary/ad	id or url	702369045530963
Facebook 查找公司	/v1/facebook/adLibrary/search/companies	query	Nike
Google 公司广告	/v1/google/company/ads	domain or advertiser_id	nike.com
Google 广告详情	/v1/google/ad	url	https://adstransparency.google.com/...
Google 查找广告主	/v1/google/adLibrary/advertisers/search	query	Nike
LinkedIn 广告搜索	/v1/linkedin/ads/search	company or keyword	Shopify
LinkedIn 广告详情	/v1/linkedin/ad	url	https://www.linkedin.com/ad/...
Reddit 广告搜索	/v1/reddit/ads/search	query	gaming
Reddit 广告详情	/v1/reddit/ad	id	t3_abc123

趋势 / 热门

内容	端点	参数	示例
趋势动态	/v1/tiktok/get-trending-feed	region (required)	US
热门视频	/v1/tiktok/videos/popular
热门创作者	/v1/tiktok/creators/popular
热门话题标签	/v1/tiktok/hashtags/popular
热门歌曲	/v1/tiktok/songs/popular
歌曲详情	/v1/tiktok/song	clipId	7439295283975702544
使用该歌曲的视频	/v1/tiktok/song/videos	clipId	7439295283975702544
趋势 Shorts（YT）	/v1/youtube/shorts/trending

粉丝 / 关注 / 直播（仅 TikTok）

类型	端点	示例
关注中	/v1/tiktok/user/following	handle=stoolpresidente
粉丝	/v1/tiktok/user/followers	handle=stoolpresidente
受众人口统计	/v1/tiktok/user/audience (26 credits!)	handle=shakira
直播	/v1/tiktok/user/live	handle=thejustalex

TikTok Shop

类型	端点	主要参数	示例
搜索商品	/v1/tiktok/shop/search	query	shoes
店铺商品	/v1/tiktok/shop/products	url	https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079
商品详情	/v1/tiktok/product	url	https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies.../1729587769570529799
商品评价	/v1/tiktok/shop/product/reviews	url or product_id	1731578642912612516
用户展示区	/v1/tiktok/user/showcase	handle	mrtiktokreviews

简介链接 / 其他

服务	端点	参数	示例
Linktree	/v1/linktree	url	https://linktr.ee/...
Komi	/v1/komi	url	https://komi.io/...
Pillar	/v1/pillar	url	https://pillar.io/...
Linkbio	/v1/linkbio	url	https://linkbio.co/...
Linkme	/v1/linkme	url	https://linkme.bio/...
Amazon Shop	/v1/amazon/shop	url	https://www.amazon.com/shop/...
Instagram 基本资料	/v1/instagram/basic-profile	userId	314216
Instagram 嵌入 HTML	/v1/instagram/user/embed	handle	jane
年龄 / 性别检测	/v1/detect/age-gender	url（社交资料）	https://www.tiktok.com/@charlidamelio
余额	/v1/credit/balance	（无）

ScrapeCreators 分页

分页端点会在响应中返回游标 / 令牌。将其作为查询参数传回，即可获取下一页。

游标字段	使用端点
cursor	TikTok 评论 / 搜索 / 歌曲视频、Instagram 评论、Reddit 子版块搜索、Pinterest、Bluesky、Facebook Reels / 照片 / 帖子 / 评论、TikTok Shop 商品 / 用户展示
max_cursor	TikTok 个人资料视频
min_time	TikTok 关注中 / 粉丝
continuationToken	YouTube（所有分页端点）
after	Reddit 帖子、Reddit 搜索
next_max_id	Instagram 帖子、Truth Social 帖子
max_id	Instagram Reels
page	TikTok 热门 / 商店、Instagram Reels 搜索、LinkedIn 公司帖子、TikTok Shop 评论
paginationToken	LinkedIn 广告

ScrapeCreators 已知限制

• 用户名：传入时不要带 @ 符号。使用 charlidamelio，不要使用 @charlidamelio。适用于 TikTok、Instagram、Twitter、Threads、Bluesky、Snapchat、Twitch、Pinterest、Truth Social
• YouTube 用户名：传入时不要带 @ 符号。使用 ThePatMcAfeeShow，不要使用 @ThePatMcAfeeShow。也可以传入 channelId 或完整 URL
• 标签：传入时不要带 # 符号。使用 fyp，不要使用 #fyp。适用于 TikTok 和 YouTube 标签搜索端点
• Twitter：返回约 100 条最热门推文，而非按时间顺序排列的最新推文
• Threads：公开可见的仅有最近 20-30 条帖子
• Facebook 帖子：每页仅有 3 条帖子（API 限制）
• Facebook 群组帖子：每页仅有 3 条帖子（相同限制）
• LinkedIn 公司帖子：最多 7 页
• Instagram 播放量：仅统计 IG 播放量（不包括跨发到 FB 的播放量）
• Truth Social：只有知名用户（Trump、Vance 等）的内容可公开获取
• 文字稿：所有文字稿端点都要求视频时长少于 2 分钟
• Reddit 子版块名称：区分大小写！使用 “AskReddit”，不要使用 “askreddit”

---

访问模式

ScrapeCreators（社交媒体）

使用 Python 和 core.http_client.proxied_get，以便 sc-proxy 注入凭据并正确计费。添加带类型的 SC-CALLER-ID 标头（chat:、job:、preview: 等）以跟踪成本。不要从环境变量中读取 $SCRAPECREATORS_API_KEY，也不要向用户索要密钥——代理会处理。

from core.http_client import proxied_get

headers = {"SC-CALLER-ID": "chat:youtube-transcript"}

transcript = proxied_get(
    "https://api.scrapecreators.com/v1/youtube/video/transcript",
    params={"url": "https://www.youtube.com/watch?v=VIDEO_ID", "language": "en"},
    headers=headers,
    timeout=20,
).json()

Bash/curl 也可以使用（代理是透明的），但为便于跟踪成本，优先使用 Python：

curl -s "https://api.scrapecreators.com/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: any"

每个端点都有自己的 OpenAPI 规范，位于 https://docs.scrapecreators.com/{path}/openapi.json。实际调用 API 前，务必先获取对应端点的规范，以了解完整的参数详情。完整规范位于 https://docs.scrapecreators.com/openapi.json（文件较大——优先使用各端点的规范）。

常见可选参数：

• trim（布尔值）：减小响应载荷。只需要关键指标时使用。
• region（字符串）：用于设置代理位置的 2 位国家/地区代码。不会按地区筛选——只会通过该国家 / 地区的代理路由。

Firecrawl（通过透明代理作为网页抓取回退方案）

无需 Firecrawl API 密钥——sc-proxy 会注入密钥。不要在 .env 中查找，也不要向用户询问。直接调用：

from core.http_client import proxied_post

headers = {"SC-CALLER-ID": "chat:web-crawl-fallback"}

page = proxied_post(
    "https://api.firecrawl.dev/v2/scrape",
    json={
        "url": "https://example.com/article",
        "formats": ["markdown", "links"],
        "onlyMainContent": True,
        "timeout": 60000,
    },
    headers=headers,
).json()

决策规则

将每个请求路由到正确的后端。用户不应需要指定使用哪个 API。

社交媒体请求（个人资料、帖子、评论、搜索、广告、趋势内容、转录文本）

使用 ScrapeCreators。根据用户意图，从上方的路由表中选择端点。调用前，从账号名称中去掉 @，从话题标签中去掉 #。先获取相应端点的 OpenAPI 规范，以了解完整的参数详情。

YouTube URL 或 YouTube 内容请求

对 YouTube 使用 ScrapeCreators（频道信息、视频、Shorts、播放列表、评论、转录文本、搜索、趋势 Shorts）。根据用户意图，从上方的路由表中选择合适的 YouTube 端点。

对于 YouTube URL，使用 /v1/youtube/video 获取视频详情和转录文本。如果用户的目标是内容分析、摘要、提取引言或挖掘主题，视频响应中会包含转录文本。

对于 YouTube 主题查询，使用 /v1/youtube/search 查找相关视频，然后仅对需要的视频调用 /v1/youtube/video。默认情况下，避免获取大量视频。

被拦截或大量依赖 JS 的网页

使用 Firecrawl，调用一次，并设置 formats:["markdown","links"] 和 onlyMainContent:true。将返回的 Markdown 视为提取依据，而非最终事实：从页面结构中解析标题、价格／价值字段、规格、正文描述、图片 URL、外链以及明显的联系／位置信息。

网页提取的一般经验：

• 许多列表页／详情页会通过 JavaScript、图片库、隐藏部分或重复的界面标签来呈现重要内容。web_fetch 可能只返回模板内容，而 Firecrawl 仍能提取出真实的主要内容。
• 不要硬编码特定网站的标签。将页面文本转换为通用结构化摘要：内容是什么、位于何处、关键数字、证据片段、媒体／链接以及注意事项。
• 保留有助于验证页面的图片和链接源 URL，但除非用户要求，否则不要下载或批量处理所有媒体资源。
• 如果 Markdown 遗漏了重要布局或结构化字段，可使用 rawHtml 重试一次；仅当用户要求特定范围的提取，且模式／提示词明确时，才使用 json、question 或 highlights。

成本控制

ScrapeCreators — 大多数端点每次请求收费 1 个额度。例外情况：/v1/tiktok/user/audience 收费 26 个额度；/v1/tiktok/video/transcript 在 use_ai_as_fallback=true 时额外收费 10 个额度；/v1/google/company/ads 在 get_ad_details=true 时收费 25 个额度。调用高价端点前，先提醒用户。

Firecrawl — 按页面计费，使用昂贵的修饰参数时费用更高。

控制调用范围：一个页面、一个视频或一个简短候选列表。使用此技能时，绝不要批量抓取整个网站或批量抓取整个信息流。

如果代理返回 403，说明请求不属于允许的使用场景。应更换处理方式，而不是重试。

如果代理返回 429，应退避；不要通过并行请求绕过限制。

如果上游返回失败，应报告确切的失败信息；除非明显有理由更改某个参数，否则避免反复进行付费重试。