youtube-search

YouTube 検索

Frevana を通じて YouTube 動画を検索します。

目的

このスキルは、YouTube の検索結果を見つけるためのものです。

入力：

• search_query
• sp（任意）
• hl（任意）
• gl（任意）

出力：

• YouTube の検索結果を含む、検証済みのレスポンス JSON

このスキルは、レスポンスが JSON であることを検証し、変更せずに返します。ユーザーが変換を明示的に依頼しない限り、返されたデータを書き換えたり、形を変えたりしないでください。

このスキルに必要なもの

• ユーザーが指定した search_query
• sp（任意）
• hl（任意）
• gl（任意）
• 環境変数の FREVANA_TOKEN、または今回の実行で明示的に指定する --token の上書き
• curl
• bash
• python3

実行順序

リクエストをシンプルかつ確実に処理するため、次のフローを使用してください。

1. ユーザーが search_query またはそれに相当する YouTube 検索キーワードを指定していることを確認します。
2. 場当たり的な curl コマンドより、スクリプトを優先します。
3. スクリプトにまず FREVANA_TOKEN を読み込ませます。
4. 対話型のシェルで使用する場合、FREVANA_TOKEN がないときは、スクリプトが入力を求めることがあります。
5. 非対話型またはエージェントのワークフローでは、トークンがない場合はすぐに処理を中止し、ユーザーに FREVANA_TOKEN を設定するか、--token を明示的に渡すよう伝えます。
6. 検証済みのレスポンス JSON を返すか、ユーザーが完全なペイロードを必要としない場合は、最も関連性の高い動画を要約します。
7. 必要に応じて、JSON をファイルにも保存します。

コマンド

YouTube を基本検索する

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast"

--query は --search-query のエイリアスとして使用できます。

国と言語を指定して検索する

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --gl us \
  --hl en

sp フィルターまたはページネーショントークンを指定して検索する

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --sp "EgIQAQ%253D%253D" \
  --hl en \
  --gl us

ユーザーが YouTube のフィルタートークンを指定した場合や、レスポンスに含まれる後続トークンを使ってページネーション結果を続けて取得する場合は、--sp を使用します。

レスポンス JSON をファイルに保存する

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --gl us \
  --hl en \
  --output ./out/youtube-search-result.json

今回の実行でトークンを上書きする

bash <skill-path>/scripts/search_youtube.sh \
  --search-query "mrbeast" \
  --token "your bearer token"

固定リクエスト形式

スクリプトは、指定されていない任意フィールドを省略して、次の形式のペイロードを送信します。

{
  "search_query": "mrbeast",
  "sp": "EgIQAQ%253D%253D",
  "hl": "en",
  "gl": "us"
}

必須なのは search_query のみです。ユーザーが指定していない sp、hl、gl の値を推測して設定しないでください。

Frevana のエンドポイントはすでに YouTube 検索に限定されているため、engine、api_key、output、no_cache、async、zero_trace など、サポートされていないパススルーフィールドを渡さないでください。

レスポンス形式

API は JSON を返します。このスキルはレスポンスが JSON であることを検証し、変更せずに返します。

出力

• 成功時：スクリプトはレスポンス本文が JSON であることを検証し、標準出力に出力します
• --output を指定した場合：同じ JSON が指定されたファイルパスにも書き込まれます
• 失敗時：スクリプトはレスポンス本文または解析エラーを出力し、ゼロ以外の終了コードで終了します

注意事項

• --search-query または --query を必須とします
• ユーザーが特定の国または地域を指定した場合は --gl を使用します
• ユーザーが特定の言語を指定した場合は --hl を使用します
• --sp を使用するのは、ユーザーがフィルターまたはページネーショントークンを指定した場合、あるいは以前の YouTube 検索レスポンスに含まれていたトークンを使って結果の続きを取得するよう求めた場合のみです
• curl が見つからない場合は処理を中止し、ユーザーに curl のインストールを伝えます
• python3 が見つからない場合は処理を中止し、ユーザーに python3 のインストールを伝えます
• Bearer トークンをユーザーに再表示しないでください
• ユーザーが完全なペイロードを求めていない限り、未加工の JSON をそのまま出力するのではなく、ユーザーが実際に知りたい動画を要約します

プロンプト例

中国語

• 「YouTube で mrbeast を検索」
• 「YouTube で search_query=mrbeast、gl=us、hl=en の結果を調べて」
• 「この sp パラメーターを使って YouTube 検索の続きを取得し、元の JSON を保存して」

英語

• 「YouTube で mrbeast を検索」
• 「gl=us と hl=en を指定して、mrbeast の YouTube 検索結果を調べて」
• 「この sp トークンを使って YouTube を検索し、元の JSON をファイルに保存して」