Explorar documentação
Guias
Encontre vídeos relevantes, selecione faixas de legenda e processe novos uploads de canais sem repetir o trabalho.
Nesta página
Comece com a informação que você já tem
Cada fonte responde uma pergunta diferente. Pular descoberta para um vídeo conhecido ID ou cabo de canal, e enriquecer apenas os vídeos que sua tarefa precisa.
| Sua tarefa | Fonte | Decisão |
|---|---|---|
| Encontre vídeos sobre um tópico | youtube_search | Comece com cinco candidatos, então selecione por relevância. |
| Inspecione um vídeo conhecido | youtube_metadata | Obter título, canal, duração e legendas. |
| Resuma ou cite o que foi dito | youtube_transcript / youtube_captions | Escolha uma língua e uma faixa automática ou manual. |
| Verifique os uploads de canais recentes | youtube_channel | Compare IDs retornado com seu IDs processado. |
Execute os exemplos de pedidos
Salve cada corpo JSON usando seu nome de arquivo exibido. Python usa o ajudante query.py abaixo, cURL pode enviar o mesmo arquivo. Use uma chave com as permissões de origem que você precisa e créditos disponíveis. Cada submissão é uma consulta, independentemente do número de vídeos devolvidos.
Python 3.10+. Instale pedidos uma vez, salve query.py abaixo, e use o comando ao lado de cada pedido. Saídas existentes são reutilizadas, entradas alteradas requerem um novo nome de arquivo de saída.
python -m pip install requestsBash. Substitua REQUEST.json e RESULT.json pelos nomes de arquivos para o seu exemplo escolhido. Verifique o resultado antes de repetir um pedido, este comando salva o corpo HTTP mesmo por um erro.
(
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
)Defina sua chave API
Reutilize FLASHDATA_API_KEY de seu terminal ou loja secreta. Caso contrário, digite a chave usando um alerta escondido abaixo. Mantenha-o no processo executando esses exemplos.
# 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 flashdataSecureKeySalve query.py para os exemplos Python
Crie query.py em uma nova pasta de trabalho e copie o código completo abaixo nela. Salve os arquivos JSON e outros scripts Python nesta pasta, e execute todos os comandos de lá.
# 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))Encontre candidatos antes de pegar detalhes
O filtro de vídeo exclui outros tipos de resultados; legendas restringem a descoberta a vídeos com legendas. Ele não seleciona uma linguagem de legenda ou garante a faixa que você precisa. Salve como 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.jsonSelecione por relevância, não o primeiro ID
Salve candidates.py ao lado de query.py e search.json, então execute-o a partir dessa pasta. Ele mantém a ordem de busca e remove o vídeo duplicado IDs. Inspecione títulos, canais e duração, e copie um ID selecionado para o próximo pedido. Uma lista vazia é uma busca completa sem candidatos.
# 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.pyExpanda apenas quando a lista é insuficiente
A busca padrão suporta max_results até 20. Para uma coleção mais ampla, mude para youtube_search_extended, que suporta até 700 e tem preços separados. Este exemplo pede 50, verifique se seus primeiros resultados são úteis antes de enriquecer todos eles.
{
"source": "youtube_search_extended",
"query": "battery recycling process explained",
"params": {
"max_results": 50,
"filters": {
"type": "video"
}
}
}python query.py extended-request.json extended.jsonRecupere apenas os metadados que você precisa
Substitua a amostra video_id por sua ID selecionada. Mantenha os formatos e capítulos desativados para uma simples placa de vídeo ou verificação de linguagem. Active include_chapters para um esboço, ou include_formats ao escolher um formato de mídia.
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"params": {
"include_formats": false,
"include_chapters": false
}
}python query.py metadata-request.json metadata.jsonInspecione as línguas disponíveis
Leia os resultados.0].transcriptLanguages Antes de escolher as legendas. Formatos, capítulos e idiomas são campos no objeto de vídeo retornado, o registro de uso pertence à resposta externa.
| Ajustando | Use-o para |
|---|---|
| language | Um código de transcriptLanguages, como en ou zh-Hans. Esta lista não distingue faixas manuais e automáticas. |
| auto: true | Uma faixa gerada automaticamente existente. |
| auto: false | Uma pista existente, fornecida manualmente. Não há recuo entre os dois tipos de pista. |
python -m json.tool metadata.jsonEscolha o idioma e a faixa explicitamente
Use o mesmo. video_id como seu pedido de metadados e mudança de linguagem e auto para combinar com a faixa escolhida. youtube_transcript padrão para auto: true; youtube_captions padrão para auto: false. Ambos recuperam legendas existentes, e não texto-a-texto.
{
"source": "youtube_transcript",
"video_id": "FUfGcZ092b0",
"params": {
"language": "en",
"auto": true
}
}python query.py captions-request.json captions.jsonMantenha a hora com as evidências
Salve cite-segments.py ao lado de captions.json e execute-o a partir dessa pasta. Use os resultados.0Segmentos para citações: início e fim são segundos. Preservar languageCode e... isAutoGenerated Com o texto. fullText é útil para leitura, mas não substitui o momento do segmento. Se a faixa escolhida está faltando, registre a lacuna antes de decidir se outra pergunta vale a pena.
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.pyProcesse apenas novos vídeos de um canal conhecido
Use um cabo de canal e um video_limit limitado (1–100). resultados [0].vídeos é a lista recente retornada; videoCount é metadados de canal, não o número de itens retornados. Escolha um limite e agenda que cubra os uploads que você precisa observar.
{
"source": "youtube_channel",
"handle": "@TED",
"params": {
"video_limit": 10
}
}python query.py channel-request.json channel.jsonMantenha uma fila e um ponto de controle de conclusão
Salve channel-queue.py ao lado de query.py e channel.json, e execute-o a partir dessa pasta. Corra sem argumentos para criar new-ids.json, então processe e guarde evidências para esses IDs. Corra --commit apenas depois que cada fila ID tiver sucesso, uma falha deixa o ponto de controle inalterado. Use um diretório por canal e um trabalhador para este exemplo.
# 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 --commitComece uma nova verificação de canal deliberadamente
O auxiliar de pesquisa reutiliza uma resposta salva. Para a próxima verificação agendada, use um novo nome de arquivo de resultado, inspecione-o, em seguida, copie a resposta completa para channel.json para a etapa de fila. Mantenha processed-ids.json entre as corridas. Esta lista recente não é uma exportação de canal completo ou um fluxo de eventos.
python query.py channel-request.json channel-next.jsonpython -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"Use sugestões para melhorar a consulta
Sugestões retornam frases em resultados.0- Não de vídeo. Selecione uma frase útil e faça um pedido youtube_search separado. Defina a língua e a região para o público que você está pesquisando.
{
"source": "youtube_suggestions",
"query": "battery recycling",
"params": {
"language": "en",
"region": "US"
}
}python query.py suggestions-request.json suggestions.jsonGuarde etiquetas sem tratá-las como permissão
youtube_trainability devolve uma etiqueta de licença para um vídeo permitido: mapas "all" para Creative Commons; "none" também cobre metadados de licença faltando. Mantenha o vídeo ID, fonte de resposta e data de recuperação. Este rótulo não concede direitos de download, reutilização ou treinamento.
{
"source": "youtube_trainability",
"video_id": "FUfGcZ092b0"
}python query.py license-request.json license.jsonPressionado o trabalho para aplicativos e agentes
| Regra | Implementação |
|---|---|
| Selecione antes de enriquecer | Para uma tarefa de tópico: uma busca, um metadados de vídeo selecionados e uma faixa de legenda escolhida. Forçar o orçamento de chamadas em seu aplicativo, e preço cada fonte separadamente. |
| Reutilizar pela entrada real | Metadados: vídeo ID + opções. Legendas: vídeo ID + linguagem + faixa. As fotos do canal também precisam de tempo de recuperação ou executar ID. |
| Pare com as evidências desaparecidas | Não tente de novo um resultado de descoberta vazio ou mude silenciosamente as faixas de legenda. Devolva a lacuna para que o usuário ou o fluxo de trabalho possam escolher a próxima ação. |
| Preservar o uso e o trabalho fracassado | Poupe o uso com respostas bem sucedidas. Em 429, homenagear Retry-After, após uma submissão incerta, verifique History antes de outra consulta paga. |