Ads

Upload images and videos to Meta Ads, Google Ads and TikTok Ads via API

One call delivers an image or a video, by URL, to the customer's ad account and returns what ads use to reference the file: the image hash or the video id. You upload once and reuse it in as many ads as you want, without implementing the Meta API. On Google Ads, the route is POST /ads/google_adwords/media and the response carries the asset_id. On TikTok Ads, the route is POST /ads/tiktok_ads/media and the response carries the image's image_id or the video's id.

The request

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

What you can do

  • Upload a JPEG or PNG image by URL with POST /ads/facebook_ads/media and type: image, and get the hash.
  • Upload a video by URL with type: video and get the id.
  • Use the URL returned by POST /media, which uploads the file and returns the public address.
  • Track video processing with GET /ads/facebook_ads/videos/{id}, which returns status and thumbnail_url.
  • Reuse the same hash or id across several ads, such as the feed and stories versions of one creative.
  • On Google Ads, upload an image with POST /ads/google_adwords/media and get its asset_id, ready at once.
  • On Google Ads, import a YouTube video by its link, ready at once, or upload a video file, which goes to YouTube as unlisted.
  • On Google Ads, list the images and YouTube videos already in the account with GET /ads/google_adwords/library, with their asset_id, so you don't upload them again.
  • On TikTok Ads, send the video and its cover with POST /ads/tiktok_ads/media, follow the video with GET /ads/tiktok_ads/videos/{id} and list what the account already has with GET /ads/tiktok_ads/library.

Rules and limits

  • Idempotency-Key is required and always goes in the header. Generate it once and resend the same key on retries. Repeating the same request returns 200 with Idempotent-Replay: true.
  • The image is ready immediately. The video starts as processing and should only go in an ad once the status is ready.
  • The video status can be processing, ready or failed. thumbnail_url is a frame chosen by the network, used as the ad's thumbnail.
  • GET /ads/facebook_ads/videos/{id} only answers for videos this account received via POST /ads/facebook_ads/media. Any other id is 404.
  • Connect does not store the file: keep the hash or id on your side. If an ad uses a video still processing, the response is 409 ads_video_not_ready, and retrying with the same key resumes.
  • On Google Ads, a video uploaded as a file starts as processing, and GET /ads/google_adwords/videos/{id} says when it is ready and returns its asset_id. The upload to YouTube must finish within 60 seconds: for a large video, publish it on YouTube and send the link.
  • On TikTok Ads, TikTok downloads the file from the URL. An image comes back ready with its image_id; a video starts in processing, and TikTok usually takes 30 seconds to 5 minutes to make it ready.

Main fields

FieldTypeRequiredDescription
typestringYesimage or video.
urlstringYesPublic https address of the file, for example the URL returned by POST /media. Image: JPEG or PNG.
namestringNoName in the account's library. Without it, the file name in the URL.
Idempotency-KeystringYesRequired header, up to 255 characters. Generate it once and resend the same one on every retry.
hashstringNoIn the response, image only: what the ad uses to reference it. Meta Ads only.
idstringNoIn the response, video only: the id the ad uses. It is also the {id} of GET /ads/facebook_ads/videos/{id}.
statusstringNoIn the response: ready or processing. On the video GET, also failed.
asset_idstringNoIn the response, on Google Ads: what the ad uses in google_adwords.images, logo_asset_ids and video_asset_ids.
video_idstringNoIn the response, on Google Ads, video only: the video's YouTube id.
image_idNoIn the response, on TikTok Ads, for an image: what the ad uses in tiktok_ads.cover_image_id.

Who it is for

  • Customer creative library

    An ads SaaS uploads the customer's creatives once and keeps the hash and id to build ads without resending the file.

  • Ad with feed and stories versions

    An agency uploads two files, one per placement, and references each one in the same ad.

  • AI agent that generates videos

    An agent generates a video, uploads it by URL, waits for the ready status and only then creates the ad.

Works with

  • Meta Ads
  • Google Ads
  • TikTok Ads

Frequently asked questions

Do I have to wait for the video to process before creating the ad?

Yes. The video starts as processing. Check GET /ads/facebook_ads/videos/{id} and use the id in the ad when the status is ready. If you use it earlier, the response is 409 ads_video_not_ready and you retry with the same Idempotency-Key.

Does it work with Google Ads and TikTok Ads?

Yes. Use POST /ads/google_adwords/media: the response carries the asset_id, which the Google ad uses. A YouTube link is imported and comes back ready; any other video is uploaded to YouTube, unlisted, and is ready when GET /ads/google_adwords/videos/{id} says ready. On TikTok Ads, use POST /ads/tiktok_ads/media: the cover comes back with its image_id and the video with its id, which the ad uses once GET /ads/tiktok_ads/videos/{id} says ready.

Does Connect store the image or video?

No. It delivers the file to the ad account and returns the hash or id. Keep that value on your side to reuse in ads.

Related

See everything you can do with Ads

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.