Skip to content
UGC API
Get API key

Fit to platform: send any file, once

You send one file and one caption. UGC API checks each destination's rules and makes a version that fits: JPEG for Instagram, the right aspect ratio, captions within limits. Anything it changes or skips is listed in warnings, and a dry run shows them before anything posts.

Updated

What it does for you

DestinationPlatform ruleWhat UGC API does
Instagram posts and carouselsJPEG only, aspect 4:5 to 1.91:1Converts PNG and WebP to JPEG; pads (or crops) images outside the range
Instagram carouselsUp to 10 imagesUses the first 10 and tells you
Instagram StoriesJPEG imagesConverts PNG and WebP to JPEG
Instagram captions2,200 characters, 30 hashtagsKeeps the first 30 hashtags, trims at a word
TikTok photo postsJPEG or WebPConverts PNG to JPEG
TikTok video3 seconds to 10 minutesSkips the account for clips outside it
Facebook Reels3–90 secondsSkips Facebook for longer clips (it doesn't post a cut version)
YouTubeVideo only; Shorts up to 3 minutesSkips YouTube for photo posts; notes when a clip will be a regular video
Any vertical placement9:16Notes landscape videos, which show with bars

Choose what happens to images that don't fit

Set options.fit on a post or in a campaign's defaults: pad (default, white bars), crop (centre crop) or skip (leave that placement out).

bash
curl https://ugcapi.dev/v1/posts \
  -H "Authorization: Bearer ugc_live_..." -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "accounts": ["acc_tt_01", "acc_ig_01", "acc_yt_01"],
    "format": "slideshow",
    "media": ["https://cdn.example.com/1.png", "https://cdn.example.com/2.webp"],
    "caption": "3 things I wish I knew",
    "options": { "fit": "crop", "tiktok": { "privacy": "PUBLIC_TO_EVERYONE" } }
  }'
json
{
  "dry_run": true,
  "credits_needed": 2,
  "warnings": [
    { "platform": "instagram", "placement": "carousel", "action": "converted", "message": "Image 1: PNG → JPEG, cropped to 4:5 for Instagram carousel." },
    { "platform": "instagram", "placement": "carousel", "action": "converted", "message": "Image 2: WEBP → JPEG for Instagram carousel." },
    { "platform": "tiktok", "placement": "photos", "action": "converted", "message": "Image 1: PNG → JPEG for TikTok photo post." },
    { "platform": "youtube", "placement": "short", "action": "skipped", "message": "YouTube takes video only (Shorts); this photo post skips YouTube." }
  ]
}

Warnings

  • converted: a version of a file was made for that placement (stored next to the original, reused for later posts).
  • adjusted: the caption or the number of images was changed to fit.
  • skipped: that placement was left out, so no credit is used for it.
  • note: nothing changed, but you may want to know (a landscape video on a vertical feed).
  • POST /v1/posts and POST /v1/campaigns both return warnings; with dry_run: true they return them without posting. If nothing is left to post, the request fails with nothing_to_publish.
Video files are checked (length, size, orientation) but not re-encoded: send H.264 MP4 or MOV. Converting video and turning photo posts into YouTube slideshows are on the roadmap.

FAQ

Do I need to resize images for Instagram?

No. Send any JPEG, PNG or WebP. UGC API makes a JPEG in Instagram's 4:5 to 1.91:1 range for Instagram and leaves the other platforms' copies as they are.

What happens to a 2-minute video sent to Facebook Reels?

Facebook Reels can be up to 90 seconds, so that account is skipped with a warning and no credit is used. The other platforms still get it.

Can I see the changes before posting?

Yes. Add dry_run: true to the same request and read warnings.

Related

DocsFormats and optionsDocsMediaDocsCampaignsDocsCreate a post