Docs

Creative-Merkmale

Hook, Angebote, Format, Schnitte und eingeblendeter Text jeder Anzeige, dazu optional ein Transkript des Gesprochenen und optional eine KI-Auswertung von Hook-Typ, Argumenten, Emotionen und Zielgruppe.

GET /v1/ads/{id}/features zerlegt eine Anzeige in die Teile, die Creative-Strategen vergleichen. Die Basis ist immer dabei. Transkript und KI-Auswertung sind optional und kosten extra.

Teil So forderst du ihn an Was du bekommst Credits
Basis immer Hook, Preise, Rabatte, Dringlichkeit, Social Proof und andere Text-Tags mit dem genauen Text, auf den sie gepasst haben; Format, Seitenverhältnis, Videolänge, Schnitte, Ton; der Text auf Bildern und in Videos mit einer Timeline, wann er zu sehen ist; Domain der Landingpage und UTM 2
Transkript include=transcript Was in den Videos gesagt wird, Satz für Satz mit Start- und Endzeit, und die gesprochene Sprache +10 pro angefangene Videominute
KI-Auswertung include=ai Eine Zusammenfassung, der Hook und sein Typ, Verkaufsargumente, Emotionen, Zielgruppe, Produktionsstil, Call to Action und Angebot, geschrieben von der AdLib-KI +5

Du kannst sie frei kombinieren: Mit include=transcript,ai liest die KI-Auswertung auch das Gesprochene mit. Bei Videos mit Voice-over wird sie dadurch spürbar besser. Jeder Teil wird pro Anzeigenversion gespeichert. Fragst du noch mal oder forderst später einen weiteren Teil an, werden die anderen nicht neu berechnet.

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

Eine echte Antwort, gekürzt: Die vollständige hat mehr Felder und jede Zeile des eingeblendeten Texts.

Basis

Feld Was es ist
text.hook Der erste Satz des Anzeigentexts, dazu hook_is_question
text.prices, text.discounts, text.numbers Preise, Prozentangaben und Spar-Formulierungen („save“), wie sie dastehen
text.urgency, social_proof, guarantee, free_offer, free_shipping, novelty Jeder Treffer hat rule und den genauen text, z. B. {"rule": "today only", "text": "Today only"}. Englisch, Deutsch, Französisch, Spanisch, Italienisch, Niederländisch und Polnisch
text.emojis, hashtags, mentions, uppercase_ratio Gezählt
format vertical_video, square_image, carousel, text_only, …
media[].aspect, orientation, width, height Von jedem Bild oder Video
media[].duration_s, has_audio Videos
media[].scene_cuts, cuts_per_minute Harte Schnitte im Video
media[].ocr.text Text auf dem Bild; bei Videos jeder unterschiedliche Text, der im Video zu sehen ist, einer pro Zeile
media[].ocr.timeline Videos: wann welcher Text zu sehen ist, {"start", "end", "text"} in Sekunden, in der Reihenfolge des Erscheinens
landing Domain, Pfad und UTM-Parameter der Landing-URL

Beim eingeblendeten Text behalten wir nur Wörter, die mit mindestens 75 % Sicherheit erkannt wurden. Bleiben auf einem Bild weniger als zwei solche Wörter übrig, lassen wir seinen Text weg. Du bekommst also lieber keinen Text als falschen. Die Zeiten in der Timeline sind auf etwa eine Sekunde genau.

Transkript

include=transcript ergänzt transcript.media[], einen Eintrag pro Video:

Feld Was es ist
duration_s Länge des Videos
language Gesprochene Sprache (en, de, it, …); leer, wenn niemand spricht
text Alles Gesagte
segments[] {"start", "end", "text"} pro Satz, in Sekunden
error Gesetzt, wenn dieses Video nicht transkribiert werden konnte (wird nicht berechnet)

Abgerechnet wird pro angefangene Videominute: Eine 15-Sekunden-Anzeige kostet 10 Credits, eine mit 75 Sekunden 20. Derselbe Spot in mehreren Platzierungen (9:16 und 1:1 mit gleicher Länge) zählt einmal. Anzeigen ohne Video bekommen eine leere media-Liste, und das Transkript wird nicht berechnet.

KI-Auswertung

include=ai ergänzt ai:

Feld Was es ist
summary Ein oder zwei Sätze: was die Anzeige zeigt und verspricht
hook Die ersten Worte, so wie der Betrachter sie wahrnimmt, in der Sprache der Anzeige
hook_type question, bold_claim, problem, offer, social_proof, curiosity, demonstration, testimonial, news oder other
angles Verkaufsargumente, z. B. price, convenience, trust, status
emotions Emotionen, die die Anzeige anspricht, z. B. excitement, fear_of_missing_out
audience Wen die Anzeige anspricht
style ugc, talking_head, studio, product_demo, animation, slideshow, static_image, text_only oder other
cta, offer Wozu der Betrachter aufgefordert wird, und das Angebot; leer, wenn es keins gibt
language Hauptsprache der Anzeige
model, with_transcript Welches Modell sie geschrieben hat und ob es das Transkript gelesen hat

Die KI-Auswertung stützt sich nur auf das, was in der Anzeige steckt: ihren Text, den eingeblendeten Text, ihr erstes Bild oder Frame und, mit include=transcript,ai, das Gesprochene. Alles in Basis und Transkript sind Daten, die du prüfen kannst. Die KI-Auswertung ist eine Interpretation. Nutz sie zum Sortieren und Zusammenfassen, nicht als Beleg.

Während die Auswertung läuft

Reine Textanzeigen und die meisten Bilder antworten sofort. Videos und Transkripte dauern länger: Ist die Arbeit nicht innerhalb weniger Sekunden fertig, antwortet der Aufruf direkt mit 202 Accepted, statt dich warten zu lassen. Das ist kostenlos:

JSON
{ "data": null, "meta": { "ad_id": "tiktok:1877821189943761", "status": "processing", "pending": "transcript", "retry_after": 10, "cached": false } }

pending sagt, an welchem Teil gerade gearbeitet wird. Die Arbeit läuft weiter. Ruf dieselbe URL nach retry_after Sekunden noch mal auf (steht auch im Header Retry-After), dann bekommst du 200 mit meta.status = ready. Die SDKs für Node und Python, die n8n-Node und der MCP-Server fragen selbst noch mal nach.

Kosten und Caching

Credits werden berechnet, wenn die Daten geliefert werden, nie für ein 202. meta.credits schlüsselt sie nach Teilen auf. Ein Teil, der fehlschlägt, steht in meta.errors und wird nicht berechnet. Der Rest der Antwort ist trotzdem da. Ergebnisse werden pro Anzeigenversion gespeichert: Ein wiederholter Aufruf antwortet aus dem Speicher, ein geändertes Creative wird neu analysiert. Aufrufe, bei denen nichts analysiert werden konnte (kein Text, keine erreichbaren Medien), kosten nichts. Ist die Anzeige noch nicht in unserem Archiv, kommt für den Live-Abruf der Preis der Anzeige dazu.

Was du damit machen kannst

  • Ein Creative-Team mit Belegen briefen. Hol die Merkmale der am längsten laufenden Anzeigen eines Wettbewerbers (GET /v1/search?source=history&sort=days_running) und vergleich Hooks, Angebote, Videolängen und das, was in den ersten drei Sekunden gesagt wird.
  • Ein Swipe File sortieren. ai.hook_type, ai.angles und ai.style gruppieren Hunderte Anzeigen in einem Durchgang. Transkript und Timeline des eingeblendeten Texts zeigen, was jede tatsächlich sagt.
  • Erkennen, was getestet wird. Anzeigen mit derived.stage: testing sind neu und unbewiesen. proven-Anzeigen haben zwei oder mehr Signale, etwa eine lange Laufzeit, mehrere Varianten oder hohe EU-Reichweite. Die Merkmale beider zeigen, was es vom Test bis zur Skalierung geschafft hat.
  • Einen Agenten fragen. Das MCP-Tool get_ad_features liefert dieselben Daten und nimmt dieselben Optionen. So kann Claude eine Anzeige mit Zitaten erklären statt mit Vermutungen.