API do YouTube

A API do YouTube permite pesquisar no YouTube e recuperar metadados de vídeo por meio de uma interface unificada. Cada endpoint retorna JSON estruturado com rastreamento de uso de créditos.

Endpoints

Endpoint	Descrição
`POST /api/v1/youtube/search`	Pesquisar no YouTube com filtros (data, duração, tipo, qualidade)
`POST /api/v1/youtube/metadata`	Obter metadados estruturados de um vídeo (visualizações, curtidas, tags, descrição)

Autenticação

Cabeçalho	Valor	Obrigatório
`Authorization`	`Bearer YOUR_API_KEY`	Sim
`Content-Type`	`application/json`	Sim

Pesquisa no YouTube

Bash

POST https://api.scavio.dev/api/v1/youtube/search

Pesquise no YouTube e obtenha resultados estruturados. Suporta filtragem por data de upload, duração, tipo de resultado, qualidade do vídeo e muito mais.

Corpo da Requisição

Parâmetro	Tipo	Padrão	Descrição
`search`	`string`	--	Obrigatório. Consulta de pesquisa (1-500 caracteres).
`upload_date`	`string`	--	Filtrar por data de upload. Um de: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	Filtrar por tipo de resultado. Um de: `video`, `channel`, `playlist`
`duration`	`string`	--	Filtrar por duração do vídeo. Um de: `short` (menos de 4 min), `medium` (4-20 min), `long` (mais de 20 min)
`sort_by`	`string`	`relevance`	Ordem de classificação. Um de: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	Apenas vídeos HD
`4k`	`boolean`	`false`	Apenas vídeos 4K
`subtitles`	`boolean`	`false`	Apenas vídeos com legendas/closed caption
`creative_commons`	`boolean`	`false`	Apenas vídeos licenciados sob Creative Commons
`live`	`boolean`	`false`	Apenas transmissões ao vivo
`hdr`	`boolean`	`false`	Apenas vídeos HDR
`360`	`boolean`	`false`	Apenas vídeos em 360 graus
`3d`	`boolean`	`false`	Apenas vídeos 3D
`location`	`boolean`	`false`	Apenas vídeos com metadados de localização
`vr180`	`boolean`	`false`	Apenas vídeos VR180

Exemplo

curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "langchain tutorial",
    "type": "video",
    "duration": "medium",
    "sort_by": "view_count",
    "upload_date": "this_year"
  }'

Exemplo de Resposta

JSON

{
  "data": {
    "results": [
      {
        "videoId": "sVcwVQRHIc8",
        "title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
        "longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
        "publishedTimeText": { "simpleText": "1 year ago" },
        "lengthText": { "simpleText": "2:33:11" },
        "viewCountText": { "simpleText": "1,258,310 views" },
        "thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
      }
    ],
    "search": "langchain tutorial"
  },
  "response_time": 1230,
  "credits_used": 1,
  "credits_remaining": 999
}

Metadados do Vídeo

Bash

POST https://api.scavio.dev/api/v1/youtube/metadata

Obtenha metadados estruturados de um vídeo do YouTube, incluindo título, descrição, contagem de visualizações, contagem de curtidas, contagem de comentários, tags, miniaturas, data de upload, informações do canal e formatos disponíveis.

Corpo da Requisição

Parâmetro	Tipo	Descrição
`video_id`	`string`	Obrigatório. ID do vídeo do YouTube (ex.: `dQw4w9WgXcQ`).

Exemplo

curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

Exemplo de Resposta

JSON

{
  "data": {
    "title": "Learn RAG From Scratch - Python AI Tutorial",
    "description": "Learn how to implement RAG from scratch...",
    "upload_date": 20240417,
    "duration": 9191,
    "view_count": 1258310,
    "like_count": 23211,
    "comment_count": 295,
    "categories": ["Education"],
    "tags": ["rag", "langchain", "python", "llm"],
    "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
    "channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
    "uploader": "freeCodeCamp.org",
    "uploader_id": "@freecodecamp",
    "uploader_url": "https://www.youtube.com/@freecodecamp",
    "video_id": "sVcwVQRHIc8",
    "is_live": false,
    "age_limit": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "formats": []
  },
  "response_time": 890,
  "credits_used": 1,
  "credits_remaining": 998
}

Formato da Resposta

Todos os endpoints do YouTube retornam um invólucro de resposta consistente:

Campo	Tipo	Descrição
`data`	`object \| null`	O payload da resposta. A forma depende do endpoint. Pesquisa retorna `{results, search}`; metadados retorna o objeto do vídeo. `null` se a requisição falhou upstream.
`response_time`	`number`	Tempo de resposta do servidor em milissegundos
`credits_used`	`number`	Número de créditos consumidos por esta requisição
`credits_remaining`	`number`	Créditos restantes no seu período de faturamento atual

Respostas de Erro

Status	Descrição
`401`	Não autorizado -- chave de API ausente ou inválida
`429`	Limite de taxa ou uso excedido para seu plano
`502`	Erro upstream -- tente novamente após um breve atraso
`503`	Indisponível upstream -- tente novamente mais tarde

Veja Erros para a referência completa de erros e melhores práticas de repetição.

Relacionados

Início Rápido -- obtenha sua chave de API e faça sua primeira requisição
API de Pesquisa do Google -- pesquise no Google com dados SERP estruturados
API da Amazon -- pesquise produtos e obtenha detalhes por ASIN
Limites de Taxa -- limites por nível de plano
Erros -- códigos de erro e tratamento

API do YouTube

A API do YouTube permite pesquisar no YouTube e recuperar metadados de vídeo por meio de uma interface unificada. Cada endpoint retorna JSON estruturado com rastreamento de uso de créditos.

Endpoints

Endpoint	Descrição
`POST /api/v1/youtube/search`	Pesquisar no YouTube com filtros (data, duração, tipo, qualidade)
`POST /api/v1/youtube/metadata`	Obter metadados estruturados de um vídeo (visualizações, curtidas, tags, descrição)

Autenticação

Cabeçalho	Valor	Obrigatório
`Authorization`	`Bearer YOUR_API_KEY`	Sim
`Content-Type`	`application/json`	Sim

Pesquisa no YouTube

Bash

POST https://api.scavio.dev/api/v1/youtube/search

Pesquise no YouTube e obtenha resultados estruturados. Suporta filtragem por data de upload, duração, tipo de resultado, qualidade do vídeo e muito mais.

Corpo da Requisição

Parâmetro	Tipo	Padrão	Descrição
`search`	`string`	--	Obrigatório. Consulta de pesquisa (1-500 caracteres).
`upload_date`	`string`	--	Filtrar por data de upload. Um de: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	Filtrar por tipo de resultado. Um de: `video`, `channel`, `playlist`
`duration`	`string`	--	Filtrar por duração do vídeo. Um de: `short` (menos de 4 min), `medium` (4-20 min), `long` (mais de 20 min)
`sort_by`	`string`	`relevance`	Ordem de classificação. Um de: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	Apenas vídeos HD
`4k`	`boolean`	`false`	Apenas vídeos 4K
`subtitles`	`boolean`	`false`	Apenas vídeos com legendas/closed caption
`creative_commons`	`boolean`	`false`	Apenas vídeos licenciados sob Creative Commons
`live`	`boolean`	`false`	Apenas transmissões ao vivo
`hdr`	`boolean`	`false`	Apenas vídeos HDR
`360`	`boolean`	`false`	Apenas vídeos em 360 graus
`3d`	`boolean`	`false`	Apenas vídeos 3D
`location`	`boolean`	`false`	Apenas vídeos com metadados de localização
`vr180`	`boolean`	`false`	Apenas vídeos VR180

Exemplo

curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "langchain tutorial",
    "type": "video",
    "duration": "medium",
    "sort_by": "view_count",
    "upload_date": "this_year"
  }'

Exemplo de Resposta

JSON

{
  "data": {
    "results": [
      {
        "videoId": "sVcwVQRHIc8",
        "title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
        "longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
        "publishedTimeText": { "simpleText": "1 year ago" },
        "lengthText": { "simpleText": "2:33:11" },
        "viewCountText": { "simpleText": "1,258,310 views" },
        "thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
      }
    ],
    "search": "langchain tutorial"
  },
  "response_time": 1230,
  "credits_used": 1,
  "credits_remaining": 999
}

Metadados do Vídeo

Bash

POST https://api.scavio.dev/api/v1/youtube/metadata

Corpo da Requisição

Parâmetro	Tipo	Descrição
`video_id`	`string`	Obrigatório. ID do vídeo do YouTube (ex.: `dQw4w9WgXcQ`).

Exemplo

curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

Exemplo de Resposta

JSON

{
  "data": {
    "title": "Learn RAG From Scratch - Python AI Tutorial",
    "description": "Learn how to implement RAG from scratch...",
    "upload_date": 20240417,
    "duration": 9191,
    "view_count": 1258310,
    "like_count": 23211,
    "comment_count": 295,
    "categories": ["Education"],
    "tags": ["rag", "langchain", "python", "llm"],
    "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
    "channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
    "uploader": "freeCodeCamp.org",
    "uploader_id": "@freecodecamp",
    "uploader_url": "https://www.youtube.com/@freecodecamp",
    "video_id": "sVcwVQRHIc8",
    "is_live": false,
    "age_limit": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "formats": []
  },
  "response_time": 890,
  "credits_used": 1,
  "credits_remaining": 998
}

Formato da Resposta

Todos os endpoints do YouTube retornam um invólucro de resposta consistente:

Campo	Tipo	Descrição
`data`	`object \| null`	O payload da resposta. A forma depende do endpoint. Pesquisa retorna `{results, search}`; metadados retorna o objeto do vídeo. `null` se a requisição falhou upstream.
`response_time`	`number`	Tempo de resposta do servidor em milissegundos
`credits_used`	`number`	Número de créditos consumidos por esta requisição
`credits_remaining`	`number`	Créditos restantes no seu período de faturamento atual

Respostas de Erro

Status	Descrição
`401`	Não autorizado -- chave de API ausente ou inválida
`429`	Limite de taxa ou uso excedido para seu plano
`502`	Erro upstream -- tente novamente após um breve atraso
`503`	Indisponível upstream -- tente novamente mais tarde

Veja Erros para a referência completa de erros e melhores práticas de repetição.

Relacionados

Início Rápido -- obtenha sua chave de API e faça sua primeira requisição
API de Pesquisa do Google -- pesquise no Google com dados SERP estruturados
API da Amazon -- pesquise produtos e obtenha detalhes por ASIN
Limites de Taxa -- limites por nível de plano
Erros -- códigos de erro e tratamento