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.
API reference · Ads
Creative features of an ad: hook, offers, format, cuts, on-screen text; optional transcript and AI analysis
/v1/ads/{id}/featuresTry it with your accountOpens in your dashboard, filled in; you see the cost before it runs.
Example request
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
idrequirede.g. meta:1187430977361020
includeOptional 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
langLanguage 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.aiWith include=ai: hook, angles, emotions, audience, style, written by a language model
anglesSelling angles, e.g. price, quality, convenience, speed, status, health, sustainability, novelty, trust
audienceWho the ad speaks to
ctaWhat the viewer is asked to do; empty when there is no ask
emotionsEmotions the ad plays on, e.g. joy, fear_of_missing_out, pride, relief, curiosity, belonging
hookThe opening words as the viewer meets them (spoken, on screen or the first line of text), in the ad's language
hook_typeOne of question, bold_claim, problem, offer, social_proof, curiosity, demonstration, testimonial, news, other
languageMain language of the ad, ISO 639-1 (en, de, it)
modelThe AdLib AI version that wrote this analysis, e.g. adlib-ai-1
offerThe offer in a few words; empty when there is none
styleHow the creative is made
One of ugc, talking_head, studio, product_demo, animation, slideshow, static_image, text_only, other
summaryOne or two sentences: what the ad shows and promises
with_transcriptThe spoken transcript was part of the input
data.ctadata.formatrequiredFrom the measured media: vertical_video, horizontal_video, square_video, vertical_image, square_image, horizontal_image, carousel, text_only
data.headlinedata.landingdomainpathurlutmdata.mediarequiredaspect9:16, 4:5, 1:1, 16:9 or WxH reduced
cuts_per_minuteduration_serrorhas_audioheightkindOne of image, video
ocrorientationOne of vertical, square, horizontal
scene_cutsHard cuts in the video
urlwidthdata.methodrequiredrules = text tags with evidence, measurement = measured from the media, ocr = text read from images and video frames
data.ocr_textdata.textrequiredcharsdiscountsemojisfree_offerfree_shippingguaranteehashtagshookFirst sentence of the primary text
hook_is_questionmentionsnoveltynumberspricessocial_proofuppercase_ratioShare of letters in capitals
urgencywordsdata.transcriptWith include=transcript: what is said in the videos, with timestamps
mediaOne entry per video, in the order of the ad's media
data.versionrequiredmetarequiredad_idanalyzed_atcachedThe base features came from an earlier analysis of the same ad version
creditsCredits by part (features, transcript, ai); their sum is X-Billing-Credits minus the ad itself if it was fetched live
errorsA part that failed, with the reason; failed parts are not billed
includedThe optional parts in this answer
pendingThe part still being worked on (processing only)
One of features, transcript, ai
retry_afterSeconds to wait before asking again (processing only)
statusprocessing: still being analysed (202, not billed); call again after retry_after seconds
One of ready, processing