# YouTube Baixe as melhores práticas

Escolha a saída de mídia certa, controle o que você baixar, e transforme um trabalho completo em um arquivo privado utilizável.

Referência canônica: https://flashdata.dev/pt/docs/guides/youtube-download-guide
2026-11-04 por FlashData

<a id="choose"></a>

## Comece com o que sua tarefa precisa

| Seu objetivo | Use |
| --- | --- |
| Resumir conteúdo falado ou construir um índice de texto | Leia uma transcrição existente primeiro. Baixe áudio apenas quando seu fluxo de trabalho precisa do áudio em si, como um passo de discurso para texto separado. |
| Processo de fala ou áudio | Saída somente de áudio. Evite carregar um vídeo que sua aplicação não usa. |
| Mostre um pequeno trecho | Set start_at e end_at. |
| Reproduzir ou processar vídeo | MP4 com áudio e uma tampa de resolução adequada para sua aplicação; o exemplo usa <=720. |

- [Sumários de legendas](https://flashdata.dev/pt/docs/guides/youtube-summary/reference.md)
- [Inspecione os metadados de vídeo](https://flashdata.dev/pt/docs/guides/youtube-data-guide/reference.md#metadata)

<a id="formats"></a>

## Salve a saída que você quer

Escolha uma guia e salve todo o pedido como download-request.json. Mude video_id para sua fonte. Os comandos de submissão abaixo ler este arquivo, então escolher áudio ou um clipe muda o pedido real.

### MP4 / 720p

Um vídeo completo com áudio, com 720p.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720"
  }
}
```


### MP3

Um arquivo de áudio para ouvir ou processamento de áudio.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio",
    "output_format": "mp3"
  }
}
```


### 5 segundo clipe

Um trecho de MP4 de 00:00:05 para 00:00:10. Use horas que correspondam ao seu vídeo selecionado.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720",
    "start_at": "00:00:05",
    "end_at": "00:00:10"
  }
}
```


- [Todas as opções de formato](https://flashdata.dev/pt/docs/sources/youtube_download/reference.md#parameters)

<a id="prepare"></a>

## Verifique o acesso do proprietário e preços baseados em bytes

Use Bash e jq, além de um perfil salvo CLI ou FLASHDATA_API_KEY para HTTP. A chave precisa de permissão youtube_download. O download requer acesso do proprietário, acesso temporário não inclui. Exemplos CLI usam seu perfil padrão; adicione --profile NAME a cada comando se o seu for nomeado.

| Decisão | Aplique assim |
| --- | --- |
| Estimativa de custo | Use o creditsPerTb e bytesPerUnit com seus bytes de saída estimados. O preço do download não é uma taxa fixa por pedido. |
| Controle de escopo | Escolha áudio, um clipe ou uma tampa de resolução antes da submissão. Aplique regras de trabalho e gastos em sua inscrição. |
| Grave a carga real | Uso de leitura da entrega completa. A admissão pode ter créditos antes do upload se resolver, o saldo atual não é um limite de gastos por trabalho. |

### verificações grátis. CLI

```bash
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --json
```

- [Configuração da chave do proprietário](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md)
- [HTTP equilíbrio e preços](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md#balance)

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

## Use um destino privado para cada saída

Salve storage.json em particular com seus valores reais de destino. Mantenha-o fora do controle de fonte. Use um object_prefix distinto para cada versão video/output; reutilizar um prefixo para diferentes saídas torna os registros de aplicativos mais difíceis de reconciliar.

| Credencial | Propósito |
| --- | --- |
| FlashData chave | Envie o download e leia seu trabalho e entrega JSON. |
| Credencial de upload de armazenamento | Escreva mídia para o prefixo e balde pretendido. |
| Identidade do armazenamento de aplicativos | Leia o objeto privado ou o acesso a um usuário autorizado. |

### storage.json · S3

```json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1",
  "object_prefix": "media/video-001/mp4-720p-v1"
}
```

### Linux / macOS · arquivo privado

```bash
chmod 600 storage.json
```

- [Permissões de arquivos Windows](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md#storage)
- [Outros fornecedores de armazenamento](https://flashdata.dev/pt/docs/sources/youtube_download/reference.md#storage)

<a id="submit"></a>

## Envie o pedido salvo uma vez

Faça uma conta depois de salvar os dois arquivos. O comando injeta storage.json através de stdin e salva download-submission.json. Fique com o recibo. Com CLI, mantenha a mesma execução ID para uma repetição; use um novo ID apenas para uma nova saída intencional. Submissões HTTP não usam o diário local do CLI.

### CLI

#### Envie a saída escolhida

```bash
(
set -eu
umask 077
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async \
  --run-id download-001 --output download-submission.json
)
```


### HTTP / cURL

#### Envie a saída escolhida

```bash
(
set -eu
umask 077
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Content-Type: application/json' \
  --data-binary @- --output download-submission.json
)
```


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

<a id="dry-run"></a>

### Validar primeiro com o CLI

Espere ok: true e data.dryRun: true. Isso verifica a entrada e o acesso ao FlashData sem enviar um trabalho, não prova que as credenciais de upload podem escrever para o seu balde.

#### Livre corrida seca

```bash
(
set -eu
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async --dry-run --json
)
```


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

### Espere pelo trabalho existente

O recibo de submissão não é o arquivo da mídia. CLI espera; o comando HTTP lê status uma vez. Repita a leitura dentro do seu prazo até completar ou falhar. Um tempo limite local não cancela o trabalho do servidor.

#### CLI

##### Espere pelo trabalho salvo

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs wait "$JOB_ID"
)
```


#### HTTP / cURL

##### Leia o status uma vez

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
STATUS_URL=$(jq -er '.links[] | select(.rel == "self") | .href' download-submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
  "$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)
```



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

## Leia o registro de entrega e acesse a mídia

Depois de concluído, recupere delivery.json usando o mesmo caminho que você usou para enviar. O resultado assinado URL recupera JSON; resultados[0].file_url identifica a mídia em seu armazenamento. Um file_url privado precisa da sua identidade de leitura de armazenamento ou um link emitido pela sua aplicação.

### CLI

#### Salve delivery.json

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs result "$JOB_ID" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)
```


### HTTP / cURL

#### Traga a entrega JSON · mantenha a chave API fora dos pedidos de armazenamento.

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
jq -e '.job.status == "completed"' job.json >/dev/null
RESULTS_URL=$(jq -er '.links[] | select(.rel == "results") | .href' download-submission.json)
# Get the signed JSON URL without forwarding the API key to storage.
STORAGE_URL=$(curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
  --output /dev/null --write-out '%{redirect_url}' "$RESULTS_URL")
: "${STORAGE_URL:?No signed result URL was returned}"
curl --fail-with-body --silent --show-error --compressed --max-time 70 \
  "$STORAGE_URL" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)
```



<a id="inspect"></a>

### Verifique o que foi entregue

Espere um local de arquivo, um file_size positivo, um MD5 e uso. Registre file_size para o objeto entregue, downloaded_bytes é um campo de transferência, não um substituto para a carga final em uso.

#### Inspecione delivery.json

```bash
(
set -eu
jq -e '.source == "youtube_download" and .status == "done"
  and (.results | length == 1) and (.results[0].file_size > 0)
  and (.results[0].md5 | test("^[a-fA-F0-9]{32}$"))' delivery.json >/dev/null
jq '{file: (.results[0] | {file_url, file_size, md5, duration, output_format}), usage}' delivery.json
)
```

- [Verifique e sirva a um objeto privado](https://flashdata.dev/pt/docs/guides/media-delivery-pipeline/reference.md#verify)

<a id="verify-media"></a>

### Verifique uma cópia local de S3

Defina OBJECT_KEY para a chave de mídia entregue de file_url, incluindo seu prefixo. Use AWS CLI com acesso de leitura, jq e OpenSSL. Isso salva media.mp4 ou media.mp3 de acordo com seu pedido escolhido e verifica seu tamanho e soma de verificações sem sobrescrever um arquivo local existente.

#### S3 não tem nenhuma nova consulta FlashData

```bash
(
set -eu
# Requires AWS CLI configured for read access, jq and OpenSSL.
# Set OBJECT_KEY to the delivered media object's key from file_url.
: "${OBJECT_KEY:?Set the delivered S3 object key}"
BUCKET=$(jq -er '.storage_url' storage.json)
REGION=$(jq -er '.region' storage.json)
FORMAT=$(jq -er '.params.output_format' download-request.json)
case "$FORMAT" in mp4|mp3) ;; *) echo 'Choose a filename for this format.' >&2; exit 1 ;; esac
LOCAL_FILE="media.$FORMAT"
test ! -e "$LOCAL_FILE" || { echo 'Keep the existing local file.' >&2; exit 1; }
EXPECTED_BYTES=$(jq -er '.results[0].file_size' delivery.json)
EXPECTED_MD5=$(jq -er '.results[0].md5 | ascii_downcase' delivery.json)
aws s3 cp "s3://$BUCKET/$OBJECT_KEY" "$LOCAL_FILE" --region "$REGION" --only-show-errors
ACTUAL_BYTES=$(wc -c < "$LOCAL_FILE" | tr -d '[:space:]')
ACTUAL_MD5=$(openssl dgst -md5 "$LOCAL_FILE" | awk '{print $NF}')
test "$ACTUAL_BYTES" = "$EXPECTED_BYTES"
test "$ACTUAL_MD5" = "$EXPECTED_MD5"
echo 'Delivery verified'
)
```

- [Retenção de resultados e mídia armazenada](https://flashdata.dev/pt/docs/guides/save-results/reference.md#media)

<a id="operations"></a>

## Recupere-se do palco que falhou

| O que aconteceu? | Próxima ação |
| --- | --- |
| A submissão acabou sem nenhum trabalho confirmado ID | Inspecione o CLI salvo ou peça o histórico. Mantenha a entrada original e não se submeta automaticamente novamente. |
| Trabalho aceito, espera tempo esgotado | Leia ou recupere o mesmo trabalho. Não crie outro download para continuar esperando. |
| O carregamento falhou | Leia o erro de trabalho e conserte as configurações de destino ou escreva o acesso antes de tentar novamente. |
| A mídia leu 403 devolvido | Verifique as permissões de leitura de armazenamento ou o link emitido pela aplicação. A chave FlashData API não destrava S3. |
| Resultado assinado JSON expirado | Leia o resultado do trabalho novamente enquanto o resultado é mantido. Mídia armazenada segue o ciclo de vida do seu balde. |

### CLI · inspecione a corrida salva

```bash
flashdata runs show download-001 --json
```

- [Decisões de recuperação](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)
- [Erros e códigos de status](https://flashdata.dev/pt/docs/errors/reference.md)
- [Tarefas recorrentes](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)

<a id="agent"></a>

## Dê ao seu agente os critérios de saída e entrega

### Tarefa do agente. Forneça o vídeo, destino e orçamento.

```text
Use meu acesso ao proprietário e configure o armazenamento privado.
Leia download-request.json para o vídeo e saída, não mude-os silenciosamente.
Verifique os preços do download e os créditos disponíveis contra o orçamento aprovado.
Submeta-se uma vez, salve o run/job ID, e leia o trabalho para completar.
Guarde o registro de entrega. Verifique o tamanho do objeto armazenado e MD5 antes de processá-lo.
Reporte a localização do objeto, formato escolhido, resultado de verificação e uso real.
Se a submissão for incerta, inspecione o trabalho salvo, não crie acesso de substituição ou outro download.
Mantenha credenciais de armazenamento privadas. Compartilhe mídia apenas através dos controles de acesso configurados da aplicação.
```

- [Construa o oleoduto de aplicação](https://flashdata.dev/pt/docs/guides/media-delivery-pipeline/reference.md)
