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 日で一致すること。トランスクリプト URL が 2xx、500 文字超、エラーページでないこと
番組自身の YouTube アップロード	チャンネル = 番組が RSS で宣言している YouTube URL (そうでなければ、チャンネル名がストップワードを除いた番組名と一致する検索ヒット)	候補 = 再生時間 ±5 % かつ 日付 ±3 日。同一性 = タイトル類似度 ≥ 0.6 または ショーノートの重複 (≥ 6 個の共通する特徴的トークン、Jaccard ≥ 0.15)。同一性チェックに失敗した候補は found=False として candidate に返されます — エピソードとして配信されることは決してありません
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: トランスクリプトホストでの 2 回の 403 により、あるエージェントは 49 MB の mp3 + ffmpeg + 4 回の whisper 呼び出し + 不完全な要約に至りました。同じリンクを get_transcript 経由で処理した場合: RSS にトランスクリプトなし → RSS が youtube.com/@a16z を宣言 → チャンネル一覧 → 再生時間の 1.2 % 以内、同日のアップロードが 1 件 → キャプション、55k 文字、約 30 秒、音声ゼロ。

クイックトリガールール (最初にこれを読んでください)

次のいずれかの条件が真の場合、このスキルを直ちに使用してください:

• web_fetch が HTTP 401/403/429/5xx を返す
• レスポンスがアンチボットチャレンジページである (たとえば Cloudflare の「Attention Required」、「Just a moment」、またはチャレンジ / キャプチャページ)
• ページが JS 主体で、最初のフェッチで必要な詳細フィールド (たとえば公開時刻、著者、リスティングコード、更新時刻、価格の内訳) が欠落している
• 検索結果に要求されたフィールドが含まれておらず、値が対象ページ自体から抽出される必要がある

フォールバックルール:

• 通常のフェッチがブロックされるか不完全な場合、ユーザーにスクリーンショット / 手動テキストを求める前に、このスキルの Firecrawl フォールバックに切り替えてください。

エラーシグネチャ -> アクション

シグネチャ	アクション
web_fetch HTTP 401/403/429/5xx	Firecrawl の POST /v2/scrape を formats:["markdown","links"] + onlyMainContent:true で一度呼び出します
本文に 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) を呼び出します — Web アーカイブのスナップショットから全文を復元します
中国アプリから構造化データが必要（抖音/小红书/微博/B站/京东/淘宝/1688/闲鱼/得物 など）	apify_run() を呼び出します — Apify Store には、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 でリトライを繰り返さないでください。代わりに Web アーカイブのスナップショットから記事を復元します:

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 を使用）

中国アプリから構造化データが必要な場合 — Douyin の動画検索、小红书のノート、微博の投稿、Bilibili の動画、JD/Taobao の商品価格、1688 の卸売リスト、闲鱼の中古品、得物のスニーカーなど — Firecrawl と ScrapeCreators はこれらのプラットフォームをカバーしていません。代わりに Apify Store のフォールバックを使用してください。Apify はサーバーレスのスクレイパーマーケットプレイスで、中国のプラットフォームに対して実際のブラウザ + プロキシプールを実行する、コミュニティが保守する数百のアクターを備えています。

認証: ユーザーが提供するキーは不要です。sc-proxy がプラットフォームの Apify トークンを自動的に注入します。Authorization: Bearer ヘッダーは任意の偽の値でかまいません — プロキシがそれを実際のトークンに置き換えます。環境変数から $APIFY_TOKEN を読み取らないでください。.env を確認しないでください。ユーザーに Apify キーを尋ねないでください。

Apify を使うべき場合（Firecrawl/ScrapeCreators との比較）:

• ✅ 中国アプリ: 抖音、小红书、微博、B站、京东、淘宝、1688、闲鱼、携程、知乎、豆瓣、雪球、优酷（得物/快手/爱奇艺: 価格設定されたアクターがないため Store を検索してください）
• ✅ 東南アジアの E コマース: Shopee、Lazada、Temu
• ✅ Instagram のストーリー（ScrapeCreators にはストーリーのエンドポイントがありません）— 以下の「Instagram ストーリー」を参照してください
• ❌ その他の西欧のソーシャルメディア（TikTok/Instagram の投稿 & リール/YouTube/X/Reddit）→ まず ScrapeCreators を使用してください（より安価です）
• ❌ 一般的な Web ページのスクレイピング → まず Firecrawl を使用してください（より安価です）
• ❌ ハードペイウォールの記事 → archive_fallback を使用してください（Apify はここでは役に立ちません） アクターの選び方: まず以下の表を使用してください — これらのアクターは sc-proxy で価格設定されており、2026-10-08 にライブで検証済みです（括弧内は 30 日間の成功実行数）。記載されていないプラットフォームについては、プロキシ経由で Store を検索し（proxied_get("https://api.apify.com/v2/store?search=<platform>&limit=10")）、 30 日間の実行数の多いものを優先し、デフォルトの $0.007/結果 の価格を想定してください。

Platform	Actor ID	Input key
抖音 search	zen-studio~douyin-search-scraper	{"keywords": [...], "maxResultsPerQuery": N}
抖音 creator profile	zen-studio~douyin-profile-scraper (22k)	(see actor input schema)
抖音 video/audio download	apple_yang~douyin-video-audio-downloader (5k)	(see actor input schema)
抖音 transcripts	apple_yang~douyin-transcripts-scraper (2.6k)	(see actor input schema)
小红书 search	zen-studio~rednote-search-scraper	{"keywords": [...], "maxResults": N}
小红书 note detail	sian.agency~xiaohongshu-rednote-scraper	{"operation": "noteDetail", "noteId": "...", "xsecToken": "..."}
小红书 data API	socialdatax~socialdatax-xhs-data-api (64k)	(see actor input schema)
微博 hot search	gentle_cloud~weibo-hot-search-scraper	{"mode": "hot_band", "includeScores": true}
微博 posts/comments	zhorex~weibo-scraper (5k) または sian.agency~weibo-scraper (17k)	(see actor input schema)
B站 videos/comments/danmaku	zhorex~bilibili-scraper (17k)	(see actor input schema)
知乎 Q&A/articles	sian.agency~zhihu-scraper	(see actor input schema)
豆瓣 reviews/subjects	zhorex~douban-scraper	(see actor input schema)
雪球 stock discussion	zhorex~xueqiu-scraper (low volume)	(see actor input schema)
优酷 videos	sian.agency~youku-video-scraper (low volume)	(see actor input schema)
京东 search	zen-studio~jd-com-search-scraper	{"keyword": "...", "maxProducts": N}
京东 products	sian.agency~jd-com-product-scraper	{"operation": "productSearch", "keyword": "...", "maxPages": 1}
淘宝 search / detail	zen-studio~taobao-search-scraper / zen-studio~taobao-detail-scraper (18k)	(see actor input schema)
淘宝/天猫 products	sian.agency~taobao-tmall-product-scraper	{"operation": "keywordSearch", "keyword": "...", "maxPages": 1}
1688 wholesale	zen-studio~1688-wholesale-scraper または devcake~1688-com-products-scraper	(see actor input schema)
闲鱼 search	zen-studio~goofish-xianyu-search-scraper	(see actor input schema)
Shopee / Lazada / Temu	gio21~shopee-scraper / fatihtahta~lazada-scraper / amit123~temu-products-scraper	(see actor input schema)
携程 / Trip.com reviews	knagymate~trip-com-reviews-scraper (89k)	(see actor input schema)
Instagram stories	data-slayer~instagram-stories-scraper	{"usernames": [...]} — 「Instagram stories」を参照
TikTok	clockworks~tiktok-scraper	{"hashtags": [...]} または {"profiles": [...]}

価格設定済みのアクターでカバーされていないもの: 快手、爱奇艺 — Store を検索し、 そのアクターが未検証であることをユーザーに警告してください。

小红书の 2 ステップワークフロー（search → note detail）: search スクレイパー（zen-studio~rednote-search-scraper）は切り詰められた desc（約 60 文字）のみを返します。完全な投稿本文を取得するには、 sian.agency~xiaohongshu-rednote-scraper を noteDetail モードで 2 回目の呼び出しを実行し、 search 結果行の 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 は pay-per-event 課金を使用します: (actor-start + result_count × per_result + add-ons) × 2 クレジット。 支配的な要因は 結果数 × 結果ごとの価格 であり、各アクターはそれぞれ異なる価格設定 です（$0.003～$0.007/結果）。未知のアクターはデフォルトで最高ティア（$0.007）になります。完全な価格表と見積もり例: reference/apify-pricing.md。 呼び出す前に必ずコストを見積もる必要があります:

1. アクターの1件あたりの価格を調べます（表は reference/apify-pricing.md にあります。 未記載の場合は $0.007）。
2. 入力パラメータ（maxResults、maxProducts など）から結果件数を見積もります。 上限が設定されていない場合は、100件以上と想定してください。
3. 計算します: result_count × per_result × 2 = 推定クレジット。
4. 見積もりが 5 クレジットを超える場合は、続行する前にユーザーにコストを伝えてください。

厳格な支出上限 — プロキシによるデフォルト適用 + 呼び出しごとの上書き:

プロキシは、まだ指定されていないすべてのアクター実行に対して 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。潜在的なコストについて警告したうえで ユーザーが明示的に上限なしの実行を求めない限り、これは絶対にしないでください。

まず小規模バッチでテスト: アクターを初めて使用する場合は、max_charge_usd=0.5（≈ 1 クレジット）を設定し、 結果を 5〜10 件に制限します。スケールアップする前に出力品質を確認してください。

エラー処理:

• 400 run-failed → 不正な入力（フィールド名の誤り）。アクターの入力スキーマページを取得して修正します。
• 401 → プロキシの設定ミス（発生しないはずです）。ユーザーに報告します。
• 空の結果 [] → アクターは実行されましたが、何も見つかりませんでした。別のキーワードや別のアクターを試してください。
• タイムアウト → timeout パラメータを増やします（デフォルト 180 秒）。一部のアクターは遅いです。

Instagram — コンテンツ別のルート

コンテンツ	ルート
プロフィール、自己紹介、最近の投稿	sc_get('/v1/instagram/profile', handle=...)
すべての投稿 / すべてのリール	/v2/instagram/user/posts / /v1/instagram/user/reels（ページネーション）
1 件の投稿またはリール	sc_get('/v1/instagram/post', url=...)
投稿/リールで話された内容	/v2/instagram/media/transcript（2 分以内）
コメント	/v2/instagram/post/comments
ハイライト	/v1/instagram/user/highlights → /v1/instagram/user/highlight/detail
キーワード別のリール	/v2/instagram/reels/search
ライブストーリー（24 時間以内）	Apify data-slayer~instagram-stories-scraper — 以下のセクション
非公開アカウント、DM、フォロワーリスト	利用不可 — その旨を伝えてください

/v1/instagram/song/reels は上流で非推奨になっています（Instagram が音声 ページを削除しました）。呼び出さないでください。

Instagram ストーリーズ（apify_run を使用）

ストーリーズの URL（instagram.com/stories/<user>/<id>）は、ScrapeCreators（ストーリーズ用エンドポイントがなく、ハイライトのみ）や Firecrawl（ログインの壁）からはアクセスできません。 これらをリトライしないでください — プロキシ経由で 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 秒のストーリーズを 1 回の呼び出しで処理します。文字起こし + 画面内テキスト）。
• Apify が何も返さない場合: /v1/instagram/user/highlights を確認してください。それでもない場合、ユーザーの Chrome が接続されており（control-browser）、Instagram にログインしていれば、そこでストーリーズを開いてください。そうでなければ、画面録画（スクリーンショットではなく — ほとんどのストーリーズは音声付き動画です）を依頼してください。
• 2026-10-08 に検証済み: 5 アカウントで約 8〜13 秒、実際の Apify コストは約 $0.0025/結果。

コストの規律: Apify のアクターは Firecrawl/ScrapeCreators よりも高コストです。 Apify は、より安価な選択肢ではデータを取得できない場合（中国のアプリ、 Instagram ストーリーズ、構造化された e コマースのフィールド）にのみ使用してください。単一の Web ページの場合は、常にまず 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 — フォールバックの Web ページスクレイパー

通常の取得が失敗した場合に、単一の Web ページ用のフォールバッククローラーとしてのみ使用します。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 でその OpenAPI 仕様を取得し、完全なパラメータの詳細、型、レスポンス例を確認してください。例: 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 リール	/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 ショート	/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 リール	/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 または 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～30 秒、2 分未満
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/...	2 分未満のみ
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 リール	/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 または companyName	Lululemon
Facebook 広告詳細	/v1/facebook/adLibrary/ad	id または url	702369045530963
Facebook 企業検索	/v1/facebook/adLibrary/search/companies	query	Nike
Google 企業広告	/v1/google/company/ads	domain または 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 または 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（必須）	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
トレンドショート（YT）	/v1/youtube/shorts/trending

フォロワー / フォロー中 / ライブ（TikTok のみ）

種類	エンドポイント	例
フォロー中	/v1/tiktok/user/following	handle=stoolpresidente
フォロワー	/v1/tiktok/user/followers	handle=stoolpresidente
オーディエンス属性	/v1/tiktok/user/audience（26 クレジット！）	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 または product_id	1731578642912612516
ユーザーショーケース	/v1/tiktok/user/showcase	handle	mrtiktokreviews

リンク-in-バイオ / その他

サービス	エンドポイント	パラメータ	例
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 リール/写真/投稿/コメント、TikTok Shop 商品/ユーザーショーケース
max_cursor	TikTok プロフィール動画
min_time	TikTok フォロー中/フォロワー
continuationToken	YouTube（すべてのページネーション対応エンドポイント）
after	Reddit 投稿、Reddit 検索
next_max_id	Instagram 投稿、Truth Social 投稿
max_id	Instagram リール
page	TikTok 人気/ショップ、Instagram リール検索、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 投稿: 1 ページにつき 3 件の投稿のみ（API の制限）
• Facebook グループ投稿: 1 ページにつき 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"

各エンドポイントには、https://docs.scrapecreators.com/{path}/openapi.json に独自の OpenAPI 仕様があります。実際の API 呼び出しを行う前に、常にエンドポイントごとの仕様を最初に取得して、完全なパラメータの詳細を確認してください。完全な仕様は https://docs.scrapecreators.com/openapi.json にあります（大きなファイルです — エンドポイントごとの仕様を優先してください）。

一般的なオプションパラメータ:

• trim（boolean）: レスポンスのペイロードサイズを削減します。主要な指標のみが必要な場合に使用します。
• region（string）: プロキシの場所を指定する 2 文字の国コード。リージョンによるフィルタリングは行いません — その国のプロキシを経由するだけです。

Firecrawl（透過プロキシ経由の Web ページフォールバック）

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 を使用します（チャンネル情報、動画、ショート、プレイリスト、コメント、文字起こし、検索、トレンドのショート）。ユーザーの意図を上記のルーティングテーブルの適切な YouTube エンドポイントに照合します。

YouTube URL の場合は、/v1/youtube/video を使用して動画の詳細と文字起こしを取得します。ユーザーの目的がコンテンツ分析、要約、引用の抽出、トピックのマイニングである場合、文字起こしは動画のレスポンスに含まれています。

YouTube のトピッククエリの場合は、/v1/youtube/search を使用して関連する動画を検索し、必要な動画に対してのみ /v1/youtube/video を呼び出します。デフォルトで多数の動画を取得することは避けてください。

ブロックされている、または JS を多用する Web ページ

Firecrawl を formats:["markdown","links"] と onlyMainContent:true を指定して 1 回だけ使用します。返された Markdown は抽出の基盤として扱い、最終的な真実とはみなしません。ページ構造からタイトル、価格／値のフィールド、仕様、本文の説明、画像 URL、外部リンク、明らかな連絡先／所在地の手がかりを解析します。

一般的な Web ページ抽出の教訓:

• 多くのリスティング／詳細ページは、JavaScript、画像ギャラリー、非表示セクション、繰り返し表示される UI ラベルによって重要なコンテンツをレンダリングします。web_fetch が定型文を返しても、Firecrawl は実際のメインコンテンツを復元できる場合があります。
• サイト固有のラベルをハードコードしないでください。ページのテキストを汎用的な構造化サマリーに変換します。つまり、それが何であるか、どこにあるか、主要な数値、根拠となる抜粋、メディア／リンク、注意事項です。
• ページの検証に役立つ場合は、画像やリンクのソース URL を保持しますが、ユーザーが求めない限り、すべてのメディアアセットをダウンロードしたり一括処理したりしないでください。
• Markdown が重要なレイアウトや構造化フィールドを見落としている場合は、rawHtml で 1 回だけ再試行します。json、question、highlights は、ユーザーが限定的な抽出を求めており、スキーマ／プロンプトが具体的である場合にのみ使用します。

コストの規律

ScrapeCreators — ほとんどのエンドポイントは 1 リクエストあたり 1 クレジットです。例外: /v1/tiktok/user/audience は 26 クレジット、use_ai_as_fallback=true を指定した /v1/tiktok/video/transcript は +10 クレジット、get_ad_details=true を指定した /v1/google/company/ads は 25 クレジットです。高コストのエンドポイントを呼び出す前にユーザーに警告します。

Firecrawl — ページごとの課金に加えて、高コストな修飾子があります。

呼び出しは最小限に抑えます。1 ページ、1 動画、または少数の候補リストにとどめます。このスキルで Web サイト全体を一括クロールしたり、フィード全体を一括スクレイピングしたりしないでください。

プロキシが 403 を返した場合、そのリクエストは許可されたユースケースの範囲外です。再試行するのではなく、アプローチを変更してください。

プロキシが 429 を返した場合、バックオフします。制限を回避して並列化しないでください。

上流が失敗を返した場合、正確な失敗を報告し、1 つのパラメータ変更が明らかに正当化されない限り、有料の再試行を繰り返さないでください。