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을 대조합니다. 비어 있지 않은 스크립트 텍스트가 있는 대상만 결과 항목이 되기 때문입니다.
- 호스트가 facebook.com, www.facebook.com, m.facebook.com 중 하나이고 경로에 /ads/library가 포함된 Facebook Ad Library URL을 하나 이상 준비합니다.
- urls 배열을 /v1/facebook/ad-transcript로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 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를 따라가세요.
관련 API
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에서 공개 릴스를 캡션, 작성자 맥락, 동영상 메타데이터, 공개된 참여도, 출처 참조와 함께 수집합니다.