Docs

Características creativas

El gancho, las ofertas, el formato, los cortes y el texto en pantalla de cualquier anuncio, más una transcripción opcional de lo que se dice y una lectura opcional con IA del tipo de gancho, los ángulos, las emociones y el público.

GET /v1/ads/{id}/features desmonta un anuncio en las piezas que comparan los estrategas creativos. La base siempre va incluida. La transcripción y la lectura con IA son opcionales y cuestan aparte.

Parte Cómo pedirla Qué recibes Créditos
Base siempre Gancho, precios, descuentos, urgencia, prueba social y otras etiquetas de texto con el texto exacto que las activó; formato, relación de aspecto, duración del vídeo, cortes, sonido; el texto de las imágenes y de los vídeos, con una línea de tiempo de cuándo aparece en pantalla; dominio de la landing y UTM 2
Transcripción include=transcript Lo que se dice en los vídeos, frase a frase con su inicio y su fin, y el idioma hablado +10 por minuto de vídeo empezado
Lectura con IA include=ai Un resumen, el gancho y su tipo, los ángulos de venta, las emociones, el público, el estilo de producción, la llamada a la acción y la oferta, redactados por la IA de AdLib +5

Puedes combinarlas como quieras. Con include=transcript,ai la IA también lee lo que se dice, y eso la mejora bastante en vídeos con locución. Cada parte se guarda por versión del anuncio, así que si vuelves a pedirla o añades otra parte más tarde, las demás no se rehacen.

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

Es una respuesta real, recortada. La completa trae más campos y cada línea del texto en pantalla.

Base

Campo Qué es
text.hook La primera frase del texto del anuncio, y hook_is_question
text.prices, text.discounts, text.numbers Precios, porcentajes y frases de ahorro tal como están escritos
text.urgency, social_proof, guarantee, free_offer, free_shipping, novelty Cada coincidencia trae rule y el text exacto, p. ej. {"rule": "today only", "text": "Today only"}. En inglés, alemán, francés, español, italiano, neerlandés y polaco
text.emojis, hashtags, mentions, uppercase_ratio Contados
format vertical_video, square_image, carousel, text_only, …
media[].aspect, orientation, width, height De cada imagen o vídeo
media[].duration_s, has_audio Vídeos
media[].scene_cuts, cuts_per_minute Cortes secos en el vídeo
media[].ocr.text El texto de la imagen; en los vídeos, cada texto distinto que aparece, uno por línea
media[].ocr.timeline Vídeos: cuándo está cada texto en pantalla, {"start", "end", "text"} en segundos, por orden de aparición
landing Dominio, ruta y parámetros UTM de la URL de destino

Del texto en pantalla solo se quedan las palabras leídas con una confianza del 75 % o más. Si en una imagen quedan menos de dos, su texto se descarta. Así recibes un campo vacío antes que un texto equivocado. Los tiempos de la línea de tiempo tienen una precisión de un segundo, más o menos.

Transcripción

include=transcript añade transcript.media[], una entrada por vídeo:

Campo Qué es
duration_s Duración del vídeo
language Idioma hablado (en, de, it, …); vacío si nadie habla
text Todo lo que se dice
segments[] {"start", "end", "text"} por frase, en segundos
error Aparece cuando no se pudo transcribir ese vídeo (no se cobra)

Se cobra por minuto de vídeo empezado: un anuncio de 15 segundos cuesta 10 créditos y uno de 75 segundos, 20. Si el mismo spot se renderiza para varias ubicaciones (9:16 y 1:1 con la misma duración), cuenta una sola vez. Los anuncios sin vídeo reciben una lista media vacía y no se les cobra la transcripción.

Lectura con IA

include=ai añade ai:

Campo Qué es
summary Una o dos frases: qué enseña el anuncio y qué promete
hook Las primeras palabras tal como las ve quien mira el anuncio, en su idioma
hook_type question, bold_claim, problem, offer, social_proof, curiosity, demonstration, testimonial, news u other
angles Ángulos de venta, p. ej. price, convenience, trust, status
emotions Emociones a las que apela el anuncio, p. ej. excitement, fear_of_missing_out
audience A quién se dirige el anuncio
style ugc, talking_head, studio, product_demo, animation, slideshow, static_image, text_only u other
cta, offer Qué se le pide a quien lo ve, y la oferta; vacíos si no hay
language Idioma principal del anuncio
model, with_transcript Qué modelo lo ha escrito y si ha leído la transcripción

La lectura con IA se basa solo en lo que hay en el anuncio: su texto, el texto en pantalla, su primera imagen o fotograma y, con include=transcript,ai, lo que se dice. Todo lo de la base y la transcripción son datos que puedes comprobar. La lectura con IA es una interpretación: úsala para ordenar y resumir, no como prueba.

Mientras se procesa

Los anuncios solo de texto y la mayoría de las imágenes responden al momento. Los vídeos y las transcripciones tardan más: si el trabajo no termina en unos segundos, la llamada responde enseguida con 202 Accepted en vez de dejarte esperando, y sin coste:

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

pending indica qué parte se está procesando. El trabajo sigue en marcha. Vuelve a llamar a la misma URL pasados retry_after segundos (también va en la cabecera Retry-After) y recibirás un 200 con meta.status = ready. Los SDK de Node y Python, el nodo de n8n y el servidor MCP reintentan por ti.

Coste y caché

Los créditos se cobran cuando se entregan los datos, nunca por un 202, y meta.credits los desglosa por parte. Una parte que falla aparece en meta.errors y no se cobra; el resto de la respuesta llega igual. Los resultados se guardan por versión del anuncio: una llamada repetida responde desde lo guardado, y si la creatividad cambia, se vuelve a analizar. Las llamadas en las que no se pudo analizar nada (sin texto, sin medios accesibles) no cuestan nada. Si el anuncio aún no está en nuestro archivo, traerlo en directo cuesta además el precio del anuncio.

Qué hacer con esto

  • Dale al equipo creativo un briefing con pruebas. Saca las características de los anuncios de un competidor que más tiempo llevan activos (GET /v1/search?source=history&sort=days_running) y compara ganchos, ofertas, duraciones de vídeo y lo que se dice en los tres primeros segundos.
  • Ordena un swipe file. ai.hook_type, ai.angles y ai.style agrupan cientos de anuncios de una pasada. La transcripción y la línea de tiempo del texto en pantalla muestran qué dice de verdad cada uno.
  • Detecta lo que están probando. Los anuncios con derived.stage: testing son nuevos y aún no están probados. Los proven reúnen dos o más señales, como una larga duración, varias variantes o un gran alcance en la UE. Comparar las características de ambos te enseña qué pasó de la prueba a escalar.
  • Pregúntale a un agente. La herramienta MCP get_ad_features devuelve los mismos datos y acepta las mismas opciones, así que Claude puede explicarte un anuncio con citas en lugar de suposiciones.