> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube API

> Pesquise no YouTube e leia vídeos, comentários, canais, envios de canais e transcrições em JSON, com visualizações, curtidas, horários de publicação, capítulos e texto das legendas.

Leia dados públicos do YouTube em JSON pela API de tarefas assíncronas. Envie `taskType` `SOCIAL` com `platform` `youtube` e escolha o que ler com `action`. Cada requisição concluída custa **0.5 crédito**.

## Requisição

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "SOCIAL", "payload": { "platform": "youtube", "action": "search", "query": "wireless earbuds review", "limit": 10 } }'
```

Envie a tarefa e depois consulte `GET /v1/async/task/{id}` ou receba o webhook. Veja [Tarefas assíncronas](https://docs.querying.ai/pt/concepts/async-tasks.md).

## Ações

| `action` | O que lê | Obrigatório |
| - | - | - |
| `search` (padrão) | Resultados de pesquisa do YouTube | `query` |
| `recent` | Os envios mais recentes para uma consulta, do mais novo ao mais antigo | `query` |
| `video` | A página de exibição de um vídeo | `videoId` |
| `comments` | Os comentários de um vídeo e suas respostas | `videoId` |
| `channel` | Os dados e links de um canal | `channel` |
| `channel_videos` | Os vídeos, Shorts ou transmissões ao vivo de um canal | `channel` |
| `transcript` | As legendas de um vídeo | `videoId` |

`videoId` aceita um ID de vídeo ou um URL de vídeo do YouTube (exibição, `youtu.be`, Shorts ou incorporado). `channel` aceita um ID de canal (`UC...`), um `@handle` ou um URL de canal.

## Parâmetros

`search` e `recent`:

* `query`: Obrigatório. A consulta de pesquisa.
* `limit`: Inteiro opcional de 1 a 50, com padrão 10.
* `type`: `video` (padrão), `all`, `shorts`, `channel`, `playlist` ou `movie`.
* `order`: `relevance` (padrão), `viewCount`, `date` ou `rating`. `date` lista os envios do mais novo ao mais antigo, como `recent`. `rating` ordena por curtidas os resultados mais vistos do YouTube. Pesquisas de `channel` e `playlist` aceitam `relevance` ou `viewCount`.
* `publishedAfter`: Um horário ISO 8601, como `2026-11-01T00:00:00Z`. Retorna os vídeos publicados depois dele.
* `videoDuration`: `short` (menos de 3 minutos), `medium` (de 3 a 20 minutos) ou `long` (mais de 20 minutos).
* `features`: Qualquer um de `live`, `4k`, `hd`, `subtitles`, `creative_commons`, `360`, `vr180`, `3d`, `hdr`, `location` e `purchased`, como array ou como string separada por vírgulas.
* `exactSpelling`: `true` pesquisa a consulta como foi escrita, sem a correção ortográfica do YouTube.
* `pageToken`: O `nextPageToken` da página anterior. Pesquisas de vídeos ordenadas por `relevance` ou `viewCount` sem `publishedAfter` retornam um, e cada página pula todos os vídeos que as páginas anteriores retornaram.
* `regionCode` e `languageCode`: A região do YouTube (`US`, `KR`, `JP`) e o idioma da interface (`en`, `ko`, `ja`) da pesquisa.

`comments`:

* `limit`: Inteiro opcional de 1 a 500, com padrão 100. As respostas contam para o limite.
* `order`: `relevance` (padrão, os principais comentários do YouTube) ou `time` (os mais novos primeiro).
* `includeReplies`: Opcional, com padrão `true`.

`channel_videos`:

* `tab`: `videos` (padrão), `shorts` ou `streams`.
* `sort`: `latest` (padrão), `popular` ou `oldest`.
* `limit`: Inteiro opcional de 1 a 50, com padrão 20.

`transcript`:

* `languages`: Idiomas de legenda em ordem de preferência, como `["en", "ko"]`. Sem ele, são lidas as legendas padrão do vídeo, depois as em inglês e depois a primeira faixa.
* `isGenerated`: `true` lê só legendas automáticas, e `false`, só as legendas de quem enviou o vídeo.
* `trackName`: O nome da faixa de legendas a ler.
* `translateTo`: Um código de idioma. O YouTube traduz as legendas para ele.
* `maxSegments`: Inteiro opcional de 1 a 5.000, com padrão 2.000.

## Exemplo de resposta

```json theme={"theme":"css-variables"}
{
  "platform": "youtube",
  "action": "search",
  "query": "wireless earbuds review",
  "order": "relevance",
  "totalResults": 4523475,
  "returnedCount": 1,
  "videos": [
    {
      "position": 1,
      "videoId": "YdJh6QdOGME",
      "url": "https://www.youtube.com/watch?v=YdJh6QdOGME",
      "title": "Earbuds Awards 2026 - Best Bluetooth Earbuds by Category!",
      "channelId": "UCZZ4ivUawsXRktLKej8d6Xw",
      "channelTitle": "Mike O'Brien",
      "channelHandle": "@MikeOBrienMedia",
      "channelIsVerified": true,
      "publishedAt": "2026-11-17T15:39:37Z",
      "publishedTimeText": "21 hours ago",
      "duration": "PT16M35S",
      "durationSeconds": 995,
      "viewCount": 62618,
      "likeCount": 957,
      "category": "Science & Technology",
      "badges": ["New"],
      "thumbnails": { "high": "https://i.ytimg.com/vi/YdJh6QdOGME/hqdefault.jpg" }
    }
  ],
  "nextPageToken": "eyJyIjpbIllkSmg2UWRPR01FIl19"
}
```

## Campos do resultado

* Toda resposta repete `platform` e `action`. As listas trazem `returnedCount`.
* `search` e `recent` retornam `videos`. Cada vídeo tem `position`, `videoId`, `url`, `title`, `description`, os campos do canal `channelId`, `channelTitle`, `channelHandle`, `channelUrl`, `channelThumbnail` e `channelIsVerified`, `publishedAt`, `publishedTimeText`, `duration` (ISO 8601), `durationSeconds`, `viewCount`, `likeCount`, `category`, `thumbnails`, `richThumbnail` (a prévia animada), `badges` e `isFamilySafe`. Um filme acrescenta `movie` com pôster, gênero, ano, elenco e diretor.
* Uma pesquisa também retorna os `channels`, `playlists`, `shorts` e `shelves` que a página de resultados mostra, `totalResults` (a estimativa do YouTube) e `didYouMean` ou `showingResultsFor` quando o YouTube corrige a consulta.
* `video` acrescenta `tags`, `commentCount`, `subscriberCount`, `hasCaptions`, `chapters`, `mostReplayed`, `music`, `descriptionLinks` e `relatedVideos`. Os capítulos de quem enviou vêm primeiro, e os capítulos automáticos trazem `autoGenerated: true`.
* `comments` retorna `comments`, cada um com `commentId`, `parentId` (`null` em um comentário de nível superior), `text`, `authorDisplayName`, `authorChannelId`, `authorProfileImageUrl`, `authorIsVerified`, `authorIsChannelOwner`, `isPinned`, `isHearted`, `likeCount`, `replyCount`, `publishedAt` e `updatedAt`. `totalCount` é a contagem que o YouTube mostra, e `topLevelCount` e `replyCount` dividem `returnedCount`.
* `channel` retorna `channelId`, `title`, `handle`, `description`, `country`, `publishedAt`, `subscriberCount`, `videoCount`, `viewCount`, `isVerified`, `keywords`, `links`, `thumbnails`, `bannerUrl`, `rssUrl` e `uploadsPlaylistId`.
* `channel_videos` retorna `videos` na ordem de `sort`, com o `channelId` e o `channelTitle` do canal.
* `transcript` retorna o `text` da legenda, os `segments` com tempos (`start` e `duration` em segundos), o `language` lido e os `availableLanguages`. `truncated: true` marca uma transcrição cortada em `maxSegments`.
* Um vídeo com curtidas ocultas traz `likesHidden: true`, e um com comentários desativados traz `commentsDisabled: true`. Um vídeo só para membros traz `membersOnly: true` e não tem `viewCount`.
* Um vídeo, canal ou faixa de legendas que não existe, ou que exige um espectador conectado, como um vídeo com restrição de idade, encerra a tarefa com `PAGE_UNAVAILABLE`. Parâmetros que não combinam entre si a encerram com `BAD_PAYLOAD`. Só as requisições concluídas são cobradas.

## Relacionado

* [Instagram](https://docs.querying.ai/pt/engines/instagram.md)
* [Threads](https://docs.querying.ai/pt/engines/threads.md)
* [Visão geral dos motores](https://docs.querying.ai/pt/engines/overview.md)
* [Créditos e limites](https://docs.querying.ai/pt/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.