Обзор документации
Руководства
Найдите соответствующие видео, выберите дорожки подписей и обработайте новые загрузки канала без повторения работы.
На этой странице
Начните с информации, которая у вас уже есть
Каждый источник отвечает на разные вопросы. Пропустите обнаружение для известного видео ID или ручки канала, и обогатите только видео, которые нужны вашей задаче.
| Ваша задача | Источник | Решение |
|---|---|---|
| Найти видео по теме | youtube_search | Начните с пяти кандидатов, затем выберите по релевантности. |
| Проверить известное видео | youtube_metadata | Получите название, канал, продолжительность и языки подписей. |
| Подытожить или процитировать сказанное | youtube_transcript / youtube_captions | Выберите язык и автоматический или ручной трек. |
| Проверить последние загрузки канала | youtube_channel | Сравните возвращенный IDs с обработанным IDs. |
Запустите примеры запросов
Сохраните каждый JSON, используя отображаемое имя файла. Python использует помощник query.py ниже; cURL может отправить тот же файл. Используйте ключ с необходимыми разрешениями источника и доступными кредитами. Каждая заявка представляет собой один запрос, независимо от количества возвращенных видео.
Python 3.10+. Установите запросы один раз, сохраните query.py ниже, затем используйте команду рядом с каждым запросом. Существующие выходы повторно используются; измененный вход требует нового имени файла вывода.
python -m pip install requestsBash. Замените REQUEST.json и RESULT.json именами файлов для выбранного примера. Проверяйте результат перед повторением запроса; эта команда сохраняет HTTP даже для ошибки.
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
--request POST 'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @REQUEST.json --output RESULT.json
)Установите ключ API
Повторное использование FLASHDATA_API_KEY из вашего терминала или секретного магазина. В противном случае введите ключ, используя одну скрытую подсказку ниже. Держите его в процессе выполнения этих примеров.
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKeyСохранить query.py для примеров Python
Создайте query.py в новой рабочей папке и скопируйте в нее полный код ниже. Сохраните файлы JSON и другие скрипты Python в этой папке и запустите все команды оттуда.
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests
if len(sys.argv) != 3:
raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
if json.loads(marker.read_text()) != payload:
raise SystemExit("Changed request: choose a new output filename.")
if not output.exists() or not receipt.exists():
raise SystemExit("Outcome unknown: check History before resubmitting.")
saved = json.loads(receipt.read_text())
if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
print(f"Read the saved {output}; no new query submitted.")
raise SystemExit(0)
if output.exists():
raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
headers={"X-API-Key": key}, json=payload,
timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
"retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))Найдите кандидатов, прежде чем приносить детали
Видеофильтр исключает другие типы результатов; субтитры сужают обнаружение видео с подписями. Он не выбирает язык подписи или не гарантирует нужный вам трек. Сохраните как discover-request.json.
{
"source": "youtube_search",
"query": "battery recycling process explained",
"params": {
"max_results": 5,
"filters": {
"type": "video",
"subtitles": true
}
}
}python query.py discover-request.json search.jsonВыбор по релевантности, а не первый ID
Сохраните candidates.py рядом с query.py и search.json, а затем запустите его из этой папки. Он сохраняет порядок поиска и удаляет дублированное видео IDs. Проверяйте заголовки, каналы и продолжительность, а затем скопируйте выбранный ID в следующий запрос. Пустой список - это завершенный поиск без кандидатов.
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path
data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
video_id = item.get("videoId", "")
if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
continue
seen.add(video_id)
candidates.append({"videoId": video_id, "title": item.get("title"),
"channel": item.get("channel"), "duration": item.get("duration"),
"url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))python candidates.pyРасширение только тогда, когда короткий список недостаточен
Стандартный поиск поддерживает max_results вплоть до 20. Для более широкой коллекции перейдите на youtube_search_extended, который поддерживает до 700 и имеет отдельную цену. Этот пример запрашивает 50; проверьте, полезны ли ваши первые результаты, прежде чем обогатить их все.
{
"source": "youtube_search_extended",
"query": "battery recycling process explained",
"params": {
"max_results": 50,
"filters": {
"type": "video"
}
}
}python query.py extended-request.json extended.jsonВосстанавливайте только метаданные, необходимые вашей функции
Замените образец video_id выбранным ID. Держите форматы и главы отключенными для простой видеокарты или проверки языка подписи. Включите include_chapters для схемы или include_formats при выборе медиаформата.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}python query.py metadata-request.json metadata.jsonПроверка доступных языков
Прочитайте results[0].transcriptLanguages, прежде чем выбрать подписи. Форматы, главы и языки являются полями на возвращаемом видеообъекте; запись использования принадлежит внешнему ответу.
| настройка | Используйте его для |
|---|---|
| language | Код от transcriptLanguages, например, en или zh-Hans. В этом списке не различают ручные и автоматические дорожки. |
| auto: true | Существующий автоматически сгенерированный трек. |
| auto: false | Существующая ручная дорожка. Между этими двумя типами трасс нет никаких откатов. |
python -m json.tool metadata.jsonВыберите язык и отслеживайте явно
Используйте тот же video_id, что и ваш запрос метаданных, и измените язык и авто, чтобы соответствовать выбранному треку. youtube_transcript по умолчанию на auto: true; youtube_captions по умолчанию на auto: false. Оба извлекают существующие подписи, а не речь в текст.
{
"source": "youtube_transcript",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}python query.py captions-request.json captions.jsonСохраняйте метки времени с доказательствами
Сохраните cite-segments.py рядом с captions.json и запустите его из этой папки. Используйте results[0].segments для цитирования: начало и конец - секунды. Сохраняйте languageCode и isAutoGenerated с текстом. fullText полезен для чтения, но не заменяет синхронизацию сегментов. Если выбранный трек отсутствует, запишите пробел, прежде чем решить, стоит ли другой запрос.
import json
from pathlib import Path
response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
print(segment["text"], url)python cite-segments.pyОбработка только новых видео с известного канала
Используйте ручку канала и ограниченный video_limit (1–100). results[0].videos - это возвращенный недавний список; videoCount - это метаданные канала, а не количество возвращенных элементов. Выберите лимит и расписание, которые покрывают загрузку, которую вы должны соблюдать.
{
"source": "youtube_channel",
"handle": "@TED",
"params": {
"video_limit": 10
}
}python query.py channel-request.json channel.jsonДержите очередь и контрольный пункт завершения
Сохраните channel-queue.py рядом с query.py и channel.json и запустите его из этой папки. Выполняйте без аргументов создание new-ids.json, затем обрабатывайте и сохраняйте доказательства для этих IDs. Запустите --commit только после того, как каждая очередь ID будет успешной; отказ оставляет контрольную точку неизменной. Используйте для этого примера один каталог на канал и одного сотрудника.
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path
checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
processed.update(json.loads(queue.read_text()))
temporary = checkpoint.with_suffix(".tmp")
temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
temporary.replace(checkpoint)
queue.unlink()
print("Checkpoint saved.")
elif sys.argv[1:]:
raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
raise SystemExit("Channel query did not complete.")
ids = dict.fromkeys(video.get("videoId", "") for video in
(data.get("results") or [{}])[0].get("videos", []))
new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
and value not in processed]
if queue.exists() and json.loads(queue.read_text()) != new:
raise SystemExit("Finish the existing queue before replacing it.")
queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
print(json.dumps(new, indent=2))python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commitНачните новую проверку канала намеренно
Помощник запроса повторно использует сохраненный ответ. Для следующей плановой проверки используйте новое имя файла результата, проверьте его, а затем скопируйте заполненный ответ на channel.json для шага очереди. Храните processed-ids.json между заездами. Этот недавний список не является полноканальным экспортом или потоком событий.
python query.py channel-request.json channel-next.jsonpython -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"Используйте предложения для улучшения запроса
Предложения возвращают фразы в results[0], а не видеозаписи. Выберите полезную фразу и сделайте отдельный запрос youtube_search. Установите язык и регион для аудитории, которую вы исследуете.
{
"source": "youtube_suggestions",
"query": "battery recycling",
"params": {
"language": "en",
"region": "US"
}
}python query.py suggestions-request.json suggestions.jsonХранить этикетки лицензий, не рассматривая их как разрешение
youtube_trainability возвращает лицензионную этикетку для видео. разрешено: ["all"] карты в Creative Commons; ["none"] также охватывает отсутствующие метаданные лицензии. Сохраните видео ID, источник ответа и дату поиска. Этот ярлык не предоставляет права на загрузку, повторное использование или обучение.
{
"source": "youtube_trainability",
"video_id": "FUfGcZ092b0"
}python query.py license-request.json license.jsonСвяжите работу с приложениями и агентами
| Правило | Осуществление |
|---|---|
| Выберите, прежде чем обогащать | Для тематической задачи: один поиск, один выбранный метаданные видео и один выбранный трек подписи. Выполните бюджет звонков в своем приложении и расцените каждый источник отдельно. |
| Повторное использование по фактическому входу | Метаданные: видео ID + опции. Видео ID + язык + трек. Снимки канала также требуют времени поиска или запуска ID. |
| Остановитесь на недостающих уликах | Не повторяйте пустой результат обнаружения или бесшумно переключайте дорожки подписей. Верните пробел, чтобы пользователь или рабочий процесс могли выбрать следующее действие. |
| Сохранение использования и неудачные работы | Сохранить использование с успешными ответами. На 429, почитайте Retry-After; после неопределенного представления, проверьте History перед другим платным запросом. |