> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/api-reference/pt-br/scrapers-dedicados/scrapers-de-midia.md).

# Scrapers de mídia

Referência para endpoints dedicados de scraper de mídia da Web API, parâmetros e modos de entrega de cada endpoint.

<table><thead><tr><th width="110">Raspador</th><th>Endpoints</th></tr></thead><tbody><tr><td><a href="#general">Geral</a></td><td><code>/media</code></td></tr><tr><td><a href="#youtube">YouTube</a></td><td><code>/media/youtube/metadata</code>, <code>/media/youtube/subtitles</code>, <code>/media/youtube/download</code>, <code>/media/youtube/channel</code>, <code>/media/youtube/search</code>, <code>/media/youtube/search/max</code>, <code>/media/youtube/autocomplete</code>, <code>/media/youtube/video/trainability</code></td></tr></tbody></table>

{% hint style="info" %}
Vídeos que não podem ser baixados falham com um código de erro específico de mídia (`11201`–`11304`). Veja [Códigos de erro de mídia](/api-reference/pt-br/erros-e-codigos-de-status.md#media-specific-errors).
{% endhint %}

{% hint style="info" %}
URLs de armazenamento são validadas quanto a `s3`, `s3_gzip`, `s3_compatible`, e `tos`. Um valor inválido retorna `400` antes que a solicitação seja criada.
{% endhint %}

### Geral

#### `POST /v1/async/scrape/media`

Baixa um vídeo de uma URL (TikTok, BiliBili etc.) e o envia para seu bucket de armazenamento. Duração máxima do vídeo – `12` horas. Tempo máximo de download – `1` hora.

**Modos:** `assíncrono`, `lote`

<table><thead><tr><th width="142">Nome</th><th width="80.5">Tipo</th><th width="84.5">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>sim</td><td>URL do vídeo.<br>TikTok: <code>tiktok.com/@{user}/video/{id}</code>, <code>tiktok.com/embed/{id}</code>, <code>vm.tiktok.com/{id}</code>, <code>vt.tiktok.com/{id}</code>.<br>BiliBili: <code>bilibili.com/video/{id}</code>, <code>bilibili.com/bangumi/play/{id}</code>.<br><code>http://</code>, <code>https://</code>, <code>www.</code> prefixos e strings de consulta são aceitos</td></tr><tr><td><code>storage</code></td><td>object</td><td>sim</td><td>Entrega o resultado em um bucket de armazenamento: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr><tr><td><code>video_quality</code></td><td>string</td><td>não</td><td><code>best</code>, <code>worst</code>, ou uma resolução: <code>144</code>, <code>360</code>, <code>480</code>, <code>720</code>, <code>1080</code>, <code>1440</code>, <code>2160</code> (4K), <code>4320</code> (8K).<br>Padrão: TikTok – <code>720</code>, BiliBili – <code>480</code>.</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>URL de webhook para o trabalho concluído. URLs malformadas são rejeitadas com <code>400</code></td></tr></tbody></table>

### YouTube

#### **`POST /v1/scrape/media/youtube/metadata`**

Retorna o título, canal, descrição, duração, contagens de visualizações, curtidas e comentários do vídeo, data de envio, categorias, tags, capítulos, miniaturas e idiomas de legendas disponíveis.

**Modos:** `sync`, `assíncrono`, `lote`

<table><thead><tr><th width="131">Nome</th><th width="89">Tipo</th><th width="83">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>ID do vídeo, por exemplo <code>tIgIF5lve8U</code>. Não é uma URL. Em lote, um array de IDs</td></tr><tr><td><code>output</code></td><td>array de strings</td><td>não</td><td><code>["json"]</code> (padrão) retorna os metadados analisados. <code>["json", "html"]</code> também retorna o código-fonte da página</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

Um vídeo excluído, privado ou restrito retorna `state: "done"` com resultados vazios `resultados`. O motivo está em `results[0].metadata.statuses.video_download`, por exemplo `11202` (indisponível) ou `11206` (restrito por idade).

#### **`POST /v1/scrape/media/youtube/subtitles`**

Retorna as faixas de legendas de um vídeo com texto e tempos, agrupadas por origem e idioma.

**Modos:** `sync`, `assíncrono`, `lote`

<table><thead><tr><th width="155">Nome</th><th width="84">Tipo</th><th width="82">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>ID do vídeo, por exemplo <code>c4P_YuNnZ7U</code>. Não é uma URL. Em lote, um array de IDs</td></tr><tr><td><code>language_code</code></td><td>string</td><td>não</td><td>Idioma das legendas, por exemplo <code>en</code>. Em minúsculas; códigos desconhecidos são rejeitados com <code>400</code>. Omitir para obter todos os idiomas</td></tr><tr><td><code>subtitle_origin</code></td><td>string</td><td>não</td><td><code>uploader_provided</code> ou <code>auto_generated</code>. Omitir para obter ambos</td></tr><tr><td><code>json</code></td><td>object</td><td>não</td><td>Extração personalizada: <code>{"prompt": string}</code> ou <code>{"schema": object}</code>, nunca ambos. Sem isso, as faixas de legendas são retornadas como o YouTube as disponibiliza</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

Um valor válido `language_code` sem faixa correspondente retorna um resultado vazio (`{}`), não um erro.

#### **`POST /v1/async/scrape/media/youtube/download`**

Baixa um vídeo, seu áudio ou um trecho de ambos para seu armazenamento em nuvem.

**Modos:** `sync`, `assíncrono`

<table><thead><tr><th width="150">Nome</th><th width="87">Tipo</th><th width="83">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>ID do vídeo, por exemplo <code>9cQBNYsCqQs</code>. Não é uma URL. Em lote, um array de IDs</td></tr><tr><td><code>storage</code></td><td>object</td><td>sim</td><td><code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>gcs</code>, <code>s3_compatible</code> ou <code>tos</code>. <code>url</code> é o bucket e a pasta, por exemplo <code>bucket-name/folder/</code>; a API nomeia o arquivo</td></tr><tr><td><code>output</code></td><td>array de strings</td><td>não</td><td>Um de <code>["audio_video"]</code> (padrão), <code>["audio"]</code> ou <code>["video"]</code></td></tr><tr><td><code>video_quality</code></td><td>string</td><td>não</td><td><code>best</code>, <code>worst</code>, <code>144</code>, <code>360</code>, <code>480</code>, <code>720</code>, <code>1080</code>, <code>1440</code>, <code>2160</code> ou <code>4320</code>. Padrão <code>720</code>; se 720p não estiver disponível, a melhor qualidade abaixo dele</td></tr><tr><td><code>audio_language</code></td><td>string</td><td>não</td><td><code>default</code> (padrão) ou <code>original</code>, a faixa de áudio original do vídeo quando ele tiver dublagens</td></tr><tr><td><code>start_at</code></td><td>string</td><td>não</td><td>Início de um trecho, como <code>hh:mm:ss</code>, por exemplo <code>00:01:30</code>. Omita para começar do início</td></tr><tr><td><code>end_at</code></td><td>string</td><td>não</td><td>Fim de um trecho, como <code>hh:mm:ss</code>, por exemplo <code>00:05:45</code>. Deve ser posterior a <code>start_at</code></td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>URL de webhook para a qual o trabalho concluído é enviado</td></tr></tbody></table>

O trabalho concluído retorna o nome do arquivo em `results[0].filename`. Um vídeo com restrição de idade retorna `state: "done"` sem arquivo e status `11206` em `results[0].metadata.statuses.video_download`.

#### **`POST /v1/scrape/media/youtube/channel`**

Retorna os detalhes de um canal (nome, ID, contagens de inscritos, vídeos e visualizações, país, data de entrada, links) e seus vídeos mais recentes.

**Modos:** `sync`, `assíncrono`

<table><thead><tr><th width="135">Nome</th><th width="87">Tipo</th><th width="84">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>Handle do canal, por exemplo <code>@Oxylabs</code> (o <code>@</code> é opcional). IDs de canal (<code>UC…</code>) não são suportados</td></tr><tr><td><code>limit</code></td><td>inteiro</td><td>não</td><td>Número de vídeos a retornar. O padrão <code>20</code>; <code>0</code> retorna apenas os detalhes do canal</td></tr><tr><td><code>output</code></td><td>array de strings</td><td>não</td><td><code>["json"]</code> retorna os dados do canal analisados. <code>["html"]</code> (padrão) retorna o código-fonte da página. Use <code>json</code>: <code>["markdown"]</code> retorna pouco mais do que o rodapé da página</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/search`**

Retorna até 20 resultados de pesquisa do YouTube.

**Modos:** `sync`, `assíncrono`

<table><thead><tr><th width="168">Nome</th><th width="96">Tipo</th><th width="87">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>Frase de busca</td></tr><tr><td><code>upload_date</code></td><td>string</td><td>não</td><td><code>last_hour</code>, <code>today</code>, <code>this_week</code>, <code>this_month</code> ou <code>this_year</code></td></tr><tr><td><code>type</code></td><td>string</td><td>não</td><td><code>video</code>, <code>channel</code>, <code>playlist</code> ou <code>movie</code></td></tr><tr><td><code>duration</code></td><td>string</td><td>não</td><td><code>&#x3C;4</code> (menos de 4 minutos), <code>4-20</code> (de 4 a 20 minutos) ou <code>>20</code> (mais de 20 minutos)</td></tr><tr><td><code>sort_by</code></td><td>string</td><td>não</td><td><code>relevance</code> (padrão), <code>upload_date</code>, <code>view_count</code> ou <code>rating</code></td></tr><tr><td><code>360</code></td><td>booleano</td><td>não</td><td>Apenas vídeos 360°</td></tr><tr><td><code>3d</code></td><td>booleano</td><td>não</td><td>Apenas vídeos 3D</td></tr><tr><td><code>4k</code></td><td>booleano</td><td>não</td><td>Apenas vídeos 4K</td></tr><tr><td><code>creative_commons</code></td><td>booleano</td><td>não</td><td>Apenas vídeos licenciados sob Creative Commons</td></tr><tr><td><code>hd</code></td><td>booleano</td><td>não</td><td>Apenas vídeos em HD</td></tr><tr><td><code>hdr</code></td><td>booleano</td><td>não</td><td>Apenas vídeos HDR</td></tr><tr><td><code>live</code></td><td>booleano</td><td>não</td><td>Apenas transmissões ao vivo</td></tr><tr><td><code>location_tag</code></td><td>booleano</td><td>não</td><td>Apenas vídeos que possuem uma tag de localização. Retorna uma lista vazia quando nenhum corresponder</td></tr><tr><td><code>purchased</code></td><td>booleano</td><td>não</td><td>Apenas conteúdo comprado</td></tr><tr><td><code>subtitles</code></td><td>booleano</td><td>não</td><td>Apenas vídeos com legendas ou legendas ocultas</td></tr><tr><td><code>vr180</code></td><td>booleano</td><td>não</td><td>Apenas vídeos VR180</td></tr><tr><td><code>localização</code></td><td>string</td><td>não</td><td>País para obter resultados, como um código ISO de duas letras, por exemplo <code>IN</code></td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/search/max`**

Retorna até 700 resultados de pesquisa com os mesmos parâmetros de `/search`, com custo e latência mais altos.

**Modos:** `sync`, `assíncrono`

<table><thead><tr><th width="166">Nome</th><th width="96">Tipo</th><th width="90">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>Frase de busca</td></tr><tr><td><code>upload_date</code></td><td>string</td><td>não</td><td><code>last_hour</code>, <code>today</code>, <code>this_week</code>, <code>this_month</code> ou <code>this_year</code></td></tr><tr><td><code>type</code></td><td>string</td><td>não</td><td><code>video</code>, <code>channel</code>, <code>playlist</code> ou <code>movie</code></td></tr><tr><td><code>duration</code></td><td>string</td><td>não</td><td><code>&#x3C;4</code> (menos de 4 minutos), <code>4-20</code> (de 4 a 20 minutos) ou <code>>20</code> (mais de 20 minutos)</td></tr><tr><td><code>sort_by</code></td><td>string</td><td>não</td><td><code>relevance</code> (padrão), <code>upload_date</code>, <code>view_count</code> ou <code>rating</code></td></tr><tr><td><code>360</code></td><td>booleano</td><td>não</td><td>Apenas vídeos 360°</td></tr><tr><td><code>3d</code></td><td>booleano</td><td>não</td><td>Apenas vídeos 3D</td></tr><tr><td><code>4k</code></td><td>booleano</td><td>não</td><td>Apenas vídeos 4K</td></tr><tr><td><code>creative_commons</code></td><td>booleano</td><td>não</td><td>Apenas vídeos licenciados sob Creative Commons</td></tr><tr><td><code>hd</code></td><td>booleano</td><td>não</td><td>Apenas vídeos em HD</td></tr><tr><td><code>hdr</code></td><td>booleano</td><td>não</td><td>Apenas vídeos HDR</td></tr><tr><td><code>live</code></td><td>booleano</td><td>não</td><td>Apenas transmissões ao vivo</td></tr><tr><td><code>location_tag</code></td><td>booleano</td><td>não</td><td>Apenas vídeos que possuem uma tag de localização. Retorna uma lista vazia quando nenhum corresponder</td></tr><tr><td><code>purchased</code></td><td>booleano</td><td>não</td><td>Apenas conteúdo comprado</td></tr><tr><td><code>subtitles</code></td><td>booleano</td><td>não</td><td>Apenas vídeos com legendas ou legendas ocultas</td></tr><tr><td><code>vr180</code></td><td>booleano</td><td>não</td><td>Apenas vídeos VR180</td></tr><tr><td><code>localização</code></td><td>string</td><td>não</td><td>País para obter resultados, como um código ISO de duas letras, por exemplo <code>IN</code></td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/autocomplete`**

Retorna as sugestões de pesquisa do YouTube para uma frase parcial.

**Modos:** `sync`, `assíncrono`

<table><thead><tr><th width="135">Nome</th><th width="84">Tipo</th><th width="89">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>Frase parcial para completar, por exemplo <code>como fazer</code></td></tr><tr><td><code>location_tag</code></td><td>string</td><td>não</td><td>País para o qual as sugestões são destinadas, como um código de duas letras em minúsculas, por exemplo <code>de</code></td></tr><tr><td><code>language</code></td><td>string</td><td>não</td><td>Idioma das sugestões, por exemplo <code>en</code></td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/video/trainability`**

Retorna a permissão declarada de treinamento de IA do vídeo: `permitted` é `["all"]`, `["None"]`, ou uma lista das partes autorizadas a treiná-lo.

**Modos:** `sync`, `assíncrono`

<table><thead><tr><th width="135">Nome</th><th width="75">Tipo</th><th width="85">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>sim</td><td>ID do vídeo, por exemplo <code>rFNDylrjn_w</code>. Não é uma URL</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>Somente assíncrono. URL de webhook para a qual o trabalho concluído é enviado. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>type</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Somente assíncrono. <code>url</code> não é validado</td></tr></tbody></table>

O sinal é declarado pelo detentor dos direitos. Não é uma autorização legal.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/api-reference/pt-br/scrapers-dedicados/scrapers-de-midia.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.