Ads

Envoyer images et vidéos vers Meta Ads, Google Ads et TikTok Ads via l'API

Un appel livre une image ou une vidéo, par URL, au compte publicitaire du client et renvoie ce que les annonces utilisent pour référencer le fichier : le hash de l'image ou l'id de la vidéo. Vous envoyez une fois et réutilisez dans autant d'annonces que vous voulez, sans implémenter l'API Meta. Sur Google Ads, la route est POST /ads/google_adwords/media et la réponse porte l'asset_id. Sur TikTok Ads, la route est POST /ads/tiktok_ads/media et la réponse porte l'image_id de l'image ou l'id de la vidéo.

L'appel

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

Ce que vous pouvez faire

  • Envoyer une image JPEG ou PNG par URL avec POST /ads/facebook_ads/media et type: image, et recevoir le hash.
  • Envoyer une vidéo par URL avec type: video et recevoir l'id.
  • Utiliser l'URL renvoyée par POST /media, qui envoie le fichier et renvoie l'adresse publique.
  • Suivre le traitement de la vidéo avec GET /ads/facebook_ads/videos/{id}, qui renvoie status et thumbnail_url.
  • Réutiliser le même hash ou id dans plusieurs annonces, comme les versions feed et stories d'un même visuel.
  • Sur Google Ads, envoyer une image avec POST /ads/google_adwords/media et recevoir l'asset_id, prête tout de suite.
  • Sur Google Ads, importer une vidéo YouTube par son lien, prête tout de suite, ou envoyer un fichier vidéo, publié sur YouTube en non répertorié.
  • Sur Google Ads, lister les images et les vidéos YouTube déjà dans le compte avec GET /ads/google_adwords/library, avec l'asset_id, pour ne pas les renvoyer.
  • Sur TikTok Ads, envoyer la vidéo et sa couverture avec POST /ads/tiktok_ads/media, suivre la vidéo avec GET /ads/tiktok_ads/videos/{id} et lister ce que le compte a déjà avec GET /ads/tiktok_ads/library.

Règles et limites

  • Idempotency-Key est obligatoire et va toujours dans le header. Générez-la une fois et renvoyez la même clé lors des nouvelles tentatives. Répéter la même requête renvoie 200 avec Idempotent-Replay: true.
  • L'image est prête immédiatement. La vidéo démarre en processing et ne doit aller dans une annonce que lorsque le status est ready.
  • Le status de la vidéo peut être processing, ready ou failed. thumbnail_url est une image choisie par le réseau, utilisée comme miniature de l'annonce.
  • GET /ads/facebook_ads/videos/{id} ne répond que pour les vidéos que ce compte a reçues via POST /ads/facebook_ads/media. Tout autre id donne 404.
  • Connect ne stocke pas le fichier : conservez le hash ou l'id de votre côté. Si une annonce utilise une vidéo encore en traitement, la réponse est 409 ads_video_not_ready, et réessayer avec la même clé reprend.
  • Sur Google Ads, une vidéo envoyée en fichier démarre en processing, et GET /ads/google_adwords/videos/{id} indique quand elle est ready et renvoie l'asset_id. L'envoi sur YouTube doit finir en 60 secondes : pour une grande vidéo, publiez-la sur YouTube et envoyez le lien.
  • Sur TikTok Ads, TikTok télécharge le fichier depuis l'URL. Une image revient ready avec son image_id ; une vidéo commence en processing, et TikTok met en général de 30 secondes à 5 minutes à la rendre ready.

Champs principaux

ChampTypeObligatoireDescription
typestringOuiimage ou video.
urlstringOuiAdresse https publique du fichier, par exemple l'URL renvoyée par POST /media. Image : JPEG ou PNG.
namestringNonNom dans la bibliothèque du compte. Sans lui, le nom du fichier dans l'URL.
Idempotency-KeystringOuiHeader obligatoire, 255 caractères maximum. Générez-la une fois et renvoyez la même à chaque nouvelle tentative.
hashstringNonDans la réponse, image uniquement : ce que l'annonce utilise pour la référencer. Meta Ads uniquement.
idstringNonDans la réponse, vidéo uniquement : l'id utilisé par l'annonce. C'est aussi l'{id} de GET /ads/facebook_ads/videos/{id}.
statusstringNonDans la réponse : ready ou processing. Sur le GET de la vidéo, aussi failed.
asset_idstringNonDans la réponse, sur Google Ads : ce que l'annonce utilise dans google_adwords.images, logo_asset_ids et video_asset_ids.
video_idstringNonDans la réponse, sur Google Ads, vidéo uniquement : l'id de la vidéo sur YouTube.
image_idNonDans la réponse, sur TikTok Ads, pour une image : ce que l'annonce utilise dans tiktok_ads.cover_image_id.

Pour qui

  • Bibliothèque de visuels du client

    Un SaaS publicitaire envoie les visuels du client une fois et garde le hash et l'id pour créer des annonces sans renvoyer le fichier.

  • Annonce avec versions feed et stories

    Une agence envoie deux fichiers, un par emplacement, et référence chacun dans la même annonce.

  • Agent IA qui génère des vidéos

    Un agent génère une vidéo, l'envoie par URL, attend le status ready et crée seulement ensuite l'annonce.

Fonctionne avec

  • Meta Ads
  • Google Ads
  • TikTok Ads

Questions fréquentes

Faut-il attendre le traitement de la vidéo avant de créer l'annonce ?

Oui. La vidéo démarre en processing. Consultez GET /ads/facebook_ads/videos/{id} et utilisez l'id dans l'annonce quand le status est ready. Si vous l'utilisez avant, la réponse est 409 ads_video_not_ready et vous réessayez avec la même Idempotency-Key.

Est-ce que ça fonctionne avec Google Ads et TikTok Ads ?

Oui. Utilisez POST /ads/google_adwords/media : la réponse porte l'asset_id, que l'annonce Google utilise. Un lien YouTube est importé et revient ready ; toute autre vidéo est envoyée sur YouTube, en non répertorié, et est prête quand GET /ads/google_adwords/videos/{id} indique ready. Sur TikTok Ads, utilisez POST /ads/tiktok_ads/media : la couverture revient avec son image_id et la vidéo avec son id, que l'annonce utilise quand GET /ads/tiktok_ads/videos/{id} indique ready.

Connect stocke-t-il l'image ou la vidéo ?

Non. Il livre le fichier au compte publicitaire et renvoie le hash ou l'id. Conservez cette valeur de votre côté pour la réutiliser dans les annonces.

Voir aussi

Voir tout ce que vous pouvez faire avec Ads

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.