# FlashData YouTube Captions API

Lấy lại YouTube đánh dấu thời gian và bản ghi đầy đủ. Tải về các tập tin âm thanh

Tài liệu tham khảo chính điển: https://flashdata.dev/vi/docs/sources/youtube_captions
Xem lại: 2026-10-23

Điểm kết thúc: POST https://data.flashdata.dev/v1/queries/realtime
Xác thực: X-API-Key: YOUR_API_KEY
Chế độ: [Realtime](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/vi/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md)

Cần thiết quyền truy cập nguồn: youtube_captions

Thay thế YOUR_API_KEY với một API Chìa khóa mà có quyền sử dụng nguồn này và tín dụng sẵn có. Chạy yêu cầu trên máy chủ hay máy phục vụ.

[Đang thiết lập xác thực](https://flashdata.dev/vi/docs/guides/headers-and-authentication/reference.md)

[Lấy phụ đề thời gian](https://flashdata.dev/vi/docs/guides/timestamped-captions-recipe/reference.md)

<a id="quickstart"></a>

## Gửi một yêu cầu

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_captions",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": False,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_captions",
  "video_id": "dQw4w9WgXcQ",
  "params": {
    "language": "en",
    "auto": false
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Tham số

<a id="parameters-group-0"></a>

### Nội dung yêu cầu

| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Vâng | — | Thiết lập youtube_captions.  |
| <a id="parameter-video_id"></a> video_id | string | Vâng | Chưa đặt | Hạt 11- Hồ sơ. YouTube video IDNhư FUfGcZ092b0. Chấp nhận chữ cái, số, điểm nhấn và dấu gạch nối. Chiều dài tối thiểu: 11. Chiều dài tối đa: 11. Mẫu: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Không | {} | Settings cho yêu cầu này.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Không | Chưa đặt | Async và chỉ một mẻ. Chung HTTPS hoàn tất URL trên cổng 443Đến 2,048 các nhân vật. Không có phân khúc người dùng hay URL. Omit, dùng null hoặc chuỗi rỗng không cho thông báo nào. Trong một mẻ, đặt nó trên mỗi câu hỏi, bên ngoài các tham số.  |

<a id="parameters-group-1"></a>

### Chọn độ xoay

| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-language"></a> params.language | string \| array | Không | en-orig → en | Omit cho tiếng Anh (en-oig, sau đó en). Với tự động =true, mỗi mã cố gắng -oig theo dõi trước, sau đó là mã đã yêu cầu. Explicit -ig mã và tự động =false Giữ nguyên vị trí. Yêu cầu Array 1–10 Những ngôn ngữ khác nhau. Omit thích en-orig và rơi trở lại để en, trở lại một theo dõi. Với tự động =true., mỗi mã cố gắng -ig theo dõi trước tiên, sau đó các mã yêu cầu; rõ ràng -og mã và tự động =false Giữ nguyên vị trí. Arrays 1–10 Các mã riêng biệt thử mọi ngôn ngữ đã yêu cầu, rồi trả lại dấu vết và các lỗi thay đổi theo thứ tự yêu cầu. languageCode xác định đường dẫn đã chọn; requestedLanguageCode được bao gồm khi nó khác với mật mã đã yêu cầu. |
| <a id="parameter-params-auto"></a> params.auto | boolean | Không | false | true lựa chọn YouTube-Các phụ đề được tạo ra; false chọn những phụ đề tải lên. Tùy chọn này chọn nguồn gốc chú thích, không phải phát hiện ngôn ngữ hay chuyển đổi mới.  |

<a id="response"></a>

## Đọc kết quả

Cứu người thành công JSON trả lời response.json. Lưu cái này vào read-response.py và chạy python read-response.py. Nó chỉ dùng thôi. PythonThư viện thông thường và không có yêu cầu mới.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Phản hồi mẫu

Ví dụ được thu; trường và số phụ thuộc vào nguồn và yêu cầu nhập.
```json
{
  "source": "youtube_captions",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 1.36,
          "end": 3.04,
          "text": "[♪♪♪]"
        },
        {
          "start": 18.64,
          "end": 21.880000000000003,
          "text": "♪ We're no strangers to love ♪"
        },
        {
          "start": 22.64,
          "end": 26.96,
          "text": "♪ You know the rules\nand so do I ♪"
        },
        {
          "start": 27.04,
          "end": 31.04,
          "text": "♪ A full commitment's\nwhat I'm thinking of ♪"
        },
        {
          "start": 31.12,
          "end": 35.08,
          "text": "♪ You wouldn't get this\nfrom any other guy ♪"
        },
        {
          "start": 35.16,
          "end": 39.52,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 40.52,
          "end": 42.92,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 43,
          "end": 45.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 45.2,
          "end": 47.080000000000005,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 47.32,
          "end": 51.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 51.48,
          "end": 53.48,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 53.6,
          "end": 55.52,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 55.72,
          "end": 59.36,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 60.8,
          "end": 64.8,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 64.88,
          "end": 69.03999999999999,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 69.12,
          "end": 72.96000000000001,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 73.36,
          "end": 77.2,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 77.4,
          "end": 82.04,
          "text": "♪ And if you ask me\nhow I'm feeling ♪"
        },
        {
          "start": 82.4,
          "end": 85.24000000000001,
          "text": "♪ Don't tell me\nyou're too blind to see ♪"
        },
        {
          "start": 85.32,
          "end": 87.27999999999999,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 87.36,
          "end": 89.32,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 89.44,
          "end": 93.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 93.8,
          "end": 95.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 95.76,
          "end": 98,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 98.08,
          "end": 102.04,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 102.2,
          "end": 104.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 104.28,
          "end": 106.36,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 106.48,
          "end": 110.08,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 110.76,
          "end": 112.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 112.8,
          "end": 114.68,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 114.96,
          "end": 118.76,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 119.84,
          "end": 122.96,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 123.72,
          "end": 127.36,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 128.48,
          "end": 130.11999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 130.24,
          "end": 131.56,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 132.48,
          "end": 134.23999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 134.36,
          "end": 135.92000000000002,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 136.76,
          "end": 141.07999999999998,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 141.2,
          "end": 145.2,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 145.28,
          "end": 149.12,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 149.52,
          "end": 153.20000000000002,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 153.36,
          "end": 158.04000000000002,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 158.64,
          "end": 161.32,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 161.4,
          "end": 163.36,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 163.44,
          "end": 165.64,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 165.72,
          "end": 169.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 169.8,
          "end": 171.64,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 171.8,
          "end": 173.96,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 174.04,
          "end": 177.6,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 178.2,
          "end": 180.24,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 180.32,
          "end": 182.44,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 182.52,
          "end": 186.64,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 186.72,
          "end": 188.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 188.84,
          "end": 190.72,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 190.84,
          "end": 195.2,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 195.28,
          "end": 197.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 197.2,
          "end": 199.24,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 199.4,
          "end": 203.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 203.36,
          "end": 205.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 205.68,
          "end": 207.84,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 207.92,
          "end": 211.32,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        }
      ],
      "fullText": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules\nand so do I ♪ ♪ A full commitment's\nwhat I'm thinking of ♪ ♪ You wouldn't get this\nfrom any other guy ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ And if you ask me\nhow I'm feeling ♪ ♪ Don't tell me\nyou're too blind to see ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ (Ooh, give you up) ♪ ♪ (Ooh, give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪"
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:46.290Z"
}
```

## Nhiều ngôn ngữ

Gửi một dãy ngôn ngữ để nhận dấu vết và lỗi per-language. Ví dụ này cho thấy không có tiếng Anh và tiếng Tây Ban Nha.

```json
{
  "source": "youtube_captions",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": false
  }
}
```

`results[0]`:

```json
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": false,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Uploader-provided subtitles not available for language: es"
    }
  ]
}
```

## Trường đáp ứng

| Tìm kiếm | Kiểu | Mô tả |
| --- | --- | --- |
| source | string | Nguồn API đã yêu cầu. |
| status | string | hoàn thành khi yêu cầu thời gian thực thành công. |
| created_at | string | Thời gian tạo ra đáp ứng trong ISO 8601 Định dạng. |
| usage.credits | number | Các nguồn tin cho yêu cầu, dựa trên kế hoạch của anh. |
| results[0].videoId | string | Video đã yêu cầu ID. |
| results[0].languageCode | string | Phần mềm theo dõi đã chọn đích danh, như en-oig. |
| results[0].languageName | string · nullable | Tên hiển thị ngôn ngữ nếu có. |
| results[0].requestedLanguageCode | string · optional | Mã đã yêu cầu khi nó khác với languageCodeVí dụ như en khi en-orig được chọn. |
| results[0].isAutoGenerated | boolean | Có tạo ra tự động phụ đề đã chọn hay không. |
| results[0].segments | array | Phần mở rộng theo thứ tự thời gian. |
| results[0].segments[].start | number | Đoạn phim sẽ bắt đầu trong vài giây. |
| results[0].segments[].end | number | Đoạn kết thúc thời gian trong vài giây. |
| results[0].segments[].text | string | Văn bản liên kết. |
| results[0].fullText | string | Tất cả đoạn văn đoạn thẳng vào bản ghi chép. |
| results[0].tracks | array · optional | Chỉ cho các dãy ngôn ngữ. Các đường ray sẵn sàng theo thứ tự yêu cầu; mỗi trường đơn có danh sách trên. |
| results[0].errors | array · optional | Chỉ cho các dãy ngôn ngữ. Lỗi ngôn ngữ theo thứ tự yêu cầu. Trống rỗng khi mọi dấu vết đều thành công. |
| results[0].errors[].languageCode | string | Ngôn ngữ đã yêu cầu bị lỗi. |
| results[0].errors[].code | string | language_unavailable khi đường dẫn đã chọn không tồn tại; retrieval_failed không thể tải hoặc phân tích nó. |
| results[0].errors[].message | string | Mô tả lỗi ngôn ngữ. |

- Hạt API Đọc phụ đề đã có vào YouTube. Nó không tạo ra bản ghi thay đổi mới hoặc rơi trở lại giữa tự động và phụ đề đã tải lên.
- Một ngôn ngữ dây giữ cho phản ứng theo một hướng đơn. Thậm chí một dãy"en"], đường dẫn và lỗi trở lại thay vì cấp cao languageCode, đoạn và fullText. Mỗi đường đua bao gồm những cánh đồng này, xe hơi áp dụng cho mọi ngôn ngữ.
- Với mảng ngôn ngữ, hãy kiểm tra errors để biết các bản phụ đề bị lỗi. Nếu không lấy được bản phụ đề nào, yêu cầu sẽ thất bại và số tín dụng đã giữ sẽ được hoàn lại. Lỗi trích xuất video hoặc yêu cầu hết thời gian chờ cũng làm yêu cầu thất bại.
- Sẵn sàng cho thời gian thực, một đơn vị, một mẻ đá và số lượng lớn. Bulk xuất khẩu ở lại JSONL với một ghi chép trên mỗi video, bao gồm dấu vết và lỗi. Accept và X-Respond-With áp dụng như thường lệ.

## Định dạng phản hồi

Đáp ứng được dùng JSON theo mặc định. Chọn một định dạng khác với những đầu trang tùy chọn này.

- Accept: application/json (mặc định) hay text/plain. Văn bản thường trình bày cùng một lĩnh vực trong một bố trí có thể đọc được, được in lề.
- X-Respond-With: markdown. Hãy để lại chỗ trống cho những cánh đồng nguyên thủy. Markdown hoạt động với định dạng trả lời.

Markdown có sẵn cho các yêu cầu thời gian thực và kết quả hoàn tất.

Các trường bên dưới mô tả giá trị mặc định JSON Trả lời đi.

[Ví dụ định dạng đáp ứng yêu cầu](https://flashdata.dev/vi/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Kiến thức cơ bản về API

Các yêu cầu xây dựng và ví dụ trên sử dụng các tham số của nguồn này. Sử dụng Python và cURL Những ví dụ bên dưới để được chia sẻ sự phục tùng, địa vị và kết quả là bước. A Batch Cơ thể là một JSON Đối tượng chứa các đồ thị; mỗi món đồ trả lại công việc của chính mình ID.

- [Async yêu cầu và biên lai](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Kiểm tra tình trạng công việc](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Lấy kết quả hoàn tất](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON yêu cầu](https://flashdata.dev/vi/docs/reference/batch-and-bulk/reference.md#batch)
- [API xử lý Bulk](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md)
- [Xây dựng a Bulk dòng làm việc cho nguồn này](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md?source=youtube_captions#playground)
- [Trình khách OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Thông báo đầy đủ

- [Nhận và kiểm tra hoàn tất kết nối web](https://flashdata.dev/vi/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Khắc phục sự cố

- [Lỗi và mã trạng thái](https://flashdata.dev/vi/docs/errors/reference.md#status-codes)
- [Khi nào cần thử lại](https://flashdata.dev/vi/docs/errors/reference.md#retries)

## API liên quan

- [YouTube Transcript API](https://flashdata.dev/vi/docs/sources/youtube_transcript/reference.md)
- [YouTube Siêu dữ liệu ảnh động API](https://flashdata.dev/vi/docs/sources/youtube_metadata/reference.md)
