# YouTube Search API: hướng dẫn Python

Tìm YouTube theo từ khóa, lọc video và xuất CSV, JSONL cùng ID video đã loại trùng bằng Python.

Tài liệu tham khảo chính điển: https://flashdata.dev/vi/docs/guides/youtube-search-recipe
Xem lại: 2026-11-16 by FlashData

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

## Tìm kiếm YouTube bằng Python

### Python SDK

```bash
python -m pip install -U flashdata
```

### search.py

```python
from flashdata import FlashData

with FlashData(api_key="your-flashdata-api-key") as client:
    result = client.youtube.search(
        "battery recycling process",
        max_results=5,
        filters={"type": "video"},
    )

for video in result["results"][0]["results"]:
    print(video["title"], video["videoId"])
```

- [Lấy khóa API](https://flashdata.dev/signup)
- [Thử tìm kiếm trực tiếp](https://flashdata.dev/vi/products/youtube-data#playground)

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

## Phản hồi tìm kiếm thực tế

Đây là ba kết quả đầu trong 20 kết quả của bản demo công khai cho “battery recycling process” ngày 15 tháng 11 năm 2026. Bản ghi giữ sáu trường cho mỗi video. Chạy demo trực tiếp để lấy kết quả mới.

### results[0].results · 3 / 20

```json
[
  {
    "videoId": "s2xrarUWVRQ",
    "title": "What *Really* happens to used Electric Car Batteries? - (you might be surprised)",
    "channel": "JerryRigEverything",
    "duration": 424,
    "viewCount": 5679251,
    "uploadDate": null
  },
  {
    "videoId": "RW0itbw_ALI",
    "title": "Recycling Batteries",
    "channel": "mbmmllc",
    "duration": 193,
    "viewCount": 91440,
    "uploadDate": null
  },
  {
    "videoId": "dyDoOcBMAHw",
    "title": "Why It's So Hard To Recycle Electric-Car Batteries | World Wide Waste",
    "channel": "Business Insider India",
    "duration": 376,
    "viewCount": 880172,
    "uploadDate": null
  }
]
```

- [Phản hồi tìm kiếm thực tế](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

<a id="collection"></a>

## Gộp nhiều lượt tìm kiếm thành tập dữ liệu

Bộ công cụ Python lưu phản hồi đã hoàn tất, loại ID video trùng và giữ lại từng truy vấn cùng vị trí kết quả phù hợp. Tiếp tục với cùng tùy chọn và resume=True để dùng lại các lượt tìm kiếm đã hoàn tất.

### Python toolkit

```bash
python -m pip install "https://github.com/flashdatadev/youtube-search-api/releases/download/v0.1.0/flashdata_youtube_search_api-0.1.0-py3-none-any.whl"
```

### search_to_dataset.py

```python
from flashdata_search import SearchClient, collect

with SearchClient(api_key="your-flashdata-api-key") as client:
    summary = collect(
        client,
        ["battery recycling process", "lithium battery recycling plant"],
        "output/batteries",
        max_results=20,
        filters={"duration": "4-20", "subtitles": True},
    )

print(summary["unique_videos"], "unique videos")
# output/batteries: videos.csv, videos.jsonl, video-ids.txt, summary.json
```

- [Bộ công cụ Python YouTube Search API](https://github.com/flashdatadev/youtube-search-api)

<a id="extended"></a>

## Tìm kiếm tiêu chuẩn hay mở rộng?

Tìm kiếm tiêu chuẩn chấp nhận 1–20 kết quả mỗi truy vấn. Tìm kiếm mở rộng chấp nhận 1–700 với mức phí riêng. Cả hai mặc định là 20; max_results là giới hạn, không phải số kết quả được bảo đảm.

Lọc theo thời lượng, ngày tải lên, thứ tự và phụ đề. Các endpoint này không cung cấp số trang hoặc token tiếp tục. Dùng tìm kiếm mở rộng để có thêm kết quả.

### Lấy thêm kết quả bằng tìm kiếm mở rộng

```python
from flashdata import FlashData

with FlashData(api_key="your-flashdata-api-key") as client:
    result = client.youtube.search_extended(
        "battery recycling process",
        max_results=100,
        filters={"type": "video", "duration": "4-20"},
    )

print(len(result["results"][0]["results"]), "returned results")
```

- [Khi cần sử dụng tìm kiếm mở rộng](https://flashdata.dev/vi/docs/sources/youtube_search_extended/reference.md)
- [So sánh giá tìm kiếm](https://flashdata.dev/vi/products/youtube-data#choose-api)

<a id="filters"></a>

## Thu hẹp việc tìm kiếm khi cần thiết

### filters

```python
from flashdata import FlashData

with FlashData(api_key="your-flashdata-api-key") as client:
    result = client.youtube.search(
        "battery recycling process",
        max_results=20,
        filters={
            "type": "video",
            "duration": "4-20",
            "subtitles": True,
            "sort_by": "view_count",
        },
    )
```

- [Mọi bộ lọc tìm kiếm](https://flashdata.dev/vi/docs/sources/youtube_search/reference.md#parameters)

<a id="select"></a>

## Chọn những gì cần làm giàu tiếp theo

Dùng video-ids.txt làm đầu vào cho metadata, bản chép lời hoặc tải xuống hàng loạt. Xem xét video ứng viên trước khi chọn ID cần bổ sung dữ liệu hoặc phân phối.

| Nhiệm vụ tiếp theo của bạn | Dùng IDs đã chọn cho |
| --- | --- |
| Kiểm tra chi tiết của video | Lấy siêu dữ liệu cho điều đã chọn ID. Kiểm tra transcriptLanguages trước khi yêu cầu một đoạn ghi chú cụ thể. |
| tổng hợp nội dung đã nói | Hãy đọc một bản sao hoặc phần phụ đề sẵn có và trích dẫn nhãn thời gian. Đừng chỉ tóm tắt đoạn băng trong phần tìm kiếm. |
| Làm giàu nhiều video | Dùng selected-video-ids.txt để nhập vào hướng dẫn làm giàu. Siêu dữ liệu và chú thích là những yêu cầu riêng biệt với quyền hạn và cáo buộc của riêng họ. |

- [Siêu dữ liệu của một video](https://flashdata.dev/vi/docs/guides/video-metadata-recipe/reference.md)
- [Tóm tắt một đoạn phim với lời trích dẫn](https://flashdata.dev/vi/docs/guides/youtube-summary/reference.md)
- [Enrich đã chọn phim IDs](https://flashdata.dev/vi/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

<a id="rest"></a>

## Ví dụ REST đầy đủ có lưu phản hồi

Tùy chọn: dùng trực tiếp requests hoặc cURL. Lưu request.json cạnh tập lệnh. Nhập khóa API vào biến key trong Python; Bash đọc FLASHDATA_API_KEY hoặc yêu cầu nhập khóa. Mỗi thư mục đầu ra mới gửi một lượt tìm kiếm.

Chạy với tìm kiếm-001 là thư mục xuất. Một thư mục mới đệ trình một tìm kiếm có thể thanh toán được; một thư mục đã có được đọc ở địa phương. Tập lệnh giữ yêu cầu gửi đi, đáp ứng và sử dụng chính xác.

### youtube-search/request.json

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video"
    }
  }
}
```

### Python

#### Cài đặt trong môi trường Python của bạn

```bash
python -m pip install requests
```

#### youtube-search/search.py

```python
import argparse
import json
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved search")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_search"
            or not isinstance(request.get("query"), str) or not request["query"].strip()):
        raise SystemExit("request.json must contain youtube_search and a nonempty query")
    key = "your-flashdata-api-key"
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
data = json.loads((out / "result.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_search" or data.get("status") != "done":
    raise SystemExit("Search did not finish successfully; inspect result.json")
pages = data.get("results")
if not isinstance(pages, list) or any(
    not isinstance(page, dict) or not isinstance(page.get("results"), list) for page in pages
):
    raise SystemExit("Expected results[].results arrays; inspect result.json")

videos, seen, skipped, duplicates = [], set(), 0, 0
for page in pages:
    for row in page["results"]:
        if not isinstance(row, dict):
            raise SystemExit("Expected video result objects; inspect result.json")
        video_id = row.get("videoId")
        if not isinstance(video_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
            skipped += 1
        elif video_id in seen:
            duplicates += 1
        else:
            seen.add(video_id)
            videos.append({**row, "url": "https://www.youtube.com/watch?v=" + video_id})
record = {
    "request": json.loads((out / "request.json").read_bytes()),
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "video_count": len(videos),
    "skipped_items": skipped, "duplicates_removed": duplicates, "result_file": "result.json",
}
for filename, value in (("videos.json", videos), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
(out / "video-ids.txt").write_text("".join(v["videoId"] + "\n" for v in videos), encoding="utf-8")
print(f"Saved {len(videos)} videos to {out}/videos.json and video-ids.txt")
```

#### Chạy từ bạn ống dò /

```bash
python search.py search-001
```


### Bash

#### Kiểm tra dụng cụ của bạn

```bash
curl --version
jq --version
```

#### youtube-search/search.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash search.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "youtube_search" and
    (.query | if type == "string" then test("\\S") else false end)' request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  curl --fail-with-body --silent --show-error --max-time 120 \
    --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --header 'Content-Type: application/json' --header 'Accept: application/json' \
    --data-binary "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
selection=$(jq -e '
  if .source != "youtube_search" or .status != "done" or (.results | type) != "array"
  then error("Expected a successful youtube_search response") else . end
  | [.results[] | if (.results | type) != "array"
      then error("Expected a video list") else .results[] end
      | if type != "object" then error("Expected video result objects") else . end]
  | reduce .[] as $row ({seen: {}, videos: [], skipped: 0, duplicates: 0};
      if ($row.videoId | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$") else false end) == false
      then .skipped += 1
      elif .seen[$row.videoId] then .duplicates += 1
      else .seen[$row.videoId] = true
        | .videos += [$row + {url: ("https://www.youtube.com/watch?v=" + $row.videoId)}] end)
  | del(.seen)' "$out/result.json")
printf '%s' "$selection" | jq '.videos' > "$out/videos.json"
jq -r '.[].videoId' "$out/videos.json" > "$out/video-ids.txt"
jq --slurpfile request "$out/request.json" --argjson selection "$selection" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage,
    video_count: ($selection.videos | length), skipped_items: $selection.skipped,
    duplicates_removed: $selection.duplicates, result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s videos to %s/videos.json and video-ids.txt\n' "$(jq length "$out/videos.json")" "$out"
```

#### Chạy từ bạn ống dò /

```bash
bash search.sh search-001
```



<a id="recover"></a>

## Nếu tìm kiếm cần sự chú ý

| Chuyện gì đã xảy ra | Cách xử lý |
| --- | --- |
| Ít hơn năm video, hoặc không có | Đây có thể là một cuộc tìm kiếm thành công. Chỉnh lại yêu cầu hoặc gỡ bỏ bộ lọc hạn chế. totalResults Mô tả phản ứng này, không phải tổng số khớp YouTube video. |
| 401 / 403 / 402 | Kiểm tra chìa khóa đi. youtube_search cho phép và số dư, anh bạn. Sửa chữa nguyên nhân trước khi tạo ra một nỗ lực mới. |
| 429 | Với HTTP 429, đợi theo Retry-After. Bộ công cụ chỉ thử lại phản hồi 429 rõ ràng, mặc định tối đa hai lần, và dừng nếu thời gian chờ vượt 60 giây. Ví dụ SDK trực tiếp và REST không tự thử lại. |
| Thời hạn, 5x hoặc một thư mục không đầy đủ | Giữ các tệp đã lưu và kiểm tra lịch sử trên console trước khi gửi lại. Bộ công cụ không tự gửi lại yêu cầu có kết quả chưa xác định. |

- [Yêu cầu lịch sử](https://flashdata.dev/app/jobs)
- [Lỗi và mã trạng thái](https://flashdata.dev/vi/docs/errors/reference.md)
- [Bộ công cụ Python YouTube Search API](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
