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.
curl "https://api.adlibapi.com/v1/ads/meta:1332991018770312/features?include=transcript,ai" \
-H "X-API-Key: $ADLIB_API_KEY"{
"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 :
{ "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.anglesetai.styleregroupent 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: testingsont nouvelles et pas encore validées ; les publicitésprovencumulent 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_featuresrenvoie 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.