Docs

Caractéristiques créatives

Accroche, offres, format, plans et texte à l’écran de n’importe quelle publicité, plus une transcription facultative de ce qui est dit et une lecture IA facultative du type d’accroche, des angles, des émotions et de l’audience.

GET /v1/ads/{id}/features décompose une publicité en éléments que les stratèges créatifs comparent. La base est toujours incluse ; la transcription et la lecture IA sont facultatives et facturées en plus.

Élément Comment le demander Ce que vous obtenez Crédits
Base toujours Accroche, prix, remises, urgence, preuve sociale et autres tags de texte avec le passage exact détecté ; format, format d’image, durée de la vidéo, plans, son ; le texte sur les images et dans les vidéos avec une chronologie de son affichage à l’écran ; domaine de la page de destination et UTM 2
Transcription include=transcript Ce qui est dit dans les vidéos, phrase par phrase avec heure de début et de fin, et la langue parlée +10 par minute de vidéo entamée
Lecture IA include=ai Un résumé, l’accroche et son type, les angles de vente, les émotions, l’audience, le style de production, l’appel à l’action et l’offre, rédigés par l’IA d’AdLib +5

Combinez-les librement : include=transcript,ai donne aussi à la lecture IA ce qui est dit, ce qui l’améliore nettement pour les vidéos avec voix off. Chaque élément est stocké par version de la publicité : redemander, ou ajouter un élément plus tard, ne refait pas les autres.

Shell
curl "https://api.adlibapi.com/v1/ads/meta:1332991018770312/features?include=transcript,ai" \
  -H "X-API-Key: $ADLIB_API_KEY"
JSON
{
  "data": {
    "format": "square_video",
    "text": { "hook": "Celebrate the festive season with Galaxy S26 FE.", "prices": [], "urgency": [] },
    "media": [
      { "kind": "video", "aspect": "1:1", "duration_s": 10.1, "scene_cuts": 1, "has_audio": true,
        "ocr": { "timeline": [
          { "start": 0, "end": 2, "text": "Best festive moments." },
          { "start": 0, "end": 2, "text": "Best Samsung Galaxy Deals." },
          { "start": 3, "end": 8, "text": "Instant cashback" },
          { "start": 3, "end": 8, "text": "No Cost EMI" },
          { "start": 9, "end": 10.1, "text": "SAMSUNG" } ] } }
    ],
    "transcript": {
      "media": [{ "duration_s": 10.05, "language": "en",
        "segments": [
          { "start": 0, "end": 4.7, "text": "Make your festive celebration bigger with amazing deals on Samsung Galaxy smartphones." },
          { "start": 4.7, "end": 9.4, "text": "With industry's best no cost EMI and instant cashback, the best time to buy is now." } ] }]
    },
    "ai": {
      "summary": "Festive video ad promoting Samsung Galaxy S26 FE deals with no cost EMI, instant cashback and an exchange offer, ending with a call to buy now.",
      "hook": "Best festive moments. Best Samsung Galaxy Deals.",
      "hook_type": "offer",
      "angles": ["festive_season", "price", "financing", "trade_in", "cashback"],
      "emotions": ["excitement", "urgency", "celebration"],
      "audience": "Consumers in India considering buying a Samsung Galaxy smartphone during the festive season",
      "style": "animation",
      "cta": "Buy now",
      "offer": "No cost EMI up to 40 months, instant cashback, and exchange value of 35000 on Galaxy S25 FE",
      "language": "en",
      "model": "adlib-ai-1",
      "with_transcript": true
    }
  },
  "meta": {
    "ad_id": "meta:1332991018770312",
    "status": "ready",
    "included": ["transcript", "ai"],
    "credits": { "features": 2, "transcript": 10, "ai": 5 },
    "cached": false
  }
}

Une vraie réponse, raccourcie : la version complète contient plus de champs et chaque ligne de texte à l’écran.

Base

Champ Ce que c’est
text.hook La première phrase du texte de la publicité, et hook_is_question
text.prices, text.discounts, text.numbers Prix, pourcentages et formules du type « save », tels qu’écrits
text.urgency, social_proof, guarantee, free_offer, free_shipping, novelty Chaque occurrence a une rule et le text exact, par ex. {"rule": "today only", "text": "Today only"}. Anglais, allemand, français, espagnol, italien, néerlandais et polonais
text.emojis, hashtags, mentions, uppercase_ratio Comptés
format vertical_video, square_image, carousel, text_only, …
media[].aspect, orientation, width, height De chaque image ou vidéo
media[].duration_s, has_audio Vidéos
media[].scene_cuts, cuts_per_minute Coupes franches dans la vidéo
media[].ocr.text Texte sur l’image ; pour les vidéos, chaque texte distinct affiché pendant la vidéo, un par ligne
media[].ocr.timeline Vidéos : quand chaque texte est à l’écran, {"start", "end", "text"} en secondes, dans l’ordre d’apparition
landing Domaine, chemin et paramètres UTM de l’URL de destination

Le texte à l’écran ne garde que les mots lus avec au moins 75 % de confiance et écarte le texte d’une image quand il en reste moins de deux : mieux vaut pas de texte qu’un texte faux. Les temps de la chronologie sont précis à environ une seconde.

Transcription

include=transcript ajoute transcript.media[], une entrée par vidéo :

Champ Ce que c’est
duration_s Durée de la vidéo
language Langue parlée (en, de, it, …) ; vide quand personne ne parle
text Tout ce qui est dit
segments[] {"start", "end", "text"} par phrase, en secondes
error Renseigné quand la vidéo n’a pas pu être transcrite (non facturé)

Facturée par minute de vidéo entamée : une publicité de 15 secondes coûte 10 crédits, une de 75 secondes 20. Le même spot décliné pour plusieurs emplacements (9:16 et 1:1 de même durée) ne compte qu’une fois. Les publicités sans vidéo reçoivent une liste media vide et la transcription ne leur est pas facturée.

Lecture IA

include=ai ajoute ai :

Champ Ce que c’est
summary Une ou deux phrases : ce que la publicité montre et promet
hook Les premiers mots tels que le spectateur les découvre, dans la langue de la publicité
hook_type question, bold_claim, problem, offer, social_proof, curiosity, demonstration, testimonial, news ou other
angles Angles de vente, par ex. price, convenience, trust, status
emotions Émotions sur lesquelles joue la publicité, par ex. excitement, fear_of_missing_out
audience À qui s’adresse la publicité
style ugc, talking_head, studio, product_demo, animation, slideshow, static_image, text_only ou other
cta, offer Ce qu’on demande au spectateur de faire, et l’offre ; vide s’il n’y en a pas
language Langue principale de la publicité
model, with_transcript Le modèle qui l’a rédigée, et s’il a lu la transcription

La lecture IA repose uniquement sur le contenu de la publicité : son texte, le texte à l’écran, sa première image ou frame et, avec include=transcript,ai, ce qui est dit. Tout ce que contiennent la base et la transcription est vérifiable ; la lecture IA est une interprétation : servez-vous-en pour trier et résumer, pas comme preuve.

Pendant le traitement

Les publicités texte seul et la plupart des images répondent immédiatement. Les vidéos et les transcriptions prennent plus de temps : quand le traitement n’est pas terminé en quelques secondes, l’appel répond aussitôt 202 Accepted au lieu de vous faire attendre, sans frais :

JSON
{ "data": null, "meta": { "ad_id": "tiktok:1877821189943761", "status": "processing", "pending": "transcript", "retry_after": 10, "cached": false } }

pending indique l’élément en cours de traitement. Le traitement continue ; rappelez la même URL après retry_after secondes (aussi envoyé dans l’en-tête Retry-After) et vous obtenez 200 avec meta.status = ready. Les SDK Node et Python, le nœud n8n et le serveur MCP relancent l’appel pour vous.

Coût et cache

Les crédits sont débités à la livraison des données, jamais pour un 202, et meta.credits les détaille par élément. Un élément en échec est listé dans meta.errors et n’est pas facturé ; le reste de la réponse est bien là. Les résultats sont stockés par version de la publicité : un appel répété répond depuis le stockage, et une création modifiée est analysée de nouveau. Les appels où rien n’a pu être analysé (pas de texte, aucun média accessible) ne coûtent rien. Si la publicité n’est pas encore dans notre archive, la récupérer en direct coûte en plus le prix de la publicité.

Qu’en faire

  • Briefer une équipe créa sur des faits. Récupérez les caractéristiques des publicités d’un concurrent diffusées depuis le plus longtemps (GET /v1/search?source=history&sort=days_running) et comparez accroches, offres, durées de vidéo et ce qui est dit dans les trois premières secondes.
  • Trier un swipe file. ai.hook_type, ai.angles et ai.style regroupent des centaines de publicités en une passe ; la transcription et la chronologie du texte à l’écran montrent ce que chacune dit vraiment.
  • Repérer ce qu’ils testent. Les publicités en derived.stage: testing sont nouvelles et pas encore validées ; les publicités proven cumulent au moins deux signaux, comme une longue diffusion, plusieurs variantes ou une large portée UE. Les caractéristiques des unes et des autres montrent ce qui est passé du test au scaling.
  • Interroger un agent. L’outil MCP get_ad_features renvoie les mêmes données et accepte les mêmes options : Claude peut expliquer une publicité avec des citations plutôt qu’avec des suppositions.