Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Guias

YouTube Melhores práticas de dados

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 tarefaFonteDecisão
Encontre vídeos sobre um tópicoyoutube_searchComece com cinco candidatos, então selecione por relevância.
Inspecione um vídeo conhecidoyoutube_metadataObter título, canal, duração e legendas.
Resuma ou cite o que foi ditoyoutube_transcript / youtube_captionsEscolha uma língua e uma faixa automática ou manual.
Verifique os uploads de canais recentesyoutube_channelCompare 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.

Instalar
python -m pip install requests

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.

Defina a chave
# 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

Salve 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
# 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.

discover-request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
Envie uma vez com query.py
python query.py discover-request.json search.json

Selecione 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
# 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))
Leia a busca salva
python candidates.py

Expanda 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.

extended-request.json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
Corra uma vez
python query.py extended-request.json extended.json

Recupere 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.

metadata-request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
Envie uma vez com query.py
python query.py metadata-request.json metadata.json

Inspecione 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.

AjustandoUse-o para
languageUm código de transcriptLanguages, como en ou zh-Hans. Esta lista não distingue faixas manuais e automáticas.
auto: trueUma faixa gerada automaticamente existente.
auto: falseUma pista existente, fornecida manualmente. Não há recuo entre os dois tipos de pista.
Leia metadata.json. Sem dúvida
python -m json.tool metadata.json

Escolha 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.

captions-request.json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
Envie uma vez com query.py
python query.py captions-request.json captions.json

Mantenha 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.

cite-segments.py
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)
Leia legendas salvas sem chamada API
python cite-segments.py

Processe 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.

channel-request.json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
Envie uma vez com query.py
python query.py channel-request.json channel.json

Mantenha 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
# 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))
Plano → processo → compromisso
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit

Comece 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.

Próxima verificação. Escolha um novo nome
python query.py channel-request.json channel-next.json
Após confirmar o status é feito
python -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.

suggestions-request.json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
Envie uma vez com query.py
python query.py suggestions-request.json suggestions.json

Guarde 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.

license-request.json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
Envie uma vez com query.py
python query.py license-request.json license.json

Pressionado o trabalho para aplicativos e agentes

RegraImplementação
Selecione antes de enriquecerPara 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 realMetadados: 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 desaparecidasNã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 fracassadoPoupe o uso com respostas bem sucedidas. Em 429, homenagear Retry-After, após uma submissão incerta, verifique History antes de outra consulta paga.