Cómo obtener una clave API de YouTube (API de datos de YouTube v3) y hacer tu primera solicitud

Una clave API de YouTube es la credencial que permite a tu código leer datos públicos de YouTube: detalles de videos, estadísticas de canales, resultados de búsqueda, contenido de listas de reproducción. La documentación de Google lo dice claramente: “Una solicitud que no proporciona un token OAuth 2.0 debe enviar una clave API. La clave identifica tu proyecto y proporciona acceso a la API, cuota e informes.” Sin clave, no hay datos.

Esta guía te lleva desde un proyecto vacío de Google Cloud hasta una solicitud funcional en unos quince minutos. Habilitarás la API de datos de YouTube v3, crearás una clave, la asegurarás, llamarás a la API desde curl y Python, y luego almacenarás la clave en Apidog y guardarás la llamada como una prueba repetible. Si primero quieres una visión general, nuestra descripción general de la API de datos de YouTube cubre lo que expone la API; esta publicación es la parte práctica.

Qué necesitas antes de empezar

• Una cuenta de Google. Eso es suficiente para abrir la Cloud Console y crear un proyecto.
• curl (incluido en macOS y la mayoría de las distribuciones de Linux) y Python 3 con el paquete requests para los ejemplos de código.
• Apidog si quieres que la clave se almacene como un secreto y la solicitud se guarde como una prueba. El plan gratuito cubre todo lo aquí expuesto.

Paso 1: crear un proyecto de Google Cloud

Abre la Consola de Google Cloud e inicia sesión. Usa el selector de proyectos en la parte superior de la página para crear un nuevo proyecto, por ejemplo youtube-integration. Cada clave API, cubo de cuota e informe de uso que verás más adelante está limitado a este proyecto, así que mantén un proyecto por aplicación en lugar de compartir una clave entre herramientas no relacionadas. Si la aplicación ya tiene un proyecto, usa ese.

Paso 2: habilitar la API de datos de YouTube v3

Las API están desactivadas por defecto en un proyecto nuevo. En la consola, ve a API y Servicios, abre la Biblioteca de API, busca “YouTube Data API v3” y habilítala. La guía de inicio de Google describe la misma verificación desde la otra dirección: visita la página de API habilitadas y habilita la API si no aparece en la lista.

Omite este paso y tu primera solicitud fallará con un 403 diciendo que la API no se ha usado en el proyecto o está deshabilitada. Es la razón más común por la que una clave nueva “no funciona”.

Paso 3: crear la clave API

Ve a API y Servicios, luego a Credenciales. Haz clic en Crear credenciales y elige Clave de API. La consola genera la clave inmediatamente y la muestra en un cuadro de diálogo; cópiala en un lugar seguro.

Trata la clave como una contraseña. No la pegues en un repositorio de Git, un hilo de Slack o un paquete JavaScript del lado del cliente. Si ya se ha colado en un commit, nuestra guía para encontrar y corregir claves API expuestas cubre la limpieza.

Paso 4: restringir la clave

La propia documentación de Google dice “Las claves API no restringidas son inseguras”. Inmediatamente después de la creación, haz clic en Restringir clave. Obtendrás dos controles independientes, documentados en la guía de claves API de Cloud:

• Restricciones de aplicación deciden quién puede presentar la clave. Elige una: sitios web (referentes HTTP, con soporte limitado de comodines), direcciones IP (rangos IPv4, IPv6 o CIDR), aplicaciones de Android (nombre del paquete más huella digital del certificado SHA-1) o aplicaciones de iOS (ID de paquete). Un servicio de backend debería usar direcciones IP. Un widget solo para navegador debería usar referentes.
• Restricciones de API deciden qué API puede llamar la clave. Elige “Restringir clave” y selecciona solo YouTube Data API v3. Si la clave se filtra, el atacante obtendrá la cuota de YouTube y nada más.

Guarda y espera unos minutos para que el cambio surta efecto antes de probar. Dos hábitos más de la misma guía: rota las claves periódicamente para limitar el daño de una comprometida, y elimina las claves antiguas una vez que cada llamador se haya pasado al reemplazo. Una salvedad para el siguiente paso: si restringes por IP a tu servidor, curl desde tu portátil estará bloqueado, así que prueba desde el host permitido o crea una clave de desarrollo separada.

Paso 5: haz tu primera solicitud con curl y Python

Cada endpoint depende de https://www.googleapis.com/youtube/v3/. Pasa la clave como el parámetro de consulta key, que es como lo hacen los propios ejemplos de Google, o en una cabecera x-goog-api-key, lo que la mantiene fuera de las URL y los registros de acceso. Ambas funcionan en la API en vivo.

Comienza con videos.list, la llamada útil más económica: devuelve detalles para uno o más IDs de video y cuesta 1 unidad de cuota. El ID a continuación es el que Google usa en su documentación.

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

Una respuesta recortada se ve así:

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

El parámetro part es obligatorio y controla qué secciones se devuelven; snippet, statistics, contentDetails y status son los que más usarás.

Ahora una búsqueda, que es la llamada que la mayoría de la gente busca. En Python con requests:

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

Para search.list, part debe ser snippet, maxResults por defecto es 5 y acepta de 0 a 50, y type por defecto es video,channel,playlist, así que configúralo en video si solo quieres videos. Los resultados de búsqueda contienen videoId dentro de id, no a nivel superior, por eso el bucle anterior lee item["id"]["videoId"].

Paso 6: almacena la clave y ejecuta la solicitud en Apidog

Una variable de shell funciona para un solo script. No funciona para un equipo y no te proporciona una verificación guardada y reutilizable. Aquí tienes la misma solicitud en Apidog, con la clave mantenida fuera de la nube.

1. Crea un entorno. Añade un entorno llamado YouTube con dos variables: base_url establecida en https://www.googleapis.com/youtube/v3, y youtube_api_key. Para la clave, deja el valor compartido como un marcador de posición y pega la clave real en el campo de valor local. Los valores locales permanecen en la caché de tu cliente y nunca se sincronizan con los compañeros de equipo; la configuración completa se encuentra en nuestra guía sobre entornos y variables secretas en Apidog.
2. Construye la solicitud. Nueva solicitud, GET {{base_url}}/videos, parámetros de consulta part=snippet,statistics e id=7lCDEYXw3mM, y una cabecera x-goog-api-key configurada en {{youtube_api_key}}. Selecciona el entorno YouTube y envía. Deberías ver el mismo JSON que en la llamada curl.
3. Conviértela en una prueba. En los post-procesadores de la solicitud, añade aserciones: el estado es igual a 200, y $.items[0].id es igual a 7lCDEYXw3mM. Guarda la solicitud y añádela a un escenario de prueba. La verificación ahora se ejecuta bajo demanda, en un horario, o en CI a través de la CLI de Apidog, donde --env-var "youtube_api_key=$YOUTUBE_API_KEY" inyecta la clave en tiempo de ejecución en lugar de almacenarla.

La recompensa llega la primera vez que la clave se rota o una restricción cambia: vuelve a ejecutar un escenario y sabrás en segundos si cada llamada de YouTube sigue funcionando. Descarga Apidog para seguir los pasos; es gratis para equipos de hasta cuatro personas.

Cuota y límites

La API de datos de YouTube no te factura en dólares; te factura en unidades de cuota, y los números provienen de la página de calculadora de cuota de Google. Cada proyecto que habilita la API obtiene esta asignación predeterminada:

Dentro del pool compartido de 10,000 unidades, los métodos de listado como videos.list, channels.list, playlistItems.list y commentThreads.list cuestan 1 unidad cada uno. Las escrituras cuestan más: videos.update y videos.delete son 50 unidades, y captions.insert es 400. Cuatro reglas de la misma página dan forma a cómo debes diseñar en torno a esto:

• Las cuotas se restablecen a medianoche, hora del Pacífico.
• Cada solicitud, incluso una inválida, cuesta al menos 1 unidad. Un bucle que reintenta una llamada errónea consume cuota en vano.
• Cada página adicional de un resultado paginado cuesta lo mismo que la primera página.
• La asignación predeterminada está “sujeta a cambios”. Consulta la página, no un tutorial, antes de planificar la capacidad.

Las guías antiguas valoran una búsqueda en 100 unidades del pool de 10,000. La página actual coloca search.list en su propia cubeta, por lo que el límite sigue siendo de 100 búsquedas al día, pero las búsquedas ya no consumen la cuota de tus otras llamadas.

Si eso no es suficiente, la página de auditorías de cuota y cumplimiento te dirige al Formulario de Extensión de Cuota y Auditoría de Servicios de la API de YouTube. Antes de presentarlo, almacena en caché las respuestas, solicita solo los valores de part que necesites y agrupa los IDs en una sola llamada a videos.list (el parámetro id acepta una lista separada por comas). El uso se muestra en la página de Cuotas en la Consola de Cloud.

Errores comunes y cómo solucionarlos

La referencia de errores de Google lista los códigos de motivo propios de la API. Las dos primeras filas a continuación provienen de enviar solicitudes reales a la API en vivo con una clave incorrecta y sin clave.

Una más de la práctica: si una restricción de aplicación no coincide con el llamante, obtendrás un 403 que nombra al referente o IP bloqueado. Corrige la restricción o llama desde el host permitido. Y ten en cuenta que los hilos antiguos del foro llaman al error de clave inválida keyInvalid; la API en vivo devuelve badRequest con un detalle API_KEY_INVALID, así que busca la coincidencia por el mensaje o el detalle, no por la cadena de motivo heredada.

Preguntas Frecuentes

¿Es gratuita una clave API de YouTube?

Sí. Crear una clave no cuesta nada, y la documentación valora la API en unidades de cuota, no en dinero. La asignación predeterminada anterior es lo que obtienes sin pedir nada.

¿Cuándo necesito OAuth en lugar de una clave API?

Una clave API identifica tu proyecto y desbloquea datos públicos. En el momento en que accedes a datos privados de usuario, o insertas, actualizas o eliminas algo, Google requiere un token OAuth 2.0 del usuario propietario de esos datos. Calificar un video, listar tus propias suscripciones o usar el filtro mine=true, todo recae en el lado de OAuth. Nuestra comparación de claves API y tokens de portador explica por qué las dos credenciales responden a preguntas diferentes.

¿Puede un agente de IA usar mi clave API de YouTube?

Sí, siempre y cuando el agente se ejecute donde las restricciones de la clave lo permitan. Un servidor MCP de YouTube es una forma de entregar datos de video a un asistente de codificación; dale una clave restringida a la API de datos y a la máquina en la que se ejecuta, y mantenla fuera del propio prompt.

¿Qué debo hacer si la clave se filtra?

Elimínala en la página de Credenciales y crea una de reemplazo. Luego, corrige la fuente: mueve la clave a un valor local en Apidog o a un almacén de secretos, y escanea el repositorio para que la clave antigua no siga en el historial.

Siguiente paso

Ahora tienes un proyecto, una API habilitada, una clave restringida y una solicitud que funciona desde curl, Python y Apidog. Conecta el escenario guardado a la CI y deja que la página de Cuotas te indique cuándo es el momento de optimizar.