Перейти к содержимому
RU
Ключ API
Обзор документации

Примеры

YouTube Search API: руководство по Python

Ищите видео на YouTube по ключевым словам, применяйте фильтры и экспортируйте CSV, JSONL и ID видео без дубликатов с помощью Python.

На этой странице

Поиск на YouTube с Python

Python SDK
python -m pip install -U flashdata
search.py
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"])

Реальный ответ поиска

Это первые три из 20 результатов публичной демонстрации по запросу «battery recycling process» от 15 ноября 2026 года. В записи сохранено шесть полей на видео. Для актуальных результатов запустите живую демонстрацию.

results[0].results · 3 / 20
[
  {
    "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
  }
]

Объединение нескольких поисков в набор данных

Набор инструментов Python сохраняет завершённые ответы, удаляет дубликаты ID и сохраняет каждый запрос и позицию совпадения. Продолжите с теми же параметрами и resume=True, чтобы использовать уже выполненные поиски.

Python toolkit
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
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

Обычный или расширенный поиск?

Обычный поиск принимает 1–20 результатов на запрос. Расширенный — 1–700 по отдельному тарифу. По умолчанию в обоих случаях 20; max_results — предел, а не гарантированное число результатов.

Фильтруйте по длительности, дате загрузки, порядку сортировки и субтитрам. Эти эндпоинты не предоставляют номер страницы или токен продолжения. Для большего числа результатов используйте расширенный поиск.

Больше результатов с расширенным поиском
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")

Узкий поиск, когда это необходимо

filters
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",
        },
    )

Выберите, что обогатить дальше

Используйте video-ids.txt для получения метаданных, транскриптов или массового скачивания. Проверьте найденные видео перед выбором ID для обогащения или доставки.

Ваша следующая задачаИспользуйте выбранный IDs для
Проверьте детали видеоПолучите метаданные для выбранного ID. Проверяйте transcriptLanguages, прежде чем запрашивать определенный трек подписи.
Обобщение разговорного контентаПрочитайте доступный транскрипт или трек подписи и процитируйте временные метки. Не суммируйте видео только из его описания поиска.
Обогатить несколько видеоИспользуйте selected-video-ids.txt в качестве входа в руководство по обогащению. Метаданные и подписи являются отдельными запросами с их собственными разрешениями и сборами.

Полный пример REST с сохранением ответов

При желании используйте requests или cURL напрямую. Сохраните request.json рядом со скриптом. Укажите API-ключ в переменной key в Python; Bash читает FLASHDATA_API_KEY или запрашивает ключ. Каждая новая папка вывода отправляет один поиск.

Запустите с помощью Search-001 в качестве выходной папки. Новая папка отправляет один оплачиваемый поиск; существующая папка читается локально. Сценарий содержит точный запрос, ответ и использование.

youtube-search/request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video"
    }
  }
}
Установка в среде Python
python -m pip install requests
youtube-search/search.py
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")
Скачать youtube-search
python search.py search-001

Если поиск требует внимания

Что случилось?Что делать
Меньше пяти видео или ни одногоЭто может быть успешным поиском. totalResults описывает этот ответ, а не общее количество соответствующих видео YouTube.
401 / 403 / 402Проверьте ключ, разрешение youtube_search и баланс, соответственно. Исправьте причину, прежде чем создавать новую попытку.
429При HTTP 429 соблюдайте Retry-After. Инструмент повторяет только явные ответы 429, по умолчанию не более двух раз, и останавливается при ожидании свыше 60 секунд. Прямые примеры SDK и REST не повторяют запросы автоматически.
Тайм-аут, 5xx или неполная папкаСохраните файлы и проверьте историю консоли перед повторной отправкой. Инструмент не отправляет автоматически запросы с неизвестным результатом.