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

CampoTipoObligatorioDescripción
typestringSíimage o video.
urlstringSíDirección https pública del archivo, por ejemplo la URL devuelta por POST /media. Imagen: JPEG o PNG.
namestringNoNombre en la biblioteca de la cuenta. Sin él, el nombre del archivo en la URL.
Idempotency-KeystringSíHeader obligatorio, hasta 255 caracteres. Genéralo una vez y reenvía el mismo en cada reintento.
hashstringNoEn la respuesta, solo imagen: lo que el anuncio usa para referenciarla. Solo en Meta Ads.
idstringNoEn la respuesta, solo video: el id que usa el anuncio. También es el {id} de GET /ads/facebook_ads/videos/{id}.
statusstringNoEn la respuesta: ready o processing. En el GET del video, también failed.
asset_idstringNoEn la respuesta, en Google Ads: lo que el anuncio usa en google_adwords.images, logo_asset_ids y video_asset_ids.
video_idstringNoEn la respuesta, en Google Ads, solo video: el id del video en YouTube.
image_idNoEn 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.

Relacionadas

Ver todo lo que puedes hacer con Ads

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.