facebook/
ad-transcript

Facebook Ad Library URL에서 제공되는 음성 스크립트를 추출하고, 텍스트, 언어, 형식, 수집 시각, 원본 링크, shortcode 정보를 반환합니다.

Facebook Ad Transcript API

광고 스크립트
Ad Library URL
원본 링크가 있는 텍스트
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Facebook Ad Transcript

Facebook 광고 스크립트는 Ad Library 대상에 연결된 음성 레코드로, 원본 URL, 텍스트, 언어, 형식, 수집 시각, 선택적인 shortcode 정보를 담고 있습니다. 이러한 레코드는 메시지 검토, 키워드 색인, 언어별 처리, 원본 링크가 있는 아카이브에 활용할 수 있습니다.

Facebook Ad Transcript API 주요 기능

  • Ad Library URL 일괄 처리지원되는 Facebook 호스트의 Facebook Ad Library URL을 받아, 고유한 URL마다 독립적인 스크립트 대상으로 처리합니다.
  • 원본 링크가 있는 음성 텍스트비어 있지 않은 스크립트 텍스트를 제출한 원본 URL과 함께 반환하며, 원본 ID가 없으면 URL을 식별자로 사용합니다.
  • 언어·형식 정보null일 수 있는 원본 언어, plaintext 또는 WebVTT 형식, 수집 시각, 선택적인 shortcode를 정규화된 레코드에 포함합니다.
  • 확인된 결과만 저장선택한 광고 대상에서 비어 있지 않은 스크립트 내용이 확인될 때만 결과를 저장하므로, 작업이 성공해도 제출한 URL보다 적은 레코드가 반환될 수 있습니다.

Facebook Ad Transcript API 매개변수

매개변수필수설명
urls필수지원되는 Facebook 호스트의 Facebook Ad Library URL로, 쉼표 또는 줄바꿈으로 구분합니다. 각 경로에는 /ads/library가 포함되어야 합니다.

Facebook Ad Transcript API 사용 방법

Facebook Ad Library URL을 제출한 뒤 반환된 원본 URL을 대조합니다. 비어 있지 않은 스크립트 텍스트가 있는 대상만 결과 항목이 되기 때문입니다.

  1. 호스트가 facebook.com, www.facebook.com, m.facebook.com 중 하나이고 경로에 /ads/library가 포함된 Facebook Ad Library URL을 하나 이상 준비합니다.
  2. urls 배열을 /v1/facebook/ad-transcript로 POST하고, 반환된 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 정보와 함께 색인해, 알고 있는 광고의 스크립트를 음성 속 용어로 검색할 수 있게 합니다.
  • 스크립트 처리 경로 분기: language와 format 필드를 이용해 plaintext와 WebVTT 레코드를 알맞은 텍스트, 자막, 언어 처리 파이프라인으로 보냅니다.

Facebook Ad Transcript API 활용 팁

  • 지원되는 Facebook 호스트를 사용하고 모든 URL 경로에 /ads/library를 유지하세요. 다른 호스트나 경로는 요청 검증에서 실패합니다.
  • 수집기는 완전히 같은 문자열만 중복으로 제거하므로, 같은 대상이 서로 다른 쿼리 문자열로 나타나면 일괄 제출 전에 Ad Library URL을 표준 형태로 맞추세요.
  • 작업이 성공한 뒤에는 반환된 url 값을 제출한 목록과 비교해, 지원되지 않는 광고와 비어 있지 않은 스크립트 내용이 없는 대상이 워크플로에서 계속 보이도록 하세요.
  • format에 따라 파싱을 분기하고, language와 extra.shortcode는 null일 수 있는 값으로 처리하세요. created_at은 예약 필드이며 현재는 null을 반환합니다.
  • URL 일괄 처리 분량이 요청한 결과 페이지 한도를 넘으면 results.has_more가 true인 동안 results.next_cursor를 따라가세요.

Facebook Ad Transcript API 외에 Facebook의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Facebook Pages API — 공개 페이지 프로필, 연락처, 이미지, 공개된 오디언스 평점을 가져옵니다.
  • Facebook Posts API — 지원되는 Facebook URL에서 공개 게시물, 미디어, 반응, 댓글, 공유 수를 수집합니다.
  • Facebook Video Transcript API — 공개 동영상 게시물 또는 릴스 URL에서 제공되는 스크립트 텍스트와 형식을 추출합니다.
  • Facebook Group Posts API — Facebook 그룹 URL에서 공개 게시물을 수집하며, 정렬 방식과 그룹별 제한을 선택할 수 있고 작성자 맥락, 동영상 미디어, 공개된 참여도를 포함합니다.
  • Facebook Profile Photos API — 프로필 또는 페이지 URL에서 공개 사진을 캡션, 작성자 맥락, 참여도, 이미지 메타데이터, 출처 참조와 함께 수집합니다.
  • Facebook Reels API — 프로필 또는 페이지 URL에서 공개 릴스를 캡션, 작성자 맥락, 동영상 메타데이터, 공개된 참여도, 출처 참조와 함께 수집합니다.

다른 플랫폼 둘러보기

Facebook 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Facebook Ad Transcript API — 자주 묻는 질문

Facebook Ad Transcript API는 지원되는 Facebook Ad Library URL의 음성 내용을 검색 가능한 스크립트 레코드로 바꿔 광고 메시지를 검토하고 색인하기 쉽게 해 주는 API입니다. 출처에 비어 있지 않은 스크립트 텍스트가 있다면, 소재 조사, 키워드 보관, 언어 분석에 레코드를 활용할 수 있습니다.

urls 배열의 각 항목은 facebook.com, www.facebook.com, m.facebook.com 중 하나를 사용하고 경로에 /ads/library를 포함해야 합니다. 검증 단계에서 숫자 광고 ID는 필요하지 않지만, 제출한 대상은 지원되는 스크립트 내용으로 확인되어야 합니다.

정규화된 레코드마다 id, platform, resource, type, url, text, null일 수 있는 language, format, null인 created_at, collected_at, extra.shortcode가 들어 있습니다. 광고주, 지출, 도달, 타기팅, 광고 소재 미디어, 참여도 필드는 추가하지 않습니다.

수집기는 고유한 URL을 하나씩 따로 요청하고, 출처에서 비어 있지 않은 스크립트 내용이 반환될 때만 레코드를 저장합니다. 따라서 지원되지 않는 대상이나 접근 가능한 음성 텍스트가 없는 광고는 임의의 결과를 만들지 않습니다.

출처가 언어 라벨을 제공하지 않을 수 있으므로 language는 null일 수 있는 값으로 취급하세요. 텍스트를 파싱하기 전에 format을 먼저 확인하세요. WebVTT 헤더로 시작하는 내용은 webvtt, 그 밖의 스크립트 내용은 plaintext로 표시됩니다.

반환된 정규화 스크립트 레코드 1건마다 0.5 크레딧이 차감됩니다. 현재의 빈 결과 정책에 따라, 저장된 결과가 없는 URL에는 결과당 요금이 발생하지 않습니다.