YouTube Get Video Captions
## Purpose List the caption languages available for a YouTube video or retrieve existing captions in a selected language. ## Inputs - Provide at least one of `video_id` (recommended) or `video_url` (the full video URL). - Omit `language_code` or leave it empty to list available caption languages. To retrieve caption content, supply a code from that list, such as `en`, `zh-Hans`, or `a.en` when available. - `format` defaults to `srt`. Supported values are `srt` (numbered subtitles with timestamps), `xml` (raw XML), `json3` (YouTube JSON caption structure), and `txt` (plain text without timestamps). ## Results and usage First request the language list if you do not know which languages are available, then request content using a returned language code. The language-list result includes `video_id` and a `captions` list with `language_code` and `language_name` entries. A content request returns captions in the selected format. Larger videos may require asynchronous processing. A `processing` status with a `job_id` means the result is pending, not that caption text is ready; wait for processing to complete before using the final content. If the video has no captions, the result contains an empty `captions` list and a message indicating that no transcript is available. Only existing captions are retrieved: this tool does not generate captions from audio or translate them into unavailable languages. ## Pending caption jobs This tool returns the provider response from one request without automatically polling or creating an AE background task. If the response contains status=processing and a job_id, call ae_youtube_get_video_captions_result with that provider job_id and the same format. The provider job_id is not an AE task_id and must not be passed to ae_get_result. If the query remains queued or active, query again later as needed; an empty captions list with a no-transcript message is a valid no-captions result.
Pricing
| Condition | Charge |
|---|---|
| Each call | 16.52 credits/call |
16.52 credits/call Charges are per query. A successful query is billed even if it returns no results.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
format | enum (srt | xml | json3 | txt) | No | 字幕格式/Caption format | srt |
video_id | string | No | 视频ID/Video ID | — |
video_url | string | No | 视频URL/Video URL | — |
language_code | string | No | 语言代码,为空时返回可用字幕列表/Language code, returns available caption list if empty | — |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_youtube_get_video_captions' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"format": "txt",
"video_id": "JySw_9NLuxY"
}
}'{
"code": 200,
"data": {
"captions": [
{
"language_code": "zh",
"language_name": "Chinese"
}
],
"video_id": "JySw_9NLuxY"
},
"docs": "https://api.tikhub.io/#/YouTube-Web-V2-API/get_video_captions_api_v1_youtube_web_v2_get_video_captions_get",
"message": "Request successful. This request will incur a charge.",
"message_zh": "请求成功,本次请求将被计费。",
"params": {
"format": "txt",
"video_id": "JySw_9NLuxY"
}
}This example shows part of the response. Copied content is valid JSON.

