Saltar para o conteúdo principal
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

Envie a tarefa e depois consulte GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas.

Ações

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

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