API reference · Ads

Creative features of an ad: hook, offers, format, cuts, on-screen text; optional transcript and AI analysis

GET/v1/ads/{id}/features

Try it with your accountOpens in your dashboard, filled in; you see the cost before it runs.

Base (always, features price, default 2 credits): every text tag (hook, prices, discounts, urgency, social proof, guarantees) carries the exact text it matched; format, aspect ratio, video length, cuts and audio are measured from the media; the text on images and in videos is read with OCR, for videos with a timeline of when each text is on screen (media[].ocr.timeline). include=transcript (+transcript price per started minute of video, default 10): what is said in the videos, with the language and timestamps per sentence (transcript.media[].segments). include=ai (+ai price, default 5): a summary, the hook and its type, selling angles, emotions, audience, production style, CTA and offer, written by a language model from the ad's text, on-screen text, the first image or frame and, with include=transcript,ai, what is said. Parts are combined freely and each is stored per ad version: a repeat call answers from storage, a changed creative is analysed again. New work runs in the background: when it is not done within a few seconds the call answers 202 with meta.status = processing, meta.pending (the part being worked on), meta.retry_after (seconds) and a Retry-After header, free of charge; call again then (the SDKs and the MCP server do this for you). Credits are charged when the data is delivered, broken down in meta.credits; a part that fails is listed in meta.errors and not charged. The ad itself costs extra if it has to be fetched live.

Example request

Shell
curl "https://api.adlibapi.com/v1/ads/meta:1187430977361020/features" \
  -H "X-API-Key: $ADLIB_API_KEY"

Send your key in the X-API-Key header. Try it in the explorer.

Parameters

idrequired
path · string

e.g. meta:1187430977361020

include
string

Optional extra parts, comma-separated: transcript (what is said in the videos, with timestamps; +transcript credits per started video minute), ai (hook type, angles, emotions, audience, style and a summary, written by a language model; +ai credits). Each part is stored per ad version and billed when delivered.

e.g. transcript,ai

lang
string

Language of the ai part's summary, audience, CTA, offer, angles and emotions: en (default), de, es, fr or pt. The hook stays in the ad's own words.

e.g. de

Response

data.ai
object

With include=ai: hook, angles, emotions, audience, style, written by a language model

angles
string[]

Selling angles, e.g. price, quality, convenience, speed, status, health, sustainability, novelty, trust

audience
string

Who the ad speaks to

cta
string

What the viewer is asked to do; empty when there is no ask

emotions
string[]

Emotions the ad plays on, e.g. joy, fear_of_missing_out, pride, relief, curiosity, belonging

hook
string

The opening words as the viewer meets them (spoken, on screen or the first line of text), in the ad's language

hook_type
string

One of question, bold_claim, problem, offer, social_proof, curiosity, demonstration, testimonial, news, other

language
string

Main language of the ad, ISO 639-1 (en, de, it)

model
string

The AdLib AI version that wrote this analysis, e.g. adlib-ai-1

offer
string

The offer in a few words; empty when there is none

style
string

How the creative is made

One of ugc, talking_head, studio, product_demo, animation, slideshow, static_image, text_only, other

summary
string

One or two sentences: what the ad shows and promises

with_transcript
boolean

The spoken transcript was part of the input

data.cta
string
–
data.formatrequired
string

From the measured media: vertical_video, horizontal_video, square_video, vertical_image, square_image, horizontal_image, carousel, text_only

data.headline
string
–
data.landing
object
–
domain
string
–
path
string
–
url
string
–
utm
map of string
–
data.mediarequired
object[]
–
aspect
string

9:16, 4:5, 1:1, 16:9 or WxH reduced

cuts_per_minute
number
–
duration_s
number
–
error
string
–
has_audio
boolean
–
height
integer
–
kind
string

One of image, video

ocr
object
–
orientation
string

One of vertical, square, horizontal

scene_cuts
integer

Hard cuts in the video

url
string
–
width
integer
–
data.methodrequired
string

rules = text tags with evidence, measurement = measured from the media, ocr = text read from images and video frames

data.ocr_text
string
–
data.textrequired
object
–
chars
integer
–
discounts
string[]
–
emojis
integer
–
free_offer
object[]
–
free_shipping
object[]
–
guarantee
object[]
–
hashtags
string[]
–
hook
string

First sentence of the primary text

hook_is_question
boolean
–
mentions
string[]
–
novelty
object[]
–
numbers
string[]
–
prices
string[]
–
social_proof
object[]
–
uppercase_ratio
number

Share of letters in capitals

urgency
object[]
–
words
integer
–
data.transcript
object

With include=transcript: what is said in the videos, with timestamps

media
object[]

One entry per video, in the order of the ad's media

data.versionrequired
string
–
metarequired
object
–
ad_id
string
–
analyzed_at
datetime
–
cached
boolean

The base features came from an earlier analysis of the same ad version

credits
map of integer

Credits by part (features, transcript, ai); their sum is X-Billing-Credits minus the ad itself if it was fetched live

errors
map of string

A part that failed, with the reason; failed parts are not billed

included
string[]

The optional parts in this answer

pending
string

The part still being worked on (processing only)

One of features, transcript, ai

retry_after
integer

Seconds to wait before asking again (processing only)

status
string

processing: still being analysed (202, not billed); call again after retry_after seconds

One of ready, processing