YouTube API

La YouTube API te permite buscar en YouTube y recuperar metadatos de videos a traves de una interfaz unificada. Cada endpoint devuelve JSON estructurado con seguimiento de uso de creditos.

Endpoints

Endpoint	Descripcion
`POST /api/v1/youtube/search`	Buscar en YouTube con filtros (fecha, duracion, tipo, calidad)
`POST /api/v1/youtube/metadata`	Obtener metadatos estructurados de un video (vistas, likes, tags, descripcion)

Autenticacion

Encabezado	Valor	Requerido
`Authorization`	`Bearer YOUR_API_KEY`	Si
`Content-Type`	`application/json`	Si

Busqueda en YouTube

Bash

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

Busca en YouTube y obtiene resultados estructurados. Soporta filtrado por fecha de subida, duracion, tipo de resultado, calidad de video y mas.

Cuerpo de la solicitud

Parametro	Tipo	Por defecto	Descripcion
`search`	`string`	--	Requerido. Consulta de busqueda (1-500 caracteres).
`upload_date`	`string`	--	Filtrar por fecha de subida. Uno de: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	Filtrar por tipo de resultado. Uno de: `video`, `channel`, `playlist`
`duration`	`string`	--	Filtrar por duracion del video. Uno de: `short` (menos de 4 min), `medium` (4-20 min), `long` (mas de 20 min)
`sort_by`	`string`	`relevance`	Orden de clasificacion. Uno de: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	Solo videos HD
`4k`	`boolean`	`false`	Solo videos 4K
`subtitles`	`boolean`	`false`	Solo videos con subtitulos
`creative_commons`	`boolean`	`false`	Solo videos con licencia Creative Commons
`live`	`boolean`	`false`	Solo transmisiones en vivo
`hdr`	`boolean`	`false`	Solo videos HDR
`360`	`boolean`	`false`	Solo videos de 360 grados
`3d`	`boolean`	`false`	Solo videos 3D
`location`	`boolean`	`false`	Solo videos con metadatos de ubicacion
`vr180`	`boolean`	`false`	Solo videos VR180

Ejemplo

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"
  }'

Ejemplo de respuesta

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
}

Metadatos de video

Bash

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

Obtiene metadatos estructurados de un video de YouTube incluyendo titulo, descripcion, conteo de vistas, conteo de likes, conteo de comentarios, tags, miniaturas, fecha de subida, informacion del canal y formatos disponibles.

Cuerpo de la solicitud

Parametro	Tipo	Descripcion
`video_id`	`string`	Requerido. ID de video de YouTube (por ejemplo, `dQw4w9WgXcQ`).

Ejemplo

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"}'

Ejemplo de respuesta

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 de respuesta

Todos los endpoints de YouTube devuelven un wrapper de respuesta consistente:

Campo	Tipo	Descripcion
`data`	`object \| null`	El payload de la respuesta. La estructura depende del endpoint. La busqueda devuelve `{results, search}`; los metadatos devuelven el objeto del video. `null` si la solicitud fallo en el upstream.
`response_time`	`number`	Tiempo de respuesta del servidor en milisegundos
`credits_used`	`number`	Numero de creditos consumidos por esta solicitud
`credits_remaining`	`number`	Creditos restantes en tu periodo de facturacion actual

Respuestas de error

Estado	Descripcion
`401`	No autorizado -- clave API faltante o invalida
`429`	Limite de tasa o uso excedido para tu plan
`502`	Error de upstream -- reintenta tras una breve espera
`503`	Upstream no disponible -- reintenta mas tarde

Consulta Errores para la referencia completa de errores y mejores practicas de reintento.

Relacionado

Inicio rapido -- obtiene tu clave API y haz tu primera solicitud
Google Search API -- busca en Google con datos SERP estructurados
Amazon API -- busca productos y obtiene detalles por ASIN
Rate Limits -- limites por nivel de plan
Errores -- codigos de error y manejo

YouTube API

La YouTube API te permite buscar en YouTube y recuperar metadatos de videos a traves de una interfaz unificada. Cada endpoint devuelve JSON estructurado con seguimiento de uso de creditos.

Endpoints

Endpoint	Descripcion
`POST /api/v1/youtube/search`	Buscar en YouTube con filtros (fecha, duracion, tipo, calidad)
`POST /api/v1/youtube/metadata`	Obtener metadatos estructurados de un video (vistas, likes, tags, descripcion)

Autenticacion

Encabezado	Valor	Requerido
`Authorization`	`Bearer YOUR_API_KEY`	Si
`Content-Type`	`application/json`	Si

Busqueda en YouTube

Bash

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

Busca en YouTube y obtiene resultados estructurados. Soporta filtrado por fecha de subida, duracion, tipo de resultado, calidad de video y mas.

Cuerpo de la solicitud

Parametro	Tipo	Por defecto	Descripcion
`search`	`string`	--	Requerido. Consulta de busqueda (1-500 caracteres).
`upload_date`	`string`	--	Filtrar por fecha de subida. Uno de: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	Filtrar por tipo de resultado. Uno de: `video`, `channel`, `playlist`
`duration`	`string`	--	Filtrar por duracion del video. Uno de: `short` (menos de 4 min), `medium` (4-20 min), `long` (mas de 20 min)
`sort_by`	`string`	`relevance`	Orden de clasificacion. Uno de: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	Solo videos HD
`4k`	`boolean`	`false`	Solo videos 4K
`subtitles`	`boolean`	`false`	Solo videos con subtitulos
`creative_commons`	`boolean`	`false`	Solo videos con licencia Creative Commons
`live`	`boolean`	`false`	Solo transmisiones en vivo
`hdr`	`boolean`	`false`	Solo videos HDR
`360`	`boolean`	`false`	Solo videos de 360 grados
`3d`	`boolean`	`false`	Solo videos 3D
`location`	`boolean`	`false`	Solo videos con metadatos de ubicacion
`vr180`	`boolean`	`false`	Solo videos VR180

Ejemplo

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"
  }'

Ejemplo de respuesta

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
}

Metadatos de video

Bash

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

Cuerpo de la solicitud

Parametro	Tipo	Descripcion
`video_id`	`string`	Requerido. ID de video de YouTube (por ejemplo, `dQw4w9WgXcQ`).

Ejemplo

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"}'

Ejemplo de respuesta

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 de respuesta

Todos los endpoints de YouTube devuelven un wrapper de respuesta consistente:

Campo	Tipo	Descripcion
`data`	`object \| null`	El payload de la respuesta. La estructura depende del endpoint. La busqueda devuelve `{results, search}`; los metadatos devuelven el objeto del video. `null` si la solicitud fallo en el upstream.
`response_time`	`number`	Tiempo de respuesta del servidor en milisegundos
`credits_used`	`number`	Numero de creditos consumidos por esta solicitud
`credits_remaining`	`number`	Creditos restantes en tu periodo de facturacion actual

Respuestas de error

Estado	Descripcion
`401`	No autorizado -- clave API faltante o invalida
`429`	Limite de tasa o uso excedido para tu plan
`502`	Error de upstream -- reintenta tras una breve espera
`503`	Upstream no disponible -- reintenta mas tarde

Consulta Errores para la referencia completa de errores y mejores practicas de reintento.

Relacionado

Inicio rapido -- obtiene tu clave API y haz tu primera solicitud
Google Search API -- busca en Google con datos SERP estructurados
Amazon API -- busca productos y obtiene detalles por ASIN
Rate Limits -- limites por nivel de plan
Errores -- codigos de error y manejo