Facebook Ad Transcript
Las transcripciones de anuncios de Facebook son registros de contenido hablado vinculados a destinos de la Ad Library, con URL de origen, texto, idioma, formato, hora de recopilación y contexto opcional de shortcode. Estos registros sirven para revisar mensajes, indexar palabras clave, procesar contenido según el idioma y mantener archivos con enlace de origen.
Funcionalidades de la Facebook Ad Transcript API
- Lotes de URL de la Ad LibraryAcepta URL de la Facebook Ad Library de los hosts de Facebook compatibles y procesa cada URL única como un destino de transcripción independiente.
- Texto hablado con enlace de origenDevuelve el texto de la transcripción, siempre que no esté vacío, junto con la URL de origen enviada y un identificador que recurre a la URL cuando no hay ID de origen.
- Contexto de idioma y formatoIncluye en el registro normalizado un idioma de origen que puede ser nulo, el formato (texto sin formato o WebVTT), la hora de recopilación y un shortcode opcional.
- Solo registros disponiblesGuarda un resultado únicamente cuando el anuncio seleccionado produce contenido de transcripción no vacío, por lo que una tarea exitosa puede devolver menos registros que URL enviadas.
Parámetros de la Facebook Ad Transcript API
| Parámetros | Obligatorio | Descripción |
|---|---|---|
urls | Obligatorio | URL de la Facebook Ad Library en los hosts de Facebook compatibles, separadas por comas o saltos de línea; la ruta de cada una debe contener /ads/library. |
Cómo usar la Facebook Ad Transcript API
Envíe URL de la Facebook Ad Library y concilie las URL de origen devueltas, porque solo los destinos con texto de transcripción no vacío generan elementos de resultado.
- Prepare una o más URL de la Facebook Ad Library cuyo host sea facebook.com, www.facebook.com o m.facebook.com y cuya ruta contenga /ads/library.
- Envíe urls por POST a /v1/facebook/ad-transcript y guarde el task_id devuelto.
- Consulte /v1/tasks/{task_id} hasta que la tarea termine con éxito o con error.
- Lea data.results.items y, cuando results.has_more sea true, solicite la página siguiente con results.next_cursor.
curl -X POST "https://api.socq.ai/v1/facebook/ad-transcript" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/ads/library/?id=123456789012345"]}'
# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?limit=50&cursor={next_cursor}Casos de uso de la Facebook Ad Transcript API
- Revisión de mensajes publicitarios: Lea el texto de las transcripciones con enlace de origen para comparar las palabras usadas en un conjunto seleccionado de anuncios públicos.
- Indexación de búsqueda del discurso de anuncios: Indexe el texto junto con los ID de registro, las URL de origen, las horas de recopilación y el contexto de shortcode para poder buscar transcripciones de anuncios conocidos por los términos hablados.
- Enrutamiento del procesamiento de transcripciones: Use los campos de idioma y formato para dirigir los registros en texto sin formato y WebVTT al pipeline adecuado de texto, subtítulos o procesamiento de idiomas.
Consejos de expertos para la Facebook Ad Transcript API
- Use un host de Facebook compatible y conserve /ads/library en la ruta de cada URL; otros hosts o rutas no superan la validación de la solicitud.
- Canonice las URL de la Ad Library antes de armar los lotes cuando un mismo destino aparezca con distintas cadenas de consulta, porque el recolector solo elimina las cadenas duplicadas exactas.
- Compare los valores url devueltos con la lista enviada una vez terminada la tarea, para que los anuncios no compatibles y los destinos sin contenido de transcripción no vacío sigan visibles en su flujo de trabajo.
- Ramifique el análisis según format y trate language y extra.shortcode como valores que pueden ser nulos; created_at está reservado y por ahora devuelve null.
- Siga results.next_cursor mientras results.has_more sea true cuando un lote grande de URL abarque más que el límite de resultados por página solicitado.
APIs relacionadas
Además de la Facebook Ad Transcript API, use estas APIs cuando necesite otro tipo de datos públicos de Facebook.
- Facebook Pages API — Obtiene perfiles públicos de páginas de Facebook, datos de contacto, imágenes y calificaciones visibles de la audiencia.
- Facebook Posts API — Recolecta publicaciones públicas, contenido multimedia, reacciones, comentarios y veces compartido desde URLs de Facebook compatibles.
- Facebook Video Transcript API — Extrae el texto de transcripción disponible y su formato desde URLs conocidas de videos o Reels públicos.
- Facebook Group Posts API — Recolecta publicaciones públicas desde URLs de grupos de Facebook con orden seleccionable, límites por grupo, contexto del autor, videos e interacción visible.
- Facebook Profile Photos API — Recolecta fotos públicas desde URLs de perfiles o páginas con descripciones, contexto del autor, interacción, metadatos de imagen y referencias de origen.
- Facebook Reels API — Recolecta Reels públicos desde URLs de perfiles o páginas con descripciones, contexto del autor, metadatos de video, interacción visible y referencias de origen.