Explorar documentação
Referência da API
YouTube Download API
Baixe o vídeo ou áudio YouTube para o seu armazenamento na nuvem. Escolha resolução, formato e duração do clipe, e depois rastreie o trabalho assíncrono através da conclusão.
API de download de vídeos do YouTube — exemplos em Python
Monte uma requisição
O ID de 11 caracteres da URL do vídeo, não a URL completa.
Opções avançadas da mídia
Um seletor de formato sobrepõe qualidade, taxa de quadros e seleção de áudio-língua. Formato de saída e limites de clipe ainda se aplicam. A ponta do clipe deve seguir o começo, qualquer um pode ser omitido.
Destino de armazenamento
Em branco usa a data de upload UTC (YYYMMDD).
Adicione suas credenciais de armazenamento no servidor antes de executar o código. Eles precisam de permissão para carregar arquivos.
Credenciais do fornecedor e requisitos de armazenamento"Filme de finalização"
Carregamento, verificação e repetições do WebhookMarkdown aplica-se aos resultados completados. Recibos e status de trabalho mantêm seus campos originais.
https://data.flashdata.dev/v1/queriesParâmetros
Enviar source e.. video_id no nível superior. As opções de origem pertencem a params. Campos opcionais podem ser omitidos.
Corpo da requisição
sourcestring / Obrigatório- Preparar para youtube_download.
video_idstring / Obrigatório- O 11-caracter YouTube vídeo ID, como FUfGcZ092b0. Aceita letras, números, sublinhados e hífens.Exatamente 11 personagensPredefinição:
Não está prontoFormato aceito
^[A-Za-z0-9_-]{11}$ paramsobject / Obrigatório- Settings para este pedido.
callback_urlstring · nullable / Opcional- Async e apenas lote. HTTPS conclusão URL na porta 443, até caracteres 2,048. Sem credenciais de usuário ou fragmento URL. Omit, use null ou uma string vazia para nenhuma notificação. Em um lote, coloque isso em cada consulta, fora dos parâmetros.Predefinição:
Não está pronto
Vídeo e áudio
params.download_typestring / Opcional- audio_video mescla vídeo e áudio; vídeo seleciona apenas vídeo; áudio seleciona apenas áudio.1 para 11 personagensValores:
audio_video / video / audioPredefinição:"audio_video" params.video_qualitystring / Opcional- Seleção de resolução de vídeo. Omitir para downloads somente de áudio.1 para 40 personagensValores:
best / worst / <=144 / ==144 / >=144 / <=360 / ==360 / >=360 / <=480 / ==480 / >=480 / <=720 / ==720 / >=720 / <=1080 / ==1080 / >=1080 / <=1440 / ==1440 / >=1440 / <=2160 / ==2160 / >=2160 / <=4320 / ==4320 / >=4320Predefinição:"<=720" params.fpsstring / Opcional- Restrição de taxa de quadros: >=, <= ou == seguido de um valor de 1 a 240. Omitir para downloads somente de áudio.1 para 6 personagensPredefinição:
Não está prontoFormato aceito
^(?:>=|<=|==)(?:[1-9]\d?|1\d\d|2[0-3]\d|240)$ params.audio_languagestring / Opcional- Seleção de faixas de áudio. Aplica-se a audio_video e áudio.1 para 8 personagensValores:
default / originalPredefinição:"default" params.audio_qualitystring / Opcional- Bitrate só de áudio em kbps, ou melhor. As escolhas numéricas devem ser enviadas como cordas. Omitir para downloads de vídeo.1 para 10 personagensValores:
best / 320 / 256 / 192 / 128Predefinição:"best" params.output_formatstring / Opcional- Vídeo: mp4, webm ou mkv. Áudio: M4A, MP3 ou Opus.1 para 10 personagensValores:
mp4 / webm / mkv / m4a / mp3 / opusPredefinição:mp4 (video) / m4a (audio) params.yt_dlp_formatstring / Opcional- Seletor de formato avançado, de 1 a 1,024 caracteres após aparar espaço em branco. Personagens de controle são rejeitados. Sobrepõe video_quality, fps e audio_language, cujos valores são ignorados; formato de saída e recorte ainda se aplicam.1 para 1.024 personagensPredefinição:
Não está pronto params.upload_metadataboolean / Opcional- Envie um arquivo JSON ao lado do arquivo de mídia em seu armazenamento.
trueoufalsePredefinição:false
Clipping
params.start_atstring / Opcional- Clip começa em H:MM:SS ou HH:MM:SS formato, de 00:00:00 para 12:00:00. O padrão é 00:00:00 quando somente end_at é fornecido.1 para 8 personagensPredefinição:
Não está prontoFormato aceito
^\d{1,2}:[0-5]\d:[0-5]\d$ params.end_atstring / Opcional- Fim do clipe em formato HH:SS ou HH:SS, até 12:00:00. Deve ser mais tarde do que start_at.1 para 8 personagensPredefinição:
Não está prontoFormato aceito
^\d{1,2}:[0-5]\d:[0-5]\d$
Destino de armazenamento
params.storageobject / Obrigatório- Destino para arquivos de mídia completos. Só os campos de armazenamento listados são aceitos.
params.storage.storage_typestring / Obrigatório- Prestador de armazenamento: S3, s3_compatible, Oss, GCs, Azul, Cos, Bos ou Ts.
params.storage.storage_urlstring / Obrigatório- Nome de balde ou recipiente não vazio, até caracteres 1,024. Cercar o espaço branco é removido. Para s3, use um nome AWS válido sem um URL ou pasta caminho; pastas pertencem a object_prefix.
params.storage.object_prefixstring / Opcional- Prefixo de chave de objeto, 1 para caracteres 512. Cada segmento separado aceita letras ASCII, dígitos, pontos, sublinhas e hífens, segmentos vazios, e .. são rejeitados. Sem corte de chumbo. Cercando o espaço em branco e uma barra de fuga são removidas. YYYYMMDD usa a data de upload UTC, incluindo em archive/YYYYMMDD.Predefinição:
"YYYYMMDD" params.storage.access_keystring / Opcional- Chave de acesso para S3, compatível com S3, OSS, COS, BOS ou TOS, emparelhado com secret_key.
params.storage.secret_keystring / Opcional- Chave secreta para S3, compatível com S3, OSS, COS, BOS ou TOS.
params.storage.endpoint_urlstring / Opcional- Endpoint público HTTPS para armazenamento compatível com S3 ou OSS. COS, BOS e TOS derivam da região.
params.storage.regionstring / Opcional- Necessário para COS, BOS e TOS; também fornecimento para downloads compatíveis com S3 e S3. Os nomes dos COS incluem o APID.
params.storage.service_accountobject / Opcional- GCS conta de serviço: project_id, client_email e PEM private_key.
params.storage.account_namestring / Opcional- Azure nome da conta de armazenamento. Use o nome do contêiner em storage_url.
params.storage.sas_tokenstring / Opcional- Caixa Azure SAS com validade e assinatura.
Resposta
O construtor de pedidos envia downloads com Async ou Batch e requer params.storage. HTTP 200 com status: pending confirma aceitação, não entrega. Batch retorna um recibo de trabalho por vídeo ID.
Submissão usage.credits É 0. Os downloads são faturados pelo volume de mídia entregue após a entrega bem sucedida, arquivos de metadados opcionais não adicionam para baixar cargas.
Pesquisa job.status Até completed, em seguida, recuperar o resultado JSON. Leia os detalhes da mídia. results[0], incluindo o objeto carregado file_url, tamanho do arquivo e checksum.
Leia o resultado
Depois que o trabalho terminar, salve o JSON de seu link de resultados como response.json. Guarde isso como read-response.py e execute python read-response.py. Ele lê detalhes de arquivos sem baixar a mídia ou fazer outro pedido.
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = {name: result.get(name) for name in (
"file_url", "file_size", "md5", "duration", "output_format"
)}
# Use your storage credentials to access the media at file_url.
print(json.dumps(output, ensure_ascii=False, indent=2))A situação pode incluir detalhes da mídia job.result. Os fluxos de trabalho padrão do JSON usam-nos quando disponíveis e seguem o rel: results Não assuma que um resultado inline está sempre presente.
Todos os campos de resposta de submissão
| Campo | Descrição |
|---|---|
idstring | Baixe o trabalho ID. |
sourcestring | youtube_download. |
statusstring | Esperando quando o trabalho for aceito. |
created_atstring | Tempo de criação de trabalho no formato ISO 8601. |
usage.creditsnumber | 0 na submissão. Os downloads são carregados pelo volume de dados entregues após a conclusão. |
linksarray | Siga o auto-link para o status do trabalho e o link de resultados para a saída completa. |
links[].relstring | auto ou resultados. |
links[].hrefstring | URL para consultar com a mesma chave API. |
links[].methodstring | GET. |
Campos de arquivos de mídia concluídos
| Campo | Descrição |
|---|---|
results[0].file_urlstring | Localização do arquivo de mídia no seu armazenamento. |
results[0].file_sizeinteger | Tamanho do arquivo de mídia em bytes. |
results[0].downloaded_bytesinteger | bytes de mídia entregues usados para faturamento. |
results[0].md5string | verificação MD5 do arquivo de mídia. |
results[0].resolutionstring · nullable | Resolução de vídeo, ou nulo para saída somente de áudio ou altura indisponível. |
results[0].durationnumber · nullable | Duração em segundos quando disponível. |
results[0].output_formatstring | Formato de arquivo de saída. |
results[0].fpsnumber · nullable | Taxa de quadros quando disponível. |
results[0].video_codecstring · nullable | Codificador de vídeo quando disponível. |
results[0].audio_codecstring · nullable | Codec de áudio quando disponível. |
results[0].dynamic_rangestring · nullable | Alcance dinâmico de vídeo quando disponível. |
results[0].metadataobject · optional | Metadados file_url, file_size e md5 quando upload_metadata é true. Os bytes de metadados estão excluídos das acusações de download. |
Os campos acima descrevem a resposta padrão JSON. Opções de formato se aplicam ao registro de entrega, não ao arquivo de mídia. JSON, texto simples e formatos Markdown.
Async & ciclo de vida em lote
A submissão devolve um recibo, não resultados. Async cria um trabalho; lote retorna um trabalho separado em queries[] para cada consulta aceita. Rastreie e recupere cada trabalho independentemente.
Submeta-se a data.flashdata.dev; ler status de trabalho e resultados de api.flashdata.dev com o mesmo X-API-Key. Os exemplos básicos do API ligados usam Python e cURL.
1. Salve o trabalho IDs
Envie um download com Async, ou coloque vários pedidos de download dentro de uma matriz de consultas Batch. Cada entrada precisa de params.storage. Salve todos os trabalhos devolvidos ID.
2. Verifique o status
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: pesquisa com um atraso e respeitoRetry-Afterquando presente.completed: obter resultados.failed: Inspecionejob.error.Leia job.status, não o status do recibo de submissão.
Verifique o status de Python e cURL
Situação do trabalho referência API3. Recupere os resultados
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsApós a conclusão, autentique o resultado lido, e depois vá buscar o 302 de armazenamento URL sem sua chave API. Salve o JSON dentro de 24 horas de conclusão.
O JSON descreve a mídia entregue ao seu armazenamento. Acesse o arquivo de mídia.
Obter resultados · Python e cURL · Formatos de resposta
Resultado do download da referência API
Pesquisando e buscando resultados existentes não consomem créditos de consulta. Um tempo de votação não cancela o trabalho: mantenha seu ID em vez de enviar duplicado trabalho billable. Códigos de erro e comportamento de repetição.
Webhooks de conclusão
Inscreva-se por consulta
Preparar callback_url no nível superior de um pedido de assincronização, ou dentro de cada consulta em um lote, fora params. Não é necessário nenhum pedido de registro separado.
Use um HTTPS URL público no porto 443. FlashData POSTS uma notificação para cada trabalho chegando completed ou failed; O evento contém links, não o resultado em si.
Reconheça e verifique
Retorne 2xx depois de aceitar o evento. Deduplicar por delivery_id, também enviado como X-Delivery-Id. Redirecionamentos não são seguidos.
Entregas falhadas tentam novamente com retrocesso exponencial, até 8 tenta total e no máximo 24 horas após a conclusão. Continue pesquisando como um retrocesso.
As chamadas não foram assinadas. Confirme o trabalho ID, fonte e status terminal através do Endpoint de status autenticado Antes de processar a notificação. A entrega ID é para deduplicação, não prova de autenticidade.
Exemplo de eventos webhook e campos
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_download",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Campo | Descrição |
|---|---|
delivery_idstring | Identificador de entrega estável. Deduplicar notificações usando este valor; também é enviado no cabeçalho X-Delivery-Id. |
idstring | Trabalho ID. |
sourcestring | Solicitamos fonte de dados. |
statusstring | completo ou fracassado. |
linksarray | Status e links de resultados. Notificações não incluem conteúdo de resultado ou uma chave API. |
links[].relstring | auto ou resultados. |
links[].hrefstring | Gestão absoluta API URL, autentice com sua chave API. |
links[].methodstring | GET. |
Processamento de arquivos Bulk
Envie um vídeo ID por linha e crie o trabalho Bulk com fonte: youtube_download. Opções compartilhadas se aplicam a cada ID no arquivo.
Coloque o destino de armazenamento necessário em options.storage e configurações de mídia em options. O único trabalho e os downloads Batch usam params.storage.
Arquivos de mídia são entregues no seu armazenamento na nuvem. O resultado Bulk completo inclui um manifesto e partes do resultado descrevendo os downloads. Guarde o manifesto e partes dentro de 24 horas após o trabalho Bulk completo.
Bulk processamento API · Python e cURL · Batch JSON pedidos
Construir um fluxo de trabalho Bulk para esta fonte · Pausa, retoma e recupera
Destino de armazenamento
Inclua params.storage em cada pedido de download. Preparar storage_url para o seu nome de balde ou recipiente e fornecer credenciais com acesso de escrita. Mantenha credenciais de armazenamento em seu servidor.
{
"storage_type": "s3_compatible",
"storage_url": "your-media-bucket",
"object_prefix": "archive/YYYYMMDD",
"endpoint_url": "https://your-s3-endpoint.example.com",
"region": "your-provider-region",
"access_key": "<storage-access-key>",
"secret_key": "<storage-secret-key>"
}object_prefix padrão para YYYYMMDD, substituído pela data de upload UTC. Use um diretório fixo ou um modelo como archive/YYYYMMDD.
s3- Forneça access_key e secret_key com acesso de escrita. Defina a região do seu balde para a região AWS.
s3 Exemplo
{ "storage_type": "s3", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "us-east-1" } s3_compatible- Forneça access_key, secret_key e um público HTTPS endpoint_url. Defina a região como exigido pelo seu provedor; Cloudflare R2 usa auto.
s3_compatible Exemplo
{ "storage_type": "s3_compatible", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "endpoint_url": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com", "region": "auto" } azure- Forneça account_name e sas_token, um recipiente SAS com permissão de escrita (sp inclui w), recurso sr=c, expiração se, versão sv e assinatura sig. storage_url é o nome do recipiente. Não envie endpoint_url, access_key ou secret_key.
azure Exemplo
{ "storage_type": "azure", "storage_url": "your-media-container", "account_name": "yourstorageaccount", "sas_token": "sv=2023-11-03&sr=c&sp=w&se=2099-01-01T00%3A00%3A00Z&sig=YOUR_SAS_SIGNATURE" } bos- Forneça access_key, secret_key e região: BJ, su ou hkg. O ponto final é derivado da região quando omitido. Use um nome de balde sem pontos.
bos Exemplo
{ "storage_type": "bos", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "bj" } cos- Fornecimento. access_key, secret_key e uma região ap-*, como ap-hongkong. storage_url Deve incluir o sufixo APPID. Não envie endpoint_url, é derivado da região.
cos Exemplo
{ "storage_type": "cos", "storage_url": "your-media-bucket-1234567890", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "ap-hongkong" } gcs- Forneça service_account com project_id, client_email (um endereço .gserviceaccount.com), e o PEM private_key de sua conta de serviço. A conta deve ter acesso ao balde. Não envie access_key, secret_key, região ou endpoint_url.
gcs Exemplo
{ "storage_type": "gcs", "storage_url": "your-media-bucket", "service_account": { "project_id": "your-project-id", "client_email": "[email protected]", "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n" } } oss- Forneça access_key, secret_key e HTTPS público da região do balde endpoint_url.
oss Exemplo
{ "storage_type": "oss", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "endpoint_url": "https://oss-cn-hongkong.aliyuncs.com" } tos- Forneça access_key, secret_key e região com um prefixo cn-, ap-, eu- ou nós-. O ponto final é derivado da região quando omitido. Use um nome de balde sem pontos.
tos Exemplo
{ "storage_type": "tos", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "cn-beijing" }
O resultado é file_url identifica um objeto em seu armazenamento. Objetos privados exigem autorização do seu provedor de armazenamento ou um URL assinado; a chave FlashData API não concede acesso ao seu balde.
Para uma submissão completa, votação e download do fluxo de trabalho, veja Baixe o áudio YouTube para Amazon S3.
Entrega de arquivos
O trabalho é.. rel: results Endpoint padrão para um redirecionamento para resultado JSON, não um download MP4. FlashData envia a mídia real para o balde ou recipiente que você forneceu. A retenção de mídia segue a política do seu balde; o resultado do trabalho JSON expira 24 horas após a conclusão.
results[0].file_url Identifica o objeto mas não é automaticamente um público ou assinado URL. Acesse a mídia privada com seu armazenamento SDK, ou gere um URL assinado em seu próprio servidor. Não envie a chave FlashData API para seu provedor de armazenamento.
Activar upload_metadata para carregar um {video_id}_meta.json Companheiro no mesmo prefixo. Sua localização e o checksum aparecem sob results[0].metadata.
O modo de download do navegador do console está separado. Os downloads públicos do API usam seu próprio armazenamento; não incluem somente consoles. browser_delivery Configurações.
Recuperação de erros
Para falhas de upload ou armazenamento 403, verifique o provedor, balde, região, ponto final e permissão de escrita de objetos. Um inalcançável ou privado file_url Não significa que o upload falhou: verifique o objeto através do seu provedor de armazenamento.
Um vídeo removido ou indisponível não pode ser recuperado através de pesquisas. Para formatos indisponível, inspecione Formatos de metadados, relaxar restrições de qualidade ou remover o seletor avançado. Pedidos só de áudio requerem m4a, mp3 ou opus; Os pedidos de vídeo exigem mp4, webm ou mkv.
Se o resultado JSON expirou, primeiro verifique o seu balde para a mídia entregue. Resubmissão cria um novo download e pode incorrer em outra carga, não recupera o antigo resultado JSON.
Para autenticação, equilíbrio, formatação de pedidos e falhas de taxa, use a referência de erro compartilhado. Um intervalo de submissão ainda pode ter criado um trabalho, verificar o trabalho existente antes de tentar novamente.
Erros e códigos de status · Quando tentar novamente · Limites de taxa
Guia passo-a-passo: Baixe um vídeo e verifique a entrega
Preços
| Planos | Taxas de usoPor GB entregue | Assinaturas | Incluindo créditos por período de faturamento |
|---|---|---|---|
| Pague pelo uso | US$ 0,10 | Sem mensalidade | Recarregue quando precisar |
| Micro | US$ 0,08 | US$ 49,00 / Mês | 1.000 créditos (US$ 50,00 de API uso) incluído |
| Starter | US$ 0,07 | US$ 199,00 / Mês | 4.000 créditos (US$ 200,00 de API uso) incluído |
| Pro | US$ 0,06 | US$ 499,00 / Mês | 10.000 créditos (US$ 500,00 de API uso) incluído |
| Scale | US$ 0,05 | US$ 999,00 / Mês | 20.000 créditos (US$ 1.000,00 de API uso) incluído |
| Business | US$ 0,04 | US$ 1.999,00 / Mês | 40.000 créditos (US$ 2.000,00 de API uso) incluído |
Um plano por conta. Créditos compartilhados entre os três produtos. O uso coberto pelos créditos incluídos não é cobrado novamente.
Preços atuais e limites do plano