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
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | image or video. |
| url | string | Yes | Public https address of the file, for example the URL returned by POST /media. Image: JPEG or PNG. |
| name | string | No | Name in the account's library. Without it, the file name in the URL. |
| Idempotency-Key | string | Yes | Required header, up to 255 characters. Generate it once and resend the same one on every retry. |
| hash | string | No | In the response, image only: what the ad uses to reference it. Meta Ads only. |
| id | string | No | In the response, video only: the id the ad uses. It is also the {id} of GET /ads/facebook_ads/videos/{id}. |
| status | string | No | In the response: ready or processing. On the video GET, also failed. |
| asset_id | string | No | In the response, on Google Ads: what the ad uses in google_adwords.images, logo_asset_ids and video_asset_ids. |
| video_id | string | No | In the response, on Google Ads, video only: the video's YouTube id. |
| image_id | No | In 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
