Creative features
Hook, offers, format, cuts and on-screen text of any ad, plus an optional transcript of what is said and an optional AI read of hook type, angles, emotions and audience.
GET /v1/ads/{id}/features breaks an ad down into the parts creative strategists compare. The base is always included; the transcript and the AI read are optional and cost extra.
| Part | Ask for it with | What you get | Credits |
|---|---|---|---|
| Base | always | Hook, prices, discounts, urgency, social proof and other text tags with the exact text they matched; format, aspect ratio, video length, cuts, sound; the text on images and in videos with a timeline of when it is on screen; landing page domain and UTM | 2 |
| Transcript | include=transcript |
What is said in the videos, sentence by sentence with start and end time, and the spoken language | +10 per started minute of video |
| AI read | include=ai |
A summary, the hook and its type, selling angles, emotions, audience, production style, call to action and offer, written by AdLib AI | +5 |
Combine them freely: include=transcript,ai gives the AI read what is said as well, which makes it noticeably better for videos with a voice-over. Every part is stored per ad version, so asking again, or adding a part later, does not redo the others.
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
}
}A real answer, shortened: the full one has more fields and every line of on-screen text.
Base
| Field | What it is |
|---|---|
text.hook |
The first sentence of the ad text, and hook_is_question |
text.prices, text.discounts, text.numbers |
Prices, percentages and "save" phrases as written |
text.urgency, social_proof, guarantee, free_offer, free_shipping, novelty |
Each hit has rule and the exact text, e.g. {"rule": "today only", "text": "Today only"}. English, German, French, Spanish, Italian, Dutch and Polish |
text.emojis, hashtags, mentions, uppercase_ratio |
Counted |
format |
vertical_video, square_image, carousel, text_only, … |
media[].aspect, orientation, width, height |
Of each image or video |
media[].duration_s, has_audio |
Videos |
media[].scene_cuts, cuts_per_minute |
Hard cuts in the video |
media[].ocr.text |
Text on the image; for videos, every distinct text shown during the video, one per line |
media[].ocr.timeline |
Videos: when each text is on screen, {"start", "end", "text"} in seconds, in order of appearance |
landing |
Domain, path and UTM parameters of the landing URL |
On-screen text keeps only words read with at least 75% confidence and leaves an image's text out when fewer than two such words remain, so you get no text rather than wrong text. Times in the timeline are accurate to about a second.
Transcript
include=transcript adds transcript.media[], one entry per video:
| Field | What it is |
|---|---|
duration_s |
Length of the video |
language |
Spoken language (en, de, it, …); empty when nobody speaks |
text |
Everything said |
segments[] |
{"start", "end", "text"} per sentence, in seconds |
error |
Set when this video could not be transcribed (not billed) |
Billed per started minute of video: a 15-second ad costs 10 credits, a 75-second one 20. The same spot rendered for several placements (9:16 and 1:1 of the same length) counts once. Ads without video get an empty media list and are not billed for the transcript.
AI read
include=ai adds ai:
| Field | What it is |
|---|---|
summary |
One or two sentences: what the ad shows and promises |
hook |
The opening words as the viewer meets them, in the ad's language |
hook_type |
question, bold_claim, problem, offer, social_proof, curiosity, demonstration, testimonial, news or other |
angles |
Selling angles, e.g. price, convenience, trust, status |
emotions |
Emotions the ad plays on, e.g. excitement, fear_of_missing_out |
audience |
Who the ad speaks to |
style |
ugc, talking_head, studio, product_demo, animation, slideshow, static_image, text_only or other |
cta, offer |
What the viewer is asked to do, and the offer; empty when there is none |
language |
Main language of the ad |
model, with_transcript |
Which model wrote it, and whether it read the transcript |
The AI read is based only on what is in the ad: its text, the text on screen, its first image or frame and, with include=transcript,ai, what is said. Everything in the base and the transcript is data you can check; the AI read is an interpretation, so use it to sort and summarise, not as evidence.
While it is being made
Text-only ads and most images answer at once. Videos and transcripts take longer: when the work is not done within a few seconds, the call answers 202 Accepted right away instead of keeping you waiting, free of charge:
{ "data": null, "meta": { "ad_id": "tiktok:1877821189943761", "status": "processing", "pending": "transcript", "retry_after": 10, "cached": false } }pending says which part is being worked on. The work keeps running; call the same URL again after retry_after seconds (also sent as the Retry-After header) and you get 200 with meta.status = ready. The Node and Python SDKs, the n8n node and the MCP server ask again for you.
Cost and caching
Credits are charged when the data is delivered, never for a 202, and meta.credits breaks them down by part. A part that fails is listed in meta.errors and not charged; the rest of the answer is still there. Results are stored per ad version: a repeat call answers from storage, and a changed creative is analysed again. Calls where nothing could be analysed (no text, no reachable media) cost nothing. If the ad is not in our archive yet, fetching it live costs the ad's price on top.
What to do with it
- Brief a creative team with evidence. Pull the features of a competitor's longest-running ads (
GET /v1/search?source=history&sort=days_running) and compare hooks, offers, video lengths and what is said in the first three seconds. - Sort a swipe file.
ai.hook_type,ai.anglesandai.stylegroup hundreds of ads in one pass; the transcript and on-screen timeline show what each one actually says. - Spot what they are testing. Ads with
derived.stage: testingare new and unproven;provenads carry two or more signals, such as a long run, several variants or wide EU reach. Features on both show what made it from test to scale. - Ask an agent. The MCP tool
get_ad_featuresreturns the same data and takes the same options, so Claude can explain an ad with quotes instead of guesses.