Facebook Ad Transcript
Facebook Ad Transcript indica i record del parlato collegati ai target della Ad Library, con URL di origine, testo, lingua, formato, momento della raccolta e contesto facoltativo dello shortcode. Questi record permettono di rivedere i messaggi, indicizzare le parole chiave, elaborare i contenuti in base alla lingua e creare archivi collegati alla fonte.
Funzionalità della Facebook Ad Transcript API
- Batch di URL della Ad LibraryAccetta gli URL della Facebook Ad Library provenienti dagli host Facebook supportati ed elabora ogni URL univoco come target di trascrizione indipendente.
- Parlato collegato alla fonteRestituisce il testo della trascrizione non vuoto insieme all’URL di origine inviato e a un identificatore che ricade sull’URL quando non è presente un ID di origine.
- Contesto di lingua e formatoInclude nel record normalizzato una lingua di origine nullable, il formato plaintext o WebVTT, il momento della raccolta e uno shortcode facoltativo.
- Solo record disponibiliSalva un risultato solo quando il target dell’annuncio selezionato produce un contenuto di trascrizione non vuoto, quindi un’attività riuscita può restituire meno record degli URL inviati.
Parametri della Facebook Ad Transcript API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
urls | Obbligatorio | URL della Facebook Ad Library sugli host Facebook supportati, separati da virgole o a capo; ogni percorso deve contenere /ads/library. |
Come usare la Facebook Ad Transcript API
Invia gli URL della Facebook Ad Library, poi confronta gli URL di origine restituiti, perché solo i target con testo di trascrizione non vuoto producono elementi di risultato.
- Prepara uno o più URL della Facebook Ad Library il cui host è facebook.com, www.facebook.com o m.facebook.com e il cui percorso contiene /ads/library.
- Invia urls con POST a /v1/facebook/ad-transcript, poi salva il task_id restituito.
- Interroga /v1/tasks/{task_id} finché l’attività ha successo o fallisce.
- Leggi data.results.items e, quando results.has_more è true, richiedi la pagina successiva 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}Casi d’uso della Facebook Ad Transcript API
- Revisione dei messaggi pubblicitari: Leggi il testo delle trascrizioni collegato alla fonte per confrontare le parole usate nel parlato in un gruppo selezionato di target pubblici di annunci.
- Indicizzazione di ricerca del parlato degli annunci: Indicizza il testo insieme a ID dei record, URL di origine, momenti di raccolta e contesto dello shortcode, così le trascrizioni di annunci noti si possono cercare per termini parlati.
- Instradamento dell’elaborazione delle trascrizioni: Usa i campi di lingua e formato per instradare i record plaintext e WebVTT verso la pipeline appropriata di testo, sottotitoli o elaborazione linguistica.
Consigli degli esperti per la Facebook Ad Transcript API
- Usa un host Facebook supportato e mantieni /ads/library nel percorso di ogni URL; altri host o percorsi non superano la validazione della richiesta.
- Normalizza gli URL della Ad Library prima di creare i batch quando lo stesso target compare con stringhe di query diverse, perché il collector rimuove solo le stringhe esattamente duplicate.
- Dopo il successo confronta i valori url restituiti con l’elenco inviato, così gli annunci non supportati e i target senza contenuto di trascrizione non vuoto restano visibili nel tuo flusso di lavoro.
- Differenzia l’analisi in base a format e gestisci language ed extra.shortcode come valori nullable; created_at è riservato e al momento restituisce null.
- Segui results.next_cursor finché results.has_more è true quando un batch di URL molto ampio supera il limite richiesto per pagina di risultati.
API correlate
Oltre alla Facebook Ad Transcript API, usa queste API quando ti serve un altro tipo di dati pubblici di Facebook.
- Facebook Pages API — Recupera i profili pubblici delle Pagine, i dati di contatto, le immagini e le valutazioni visibili del pubblico.
- Facebook Posts API — Raccoglie post pubblici, media, reazioni, commenti e condivisioni da URL Facebook supportati.
- Facebook Video Transcript API — Estrae, quando disponibili, il testo e il formato della trascrizione dagli URL pubblici di video o Reels noti.
- Facebook Group Posts API — Raccoglie i post pubblici dagli URL dei gruppi Facebook con ordinamento selezionabile, limiti per gruppo, contesto dell’autore, video ed engagement visibile.
- Facebook Profile Photos API — Raccoglie le foto pubbliche dagli URL di profili o Pagine con didascalie, contesto dell’autore, engagement, metadati delle immagini e riferimenti alla fonte.
- Facebook Reels API — Raccoglie i Reels pubblici dagli URL di profili o Pagine con didascalie, contesto dell’autore, metadati dei video, engagement visibile e riferimenti alla fonte.