Felo YouTube Subtitling Skill

When to Use

Trigger this skill when the user wants to:

Get subtitles or captions from a YouTube video
Extract transcript by video ID or video URL
Fetch subtitles in a specific language (e.g. en, zh-CN)
Get subtitles with timestamps for analysis or translation

Trigger keywords (examples):

YouTube subtitles, get captions, video transcript, extract subtitles, YouTube 字幕
Explicit: /felo-youtube-subtitling, "use felo youtube subtitling"

Do NOT use for:

Real-time search (use felo-search)
Web page content (use felo-web-fetch)
Generating slides (use felo-slides)

Setup

1. Get API key

Visit felo.ai
Open Settings -> API Keys
Create and copy your API key

2. Configure environment variable

Linux/macOS:

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

Windows PowerShell:

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

How to Execute

Option A: Use the bundled script or packaged CLI

Script (from repo):

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

Packaged CLI (after npm install -g felo-ai):

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

Options:

Option	Default	Description
`--video-code` / `-v`	(required)	YouTube video URL or video ID (e.g. `https://youtube.com/watch?v=ID` or `dQw4w9WgXcQ`)
`--language` / `-l`	-	Subtitle language code (e.g. `en`, `zh-CN`)
`--with-time`	false	Include start/duration timestamps in each segment
`--json` / `-j`	false	Print full API response as JSON

You can pass either a full YouTube link or the 11-character video ID:

Supported URLs: https://www.youtube.com/watch?v=ID, https://youtu.be/ID, https://youtube.com/embed/ID
Or plain ID: dQw4w9WgXcQ

Examples:

# 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

Option B: Call API with curl

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

API Reference (summary)

Endpoint: GET /v2/youtube/subtitling
Base URL: https://openapi.felo.ai. Override with FELO_API_BASE env if needed.
Auth: Authorization: Bearer YOUR_API_KEY

Query parameters

Parameter	Type	Required	Default	Description
video_code	string	Yes	-	YouTube video ID (e.g. dQw4w9WgXcQ)
language	string	No	-	Language code (e.g. en, zh-CN)
with_time	boolean	No	false	Include start/duration per segment

Response (200)

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

With with_time=false, start/duration may be absent or zero. contents[].text is always present.

Error codes

HTTP	Code	Description
400	-	Parameter validation failed (e.g. missing video_code)
401	INVALID_API_KEY	API key invalid or revoked
500/502	YOUTUBE_SUBTITLING_FAILED	Service error or subtitles unavailable for video

Output Format

Without --json: print title and then each segment's text (one per line or concatenated). If --with-time, output includes timestamps.
With --json: print full API response.

On failure (no subtitles, API error): stderr message and exit 1. Example:

YouTube subtitling failed for video dQw4w9WgXcQ: YOUTUBE_SUBTITLING_FAILED

Important Notes

Not all videos have subtitles; the API may return an error for some videos.
Language code must match a subtitle track available for the video.
Same FELO_API_KEY as other Felo skills.

felo-youtube-subtitling