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

Referência canônica: https://flashdata.dev/pt/docs/sources/youtube_download
Revisado: 2026-10-23

Ponto final: POST https://data.flashdata.dev/v1/queries
Autenticação: X-API-Key: YOUR_API_KEY
Modos: [Async](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md)

Precisou de permissão de origem: youtube_download

Substitua YOUR_API_KEY por uma chave API que tem essa permissão de fonte e créditos disponíveis. Execute pedidos no seu servidor ou host de agente.

[Configurar autenticação](https://flashdata.dev/pt/docs/guides/headers-and-authentication/reference.md)

[Baixe um vídeo e verifique a entrega](https://flashdata.dev/pt/docs/guides/download-video-recipe/reference.md)

[API de download de vídeos do YouTube — exemplos em Python](https://github.com/flashdatadev/youtube-video-download-api)

<a id="quickstart"></a>

## Envie um pedido

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "video_quality": "<=720",
    "output_format": "mp4",
    "storage": {
      "storage_type": "s3",
      "storage_url": "your-media-bucket",
      "access_key": "YOUR_ACCESS_KEY",
      "secret_key": "YOUR_SECRET_KEY",
      "region": "us-east-1"
    }
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parâmetros

<a id="parameters-group-0"></a>

### Corpo da requisição

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Sim | — | Preparar para youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Sim | Não está pronto | O 11-caracter YouTube vídeo ID, como FUfGcZ092b0. Aceita letras, números, sublinhados e hífens. Comprimento mínimo: 11. Comprimento máximo: 11. Padrão: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Sim | — | Settings para este pedido.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Não | Não está pronto | 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.  |

<a id="parameters-group-1"></a>

### Vídeo e áudio

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | Não | "audio_video" | audio_video mescla vídeo e áudio; vídeo seleciona apenas vídeo; áudio seleciona apenas áudio. Permitido: "audio_video", "video", "audio". Comprimento mínimo: 1. Comprimento máximo: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Não | "<=720" | Seleção de resolução de vídeo. Omitir para downloads somente de áudio. Permitido: "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", ">=4320". Comprimento mínimo: 1. Comprimento máximo: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Não | Não está pronto | Restrição de taxa de quadros: >=, <= ou == seguido de um valor de 1 a 240. Omitir para downloads somente de áudio. Comprimento mínimo: 1. Comprimento máximo: 6. Padrão: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Não | "default" | Seleção de faixas de áudio. Aplica-se a audio_video e áudio. Permitido: "default", "original". Comprimento mínimo: 1. Comprimento máximo: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Não | "best" | Bitrate só de áudio em kbps, ou melhor. As escolhas numéricas devem ser enviadas como cordas. Omitir para downloads de vídeo. Permite: "best", "320", "256", "192", "128". Comprimento mínimo: 1. Comprimento máximo: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Não | mp4 (video) / m4a (audio) | Vídeo: mp4, webm ou mkv. Áudio: M4A, MP3 ou Opus. Permitido: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Comprimento mínimo: 1. Comprimento máximo: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Não | Não está pronto | 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. Comprimento mínimo: 1. Comprimento máximo: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Não | false | Envie um arquivo JSON ao lado do arquivo de mídia em seu armazenamento.  |

<a id="parameters-group-2"></a>

### Clipping

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Não | Não está pronto | 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. Comprimento mínimo: 1. Comprimento máximo: 8. Padrão: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Não | Não está pronto | Fim do clipe em formato HH:SS ou HH:SS, até 12:00:00. Deve ser mais tarde do que start_at. Comprimento mínimo: 1. Comprimento máximo: 8. Padrão: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

<a id="parameters-group-3"></a>

### Destino de armazenamento

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Sim | — | Destino para arquivos de mídia completos. Só os campos de armazenamento listados são aceitos.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Sim | — | Prestador de armazenamento: S3, s3_compatible, Oss, GCs, Azul, Cos, Bos ou Ts.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Sim | — | 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.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Não | "YYYYMMDD" | 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.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Não | — | Chave de acesso para S3, compatível com S3, OSS, COS, BOS ou TOS, emparelhado com secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Não | — | Chave secreta para S3, compatível com S3, OSS, COS, BOS ou TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Não | — | Endpoint público HTTPS para armazenamento compatível com S3 ou OSS. COS, BOS e TOS derivam da região.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Não | — | 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.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Não | — | GCS conta de serviço: project_id, client_email e PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Não | — | Azure nome da conta de armazenamento. Use o nome do contêiner em storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Não | — | Caixa Azure SAS com validade e assinatura.  |

<a id="response"></a>

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

### read-response.py

```python
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))
```

## Apresentação da amostra

Exemplo gravado; campos e conta depende da fonte e entrada solicitada.
```json
{
  "id": "job_d265c693-950e-40bf-a13e-a432044d99ba",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  },
  "created_at": "2026-09-16T07:51:13.139Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba/results",
      "method": "GET"
    }
  ]
}
```

## Campos de resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| id | string | Baixe o trabalho ID. |
| source | string | youtube_download. |
| status | string | Esperando quando o trabalho for aceito. |
| created_at | string | Tempo de criação de trabalho no formato ISO 8601. |
| usage.credits | number | 0 na submissão. Os downloads são carregados pelo volume de dados entregues após a conclusão. |
| links | array | Siga o auto-link para o status do trabalho e o link de resultados para a saída completa. |
| links[].rel | string | auto ou resultados. |
| links[].href | string | URL para consultar com a mesma chave API. |
| links[].method | string | GET. |

- Os downloads são como trabalhos de fundo. A resposta de submissão contém um trabalho ID; não contém o arquivo de mídia. Siga o status do trabalho até a conclusão, então recupere o resultado descrevendo os arquivos entregues no seu armazenamento. Envie downloads para /v1/queries ou /v1/queries/batch; /v1/queries/realtime não aceita pedidos de download.

## Formatos de resposta

Respostas usam JSON por padrão. Escolha outro formato com esses cabeçalhos opcionais.

- Accept: application/json (padrão) ou text/plain. Texto simples apresenta os mesmos campos em um layout legível e indentado.
- X-Respond-With: markdown. Deixe de lado os campos originais. Markdown funciona com qualquer formato de resposta.

Markdown formata o manifesto de download; arquivos de mídia mantêm seu formato original. Recibos e status de trabalho só suportam Accept.

Os campos abaixo descrevem a resposta padrão JSON.

[Requisito e formatação de resposta exemplos](https://flashdata.dev/pt/docs/guides/response-formats/reference.md#completed-results)

<a id="storage"></a>

## Destino de armazenamento

O único trabalho e os downloads do Batch requerem params.storage; Bulk usa options.storage, storage_url é o nome do balde ou recipiente. Forneça credenciais com acesso de escrita e mantenha-as em seu servidor.

### s3

Forneça access_key e secret_key com acesso de escrita. Defina a região do seu balde para a região AWS.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "storage_type": "gcs",
  "storage_url": "your-media-bucket",
  "service_account": {
    "project_id": "your-project-id",
    "client_email": "uploader@your-project-id.iam.gserviceaccount.com",
    "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.

```json
{
  "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.

```json
{
  "storage_type": "tos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "cn-beijing"
}
```

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Conceitos básicos da API

O construtor de pedidos e exemplos acima usam os parâmetros desta fonte. Use os exemplos Python e cURL abaixo para submissão compartilhada, status e passos de resultado. Um corpo Batch é um objeto JSON contendo consultas, cada item retorna seu próprio trabalho ID.

- [Async pedido e recibo](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Verifique o status do trabalho](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Recupere resultados completados](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON pedidos](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#batch)
- [API de processamento Bulk](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md)
- [Construir um fluxo de trabalho Bulk para esta fonte](https://flashdata.dev/pt/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Cliente OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Notificações de conclusão

- [Receba e verifique os hooks de conclusão](https://flashdata.dev/pt/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Solução de problemas

- [Erros e códigos de status](https://flashdata.dev/pt/docs/errors/reference.md#status-codes)
- [Quando tentar novamente](https://flashdata.dev/pt/docs/errors/reference.md#retries)

<a id="delivery"></a>

## Entrega de arquivos

O download não suporta em tempo real.

A mídia é enviada para seu armazenamento configurado; o resultado JSON descreve esses arquivos. A mídia privada usa sua autenticação de armazenamento. JSON resultados expiram 24 horas após a conclusão; mídia segue sua política de retenção de armazenamento.

## APIs relacionadas

- [YouTube Video Metadata API](https://flashdata.dev/pt/docs/sources/youtube_metadata/reference.md)
- [YouTube Transcript API](https://flashdata.dev/pt/docs/sources/youtube_transcript/reference.md)
