facebook/
ad-transcript

Facebook広告ライブラリのURLから利用可能な音声の文字起こしを抽出し、テキスト、言語、形式、収集日時、ソースリンク、ショートコードのコンテキストを返します。

Facebook Ad Transcript API

広告の文字起こし
広告ライブラリのURL
ソースに紐づくテキスト
結果1件あたり0.5クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

Facebook Ad Transcript

Facebook広告の文字起こしとは、広告ライブラリの対象に紐づく音声のテキストレコードのことで、ソースURL、テキスト、言語、形式、収集日時、任意のショートコードのコンテキストを含みます。これらのレコードは、メッセージのレビュー、キーワードのインデックス化、言語に応じた処理、ソースに紐づくアーカイブに活用できます。

Facebook Ad Transcript API の主な機能

  • 広告ライブラリURLの一括指定対応するFacebookホストの広告ライブラリURLを受け付け、重複しない各URLを独立した文字起こし対象として処理します。
  • ソースに紐づく音声テキスト空でない文字起こしテキストを、送信したソースURLと、ソースIDがない場合はURLをフォールバックとする識別子とともに返します。
  • 言語と形式のコンテキスト正規化レコードに、null になり得るソース言語、plaintext または WebVTT の形式、収集日時、任意のショートコードを含めます。
  • 取得できたレコードのみを保存選択した広告対象から空でない文字起こしが得られた場合にのみ結果を保存するため、成功したタスクでも送信したURLより少ないレコードが返ることがあります。

Facebook Ad Transcript API のパラメータ

パラメータ必須説明
urls必須対応するFacebookホスト上の広告ライブラリURLです。カンマまたは改行で区切り、各パスには /ads/library を含める必要があります。

Facebook Ad Transcript API の使い方

Facebook広告ライブラリのURLを送信します。空でない文字起こしテキストがある対象のみが結果になるため、返されたソースURLを入力と照合してください。

  1. ホストが facebook.com、www.facebook.com、m.facebook.com のいずれかで、パスに /ads/library を含むFacebook広告ライブラリのURLを1つ以上用意します。
  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、収集日時、ショートコードのコンテキストとともにインデックス化し、既知の広告の文字起こしを話された語句で検索できるようにします。
  • 文字起こし処理の振り分け: language と format のフィールドを使って、plaintext と WebVTT のレコードを適切なテキスト処理、字幕処理、言語処理のパイプラインに振り分けます。

Facebook Ad Transcript API 活用のヒント

  • 対応するFacebookホストを使用し、すべてのURLパスに /ads/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ページのプロフィール、連絡先、画像、表示中のユーザー評価を取得します。
  • 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広告ライブラリのURLに含まれる音声コンテンツを検索可能な文字起こしレコードに変換し、広告メッセージのレビューやインデックス化を容易にするプログラムインターフェースです。ソース側で空でない文字起こしテキストが提供されている場合、そのレコードをクリエイティブのリサーチ、キーワードのアーカイブ、言語分析に活用できます。

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に結果単位の料金はかかりません。