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.
curl "https://api.adlibapi.com/v1/ads/meta:1332991018770312/features?include=transcript,ai" \
-H "X-API-Key: $ADLIB_API_KEY"{
"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:
{ "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.anglesyai.styleagrupan 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: testingson nuevos y aún no están probados. Losprovenreú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_featuresdevuelve los mismos datos y acepta las mismas opciones, así que Claude puede explicarte un anuncio con citas en lugar de suposiciones.