Ads
Subir imágenes y videos a Meta Ads, Google Ads y TikTok Ads con la API
Una llamada entrega una imagen o un video, por URL, a la cuenta de anuncios del cliente y devuelve lo que los anuncios usan para referenciar el archivo: el hash de la imagen o el id del video. Subes una vez y reutilizas en cuantos anuncios quieras, sin implementar la API de Meta. En Google Ads, la ruta es POST /ads/google_adwords/media y la respuesta trae el asset_id. En TikTok Ads, la ruta es POST /ads/tiktok_ads/media y la respuesta trae el image_id de la imagen o el id del video.
La llamada
POST /api/ads/facebook_ads/media?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"type": "video",
"url": "https://midias.reportei.com/connect-media/media/<file>.mp4",
"name": "Spring launch"
}Qué puedes hacer
- Subir una imagen JPEG o PNG por URL con POST /ads/facebook_ads/media y type: image, y recibir el hash.
- Subir un video por URL con type: video y recibir el id.
- Usar la URL devuelta por POST /media, que sube el archivo y devuelve la dirección pública.
- Seguir el procesamiento del video con GET /ads/facebook_ads/videos/{id}, que trae status y thumbnail_url.
- Reutilizar el mismo hash o id en varios anuncios, como la versión de feed y la de stories de un mismo creativo.
- En Google Ads, subir una imagen con POST /ads/google_adwords/media y recibir el asset_id, lista al instante.
- En Google Ads, importar un video de YouTube por el enlace, listo al instante, o subir un archivo de video, que va a YouTube como no listado.
- En Google Ads, listar las imágenes y los videos de YouTube que ya están en la cuenta con GET /ads/google_adwords/library, con el asset_id, para no subirlos de nuevo.
- En TikTok Ads, enviar el video y la portada con POST /ads/tiktok_ads/media, seguir el video con GET /ads/tiktok_ads/videos/{id} y listar lo que la cuenta ya tiene con GET /ads/tiktok_ads/library.
Reglas y límites
- Idempotency-Key es obligatorio y va siempre en el header. Genéralo una vez y reenvía la misma clave en los reintentos. Repetir el mismo pedido devuelve 200 con Idempotent-Replay: true.
- La imagen queda lista al instante. El video empieza en processing y solo debe ir en un anuncio cuando el status sea ready.
- El status del video puede ser processing, ready o failed. thumbnail_url es un fotograma elegido por la red, usado como miniatura del anuncio.
- GET /ads/facebook_ads/videos/{id} solo responde por videos que esta cuenta recibió por POST /ads/facebook_ads/media. Cualquier otro id da 404.
- Connect no guarda el archivo: guarda el hash o el id de tu lado. Si un anuncio usa un video aún en procesamiento, la respuesta es 409 ads_video_not_ready, y repetir con la misma clave retoma.
- En Google Ads, un video subido como archivo empieza en processing, y GET /ads/google_adwords/videos/{id} indica cuándo queda ready y devuelve el asset_id. La subida a YouTube debe terminar en 60 segundos: para un video grande, publícalo en YouTube y envía el enlace.
- En TikTok Ads, TikTok descarga el archivo de la URL. La imagen vuelve ready con el image_id; el video empieza en processing, y TikTok suele tardar de 30 segundos a 5 minutos en dejarlo ready.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| type | string | Sí | image o video. |
| url | string | Sí | Dirección https pública del archivo, por ejemplo la URL devuelta por POST /media. Imagen: JPEG o PNG. |
| name | string | No | Nombre en la biblioteca de la cuenta. Sin él, el nombre del archivo en la URL. |
| Idempotency-Key | string | Sí | Header obligatorio, hasta 255 caracteres. Genéralo una vez y reenvía el mismo en cada reintento. |
| hash | string | No | En la respuesta, solo imagen: lo que el anuncio usa para referenciarla. Solo en Meta Ads. |
| id | string | No | En la respuesta, solo video: el id que usa el anuncio. También es el {id} de GET /ads/facebook_ads/videos/{id}. |
| status | string | No | En la respuesta: ready o processing. En el GET del video, también failed. |
| asset_id | string | No | En la respuesta, en Google Ads: lo que el anuncio usa en google_adwords.images, logo_asset_ids y video_asset_ids. |
| video_id | string | No | En la respuesta, en Google Ads, solo video: el id del video en YouTube. |
| image_id | No | En la respuesta, en TikTok Ads, para imagen: lo que el anuncio usa en tiktok_ads.cover_image_id. |
Para quién
Biblioteca de creativos del cliente
Un SaaS de anuncios sube los creativos del cliente una vez y guarda el hash y el id para armar anuncios sin reenviar el archivo.
Anuncio con versiones de feed y stories
Una agencia envía dos archivos, uno por ubicación, y referencia cada uno en el mismo anuncio.
Agente de IA que genera videos
Un agente genera un video, lo envía por URL, espera el status ready y solo entonces crea el anuncio.
Funciona con
Meta Ads
Google Ads
TikTok Ads
Preguntas frecuentes
¿Debo esperar a que el video se procese antes de crear el anuncio?
Sí. El video empieza en processing. Consulta GET /ads/facebook_ads/videos/{id} y usa el id en el anuncio cuando el status sea ready. Si lo usas antes, la respuesta es 409 ads_video_not_ready y repites con la misma Idempotency-Key.
¿Funciona con Google Ads y TikTok Ads?
Sí. Usa POST /ads/google_adwords/media: la respuesta trae el asset_id, que usa el anuncio de Google. Un enlace de YouTube se importa y vuelve ready; otro video se sube a YouTube, no listado, y queda listo cuando GET /ads/google_adwords/videos/{id} diga ready. En TikTok Ads, usa POST /ads/tiktok_ads/media: la portada vuelve con el image_id y el video con el id, que el anuncio usa cuando GET /ads/tiktok_ads/videos/{id} diga ready.
¿Connect guarda la imagen o el video?
No. Entrega el archivo a la cuenta de anuncios y devuelve el hash o el id. Guarda ese valor de tu lado para reutilizarlo en anuncios.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
