facebook/
ad-transcript

Извлекайте доступные расшифровки устной речи по URL из Facebook Ad Library: текст, язык, формат, время сбора, ссылки на источник и shortcode.

Facebook Ad Transcript API

Расшифровки рекламы
URL из Ad Library
Текст со ссылкой на источник
0,5 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

Facebook Ad Transcript

Facebook Ad Transcript — это записи устной речи, привязанные к объектам Ad Library, с исходным URL, текстом, языком, форматом, временем сбора и необязательным shortcode. Такие записи помогают анализировать рекламные сообщения, индексировать ключевые слова, обрабатывать текст с учетом языка и вести архивы со ссылками на источник.

Возможности Facebook Ad Transcript API

  • Пакеты URL из Ad LibraryПринимает URL из Facebook Ad Library с поддерживаемых хостов Facebook и обрабатывает каждый уникальный URL как отдельный объект для расшифровки.
  • Устный текст со ссылкой на источникВозвращает непустой текст расшифровки вместе с переданным исходным URL и идентификатором, который заменяется на URL, если ID источника отсутствует.
  • Язык и форматДобавляет в нормализованную запись язык источника (может быть null), формат plaintext или WebVTT, время сбора и необязательный shortcode.
  • Только доступные записиСохраняет результат, только если выбранное объявление дает непустую расшифровку, поэтому успешная задача может вернуть меньше записей, чем было передано URL.

Параметры Facebook Ad Transcript API

ПараметрыОбязательныйОписание
urlsОбязательныйURL из Facebook Ad Library на поддерживаемых хостах Facebook, разделенные запятыми или переводами строки; каждый путь должен содержать /ads/library.

Как использовать Facebook Ad Transcript API

Отправьте URL из Facebook Ad Library, затем сверьте возвращенные исходные URL: элементы результата создаются только для объектов с непустым текстом расшифровки.

  1. Подготовьте один или несколько URL из Facebook Ad Library с хостом facebook.com, www.facebook.com или m.facebook.com и путем, содержащим /ads/library.
  2. Отправьте urls методом POST на /v1/facebook/ad-transcript и сохраните возвращенный task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой.
  4. Читайте data.results.items, а если results.has_more равно true, запрашивайте следующую страницу с 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}

Сценарии использования Facebook Ad Transcript API

  • Анализ рекламных сообщений: Читайте текст расшифровок со ссылками на источник, чтобы сравнивать формулировки, звучащие в выбранном наборе публичных объявлений.
  • Индексация речи в рекламе для поиска: Индексируйте текст вместе с ID записей, исходными URL, временем сбора и shortcode, чтобы находить известные расшифровки рекламы по произнесенным словам.
  • Маршрутизация обработки расшифровок: Используйте поля языка и формата, чтобы направлять записи plaintext и WebVTT в подходящий пайплайн обработки текста, субтитров или языка.

Практические советы по Facebook Ad Transcript API

  • Используйте поддерживаемый хост Facebook и сохраняйте /ads/library в пути каждого URL: другие хосты или пути не проходят проверку запроса.
  • Приводите URL из Ad Library к каноническому виду перед формированием пакета, если один и тот же объект встречается с разными строками запроса: сборщик удаляет только точные дубли строк.
  • После успешного завершения сверяйте возвращенные значения url с отправленным списком, чтобы неподдерживаемые объявления и объекты без непустой расшифровки оставались видимыми в вашем рабочем процессе.
  • Выбирайте способ разбора по format и обрабатывайте language и extra.shortcode как значения, которые могут быть null; поле created_at зарезервировано и сейчас возвращает null.
  • Переходите по results.next_cursor, пока results.has_more равно true, если большой пакет URL не помещается в запрошенный лимит страницы результатов.

Помимо Facebook Ad Transcript API, используйте эти API, когда нужен другой тип публичных данных Facebook.

  • Facebook Pages API — Получайте публичные профили страниц, контактные данные, изображения и видимые оценки аудитории.
  • Facebook Posts API — Собирайте публичные публикации, медиа, реакции, комментарии и репосты по поддерживаемым URL Facebook.
  • Facebook Video Transcript API — Извлекайте доступный текст расшифровки и формат по URL известных публичных видеопубликаций или Reels.
  • Facebook Group Posts API — Собирайте публичные публикации по URL групп Facebook с выбором порядка, лимитом на группу, контекстом автора, видео и видимой вовлеченностью.
  • Facebook Profile Photos API — Собирайте публичные фото по URL профилей или страниц: подписи, контекст автора, вовлеченность, метаданные изображений и ссылки на источник.
  • Facebook Reels API — Собирайте публичные Reels по URL профилей или страниц: подписи, контекст автора, метаданные видео, видимая вовлеченность и ссылки на источник.

Другие платформы

Объединяйте данные Facebook с публичными данными других поддерживаемых соцсетей.

Facebook Ad Transcript API — FAQ

Facebook Ad Transcript API — это программный интерфейс, который превращает устную речь из поддерживаемых URL Facebook Ad Library в доступные для поиска записи расшифровок, упрощая анализ и индексацию рекламных сообщений. Команды могут использовать эти записи для исследования креативов, архивирования ключевых слов и языкового анализа, если источник отдает непустой текст расшифровки.

Каждый элемент urls должен использовать facebook.com, www.facebook.com или m.facebook.com и содержать /ads/library в пути. Проверка не требует числового ID объявления, но переданный объект всё равно должен вести к поддерживаемому содержимому расшифровки.

Каждая нормализованная запись содержит id, platform, resource, type, url, text, language (может быть null), format, created_at со значением null, collected_at и extra.shortcode. Поля рекламодателя, расходов, охвата, таргетинга, креативов и вовлеченности не добавляются.

Сборщик запрашивает каждый уникальный URL отдельно и сохраняет запись, только если источник возвращает непустую расшифровку. Поэтому неподдерживаемые объекты или объявления без доступной речи не дают результата-заглушки.

Учитывайте, что language может быть null: источник не всегда указывает язык. Проверяйте format перед разбором text: содержимое, начинающееся с заголовка WebVTT, помечается как webvtt, а остальные расшифровки — как plaintext.

Каждая возвращенная нормализованная запись расшифровки стоит 0,5 кредита. За URL, по которому результат не сохранен, плата за результат при текущей политике пустых результатов не взимается.