Docs

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.

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
  }
}

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:

JSON
{ "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.angles and ai.style group 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: testing are new and unproven; proven ads 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_features returns the same data and takes the same options, so Claude can explain an ad with quotes instead of guesses.