felo-youtube-subtitling

Felo YouTube 字幕取得スキル

使用するタイミング

ユーザーが以下を希望する場合に、このスキルを使用します。

• YouTube 動画の字幕またはキャプションを取得する
• 動画 ID または動画 URL から文字起こしを抽出する
• 特定の言語（例：en、zh-CN）の字幕を取得する
• 分析や翻訳用にタイムスタンプ付きの字幕を取得する

トリガーキーワード（例）：

• YouTube 字幕、キャプションを取得、動画の文字起こし、字幕を抽出、YouTube 字幕
• 明示的な指定：/felo-youtube-subtitling、「felo youtube subtitling を使用」

以下の場合は使用しないでください。

• リアルタイム検索（felo-search を使用）
• Web ページのコンテンツ取得（felo-web-fetch を使用）
• スライドの生成（felo-slides を使用）

セットアップ

1. API キーを取得する

1. felo.ai にアクセスします
2. Settings -> API Keys を開きます
3. API キーを作成してコピーします

2. 環境変数を設定する

Linux/macOS：

export FELO_API_KEY="your-api-key-here"

Windows PowerShell：

$env:FELO_API_KEY="your-api-key-here"

実行方法

オプション A：同梱スクリプトまたはパッケージ版 CLI を使用する

スクリプト（リポジトリから）：

node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs --video-code "dQw4w9WgXcQ" [options]

パッケージ版 CLI（npm install -g felo-ai の実行後）：

felo youtube-subtitling -v "dQw4w9WgXcQ" [options]
# Short forms: -v (video-code), -l (language), -j (json)

オプション：

オプション	デフォルト	説明
--video-code / -v	（必須）	YouTube の動画 URLまたは動画 ID（例：https://youtube.com/watch?v=ID または dQw4w9WgXcQ）
--language / -l	-	字幕の言語コード（例：en、zh-CN）
--with-time	false	各セグメントに開始時刻／再生時間のタイムスタンプを含めます
--json / -j	false	API レスポンス全体を JSON で出力します

YouTube の完全なリンクまたは11 文字の動画 IDを指定できます。

• 対応 URL：https://www.youtube.com/watch?v=ID、https://youtu.be/ID、https://youtube.com/embed/ID
• または ID のみ：dQw4w9WgXcQ

例：

# With video URL
node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs --video-code "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
felo youtube-subtitling -v "https://youtu.be/dQw4w9WgXcQ"

# With video ID
node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs -v "dQw4w9WgXcQ" --language zh-CN

# With timestamps
node felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs -v "dQw4w9WgXcQ" --with-time --json

オプション B：curl で API を呼び出す

curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $FELO_API_KEY"

API リファレンス（概要）

• エンドポイント：GET /v2/youtube/subtitling
• ベース URL：https://openapi.felo.ai。必要に応じて FELO_API_BASE 環境変数で上書きできます。
• 認証：Authorization: Bearer YOUR_API_KEY

クエリパラメーター

パラメーター	型	必須	デフォルト	説明
video_code	string	はい	-	YouTube 動画 ID（例：dQw4w9WgXcQ）
language	string	いいえ	-	言語コード（例：en、zh-CN）
with_time	boolean	いいえ	false	各セグメントの開始時刻／再生時間を含めます

レスポンス（200）

{
  "code": 0,
  "message": "success",
  "data": {
    "title": "Video title",
    "contents": [
      { "start": 0.32, "duration": 14.26, "text": "Subtitle text" }
    ]
  }
}

with_time=false の場合、start／duration は存在しないか、値がゼロになることがあります。contents[].text は常に存在します。

エラーコード

HTTP	Code	説明
400	-	パラメーターの検証に失敗しました（例：video_code が未指定）
401	INVALID_API_KEY	API キーが無効、または取り消されています
500/502	YOUTUBE_SUBTITLING_FAILED	サービスエラー、または動画の字幕を取得できません

出力形式

• --json を指定しない場合：タイトルを出力し、その後に各セグメントのテキストを出力します（1 行ずつ、または連結して出力）。--with-time を指定すると、タイムスタンプが含まれます。
• --json を指定した場合：API レスポンス全体を出力します。

失敗時（字幕がない、API エラー）：標準エラー出力にメッセージを表示し、終了コード 1 を返します。例：

YouTube subtitling failed for video dQw4w9WgXcQ: YOUTUBE_SUBTITLING_FAILED

重要な注意事項

• すべての動画に字幕があるわけではありません。一部の動画では API がエラーを返すことがあります。
• 言語コードは、動画で利用可能な字幕トラックと一致している必要があります。
• 他の Felo スキルと同じ FELO_API_KEY を使用します。

参考資料

• Felo YouTube 字幕取得 API
• Felo Open Platform