Configure Harness

YouTube Subtitling API

Fetch YouTube subtitles with optional language and timestamp parameters.

GET/v2/youtube/subtitling

Authentication

Bearer API key

Content type

Not required

Rate notes

Endpoint-specific limits may apply.

Web Fetch API

The YouTube Subtitling API fetches structured subtitle data for a YouTube video. It is designed for agents, content analysis tools, education products, search indexes, and workflows that need video content as text.

Endpoint

GET https://openapi.felo.ai/v2/youtube/subtitling

Authentication

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for details on creating and managing API keys.

Use with AI Agents

Install the complete felo-ai package to give an Agent YouTube subtitling and every other available Felo Skill. The installer dynamically discovers every package directory containing SKILL.md, so it does not depend on a fixed Skill list. Install all discovered Skills in Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills, or Hermes Agent ~/.hermes/skills. Use the manual AI Agent setup guide for platform-specific API key configuration and verification.

Request

Query Parameters

Parameter	Type	Required	Default	Description
`video_code`	string	Yes	-	YouTube video ID, such as `dQw4w9WgXcQ`.
`language`	string	No	-	Subtitle language code, such as `en` or `zh-CN`. If omitted, the downstream service chooses the available language.
`with_time`	boolean	No	`false`	Whether to include timestamp fields (`start` and `duration`) for each subtitle item.

The service uses the full title-and-transcript mode internally. You do not need to pass a function type or mode parameter.

Response

Success Response

{
  "status": "ok",
  "message": null,
  "data": {
    "title": "Example Video Title",
    "contents": [
      {
        "start": 0.32,
        "duration": 14.26,
        "text": "Subtitle text"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`status`	string	Response status. Usually `ok` for a successful request.
`message`	string or null	Additional message. Usually `null` for successful requests.
`data.title`	string	YouTube video title.
`data.contents`	array	List of subtitle items.
`data.contents[].start`	number	Subtitle start time in seconds. Returned when timestamp data is available, especially when `with_time=true`.
`data.contents[].duration`	number	Subtitle duration in seconds. Returned when timestamp data is available, especially when `with_time=true`.
`data.contents[].text`	string	Subtitle text content.

Error Responses

HTTP Status	Error Code	Description	Suggested Action
400	`YOUTUBE_SUBTITLING_FAILED`	Request validation failed, the video does not exist, subtitles are unavailable, or the downstream service returned a client-side error.	Check `video_code`, subtitle availability, and `language`.
401	`INVALID_API_KEY`	API key is missing, invalid, or revoked.	Verify your API key and authorization header.
500	`YOUTUBE_SUBTITLING_FAILED`	Internal service error.	Retry the request. Contact support if the issue persists.
502	`YOUTUBE_SUBTITLING_FAILED`	The downstream YouTube subtitle service failed or was unavailable.	Retry later.

Examples

Basic Request

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

Request a Specific Language

curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ&language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

Include Timestamps

curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ&with_time=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Include Timestamps for a Specific Language

curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ&language=zh-CN&with_time=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Cases

Let an agent understand a YouTube video before answering questions.
Build a searchable text index for video content.
Prepare source text for summarization or translation workflows.
Map generated notes or quotes back to timestamps.
Analyze educational or research videos without downloading the video file.

Notes

This API does not download video or audio.
It returns existing subtitles. It does not generate subtitles for videos that do not have subtitle data.
Some videos may not have subtitles, or may not provide the requested language.
If language is omitted, subtitle language selection depends on downstream availability.