Publish GIFs to X and Facebook
Publish a hosted or local GIF to X and Facebook, compare official platform support with UniPost support, and convert GIFs for destinations that require video to preserve GIF animation.
Platform support
Direct GIF publishing is available in UniPost today for X and Facebook Pages. Other destinations fall into two groups: LinkedIn and Threads have upstream GIF capabilities that UniPost has not connected yet, while the remaining platforms need a video-based workflow instead of an unchanged GIF file.
| Platform | Official GIF support | UniPost status | Recommended action |
|---|---|---|---|
| X / Twitter | Yes — direct GIF media upload | Supported | Publish the GIF directly. |
| Facebook Page | Yes — GIF photo post | Supported | Publish the GIF directly. |
| Yes — through LinkedIn image APIs | Coming soon | Wait for native UniPost GIF support. | |
| Threads | Yes — through provider-backed GIF attachments | Coming soon | Wait for UniPost GIF attachment support. |
| No direct GIF publishing surface | GIF-to-MP4 conversion available; destination-specific publishing guidance coming soon | Convert the GIF to MP4, then use the destination's video workflow. | |
| TikTok | No direct GIF publishing surface | GIF-to-MP4 conversion available; destination-specific publishing guidance coming soon | Convert the GIF to MP4, then use the destination's video workflow. |
| No direct animated GIF publishing surface in the supported organic Pin API flow | GIF-to-MP4 conversion available; destination-specific publishing guidance coming soon | Convert the GIF to MP4, then use the destination's video workflow. | |
| YouTube | No GIF post type; publishing requires video media | GIF-to-MP4 conversion available; destination-specific publishing guidance coming soon | Convert the GIF to MP4, then use the destination's video workflow. |
| Bluesky | No direct GIF media type in the documented image and video embed APIs | GIF-to-MP4 conversion available; destination-specific publishing guidance coming soon | Convert the GIF to MP4, then use the destination's video workflow. |
Choose the media source
Use the recommended platform_posts[] request shape so each destination has its own account, caption, and media fields. UniPost accepts either of these GIF sources:
| Source | Request field | Workflow |
|---|---|---|
| Public hosted GIF | platform_posts[].media_urls | Send a direct, publicly reachable URL whose path ends in .gif. Query strings are allowed. |
| Local .gif file | platform_posts[].media_ids | Reserve an upload, PUT the file bytes, wait for the media row, then publish its media_id. |
Find destination IDs with GET/v1/accounts. If the accounts are not connected yet, complete the relevant X or Facebook connection flow before creating the post.
Publish a hosted GIF
If the GIF already has a stable public URL, send it directly in media_urls. The same URL can be reused for the X and Facebook destinations, while each platform post can keep a different caption.
The URL path must end in .gif; Query strings are allowed. If your CDN provides an extensionless URL, upload it and use media_ids instead so UniPost can identify the stored content as image/gif.
Validate with POST/v1/posts/validate, then publish the identical payload with POST/v1/posts.
Publish a local GIF
Local files use the media library. Reserve the upload with POST/v1/media, upload the raw bytes to the returned upload_url, and poll GET/v1/media/:media_id until the status is uploaded or attached.
After publishing, the create response is asynchronous. Poll GET/v1/posts/:post_id and inspect each result row for the final X and Facebook outcome.
X and Facebook limits
| Rule | X / Twitter | Facebook Page |
|---|---|---|
| GIF count | Exactly one GIF | Exactly one GIF |
| UniPost file-size cap | 5 MB | 10 MB |
| Mixed media | Do not combine the GIF with images or video | Do not combine the GIF with other media |
| Links | Caption URLs follow normal X post behavior | Do not combine Facebook link options with media |
| Scheduling | UniPost scheduling is supported | Publish the Facebook GIF immediately |
scheduled_at when the request contains a Facebook GIF.POST /v1/posts/validatedoes not currently enforce X's one-GIF-only rule or reject a GIF combined with another image. Send exactly one GIF as the only X media item; otherwise X can reject the post after UniPost queues it.Convert a GIF for video destinations
LinkedIn and Threads require native integrations with their upstream GIF capabilities. UniPost will add those destination-specific paths without pretending that the platforms themselves reject GIFs.
To preserve animation on Instagram, TikTok, Pinterest, YouTube, and Bluesky, convert the GIF to video media. Upload the GIF with POST/v1/media, create a job with POST/v1/media/gif-conversions, and poll GET /v1/media/gif-conversions/{id}. A successful job returns an MP4 output_media_id.
Conversion does not publish, edit a draft, or replace the original GIF. Use the returned Media ID in a normal video publishing request after validating the selected destination. Destination-specific publishing guides and the Dashboard conversion control are still coming soon.
Common errors
| Code or state | What it means | How to fix it |
|---|---|---|
| unsupported_format | The GIF targets a destination that UniPost does not currently support for direct GIF publishing. | Target X or Facebook directly, or convert the GIF to MP4 before using a video destination. |
| file_too_large | The GIF exceeds a destination's UniPost file-size limit. | Use 5 MB or smaller when one request targets both X and Facebook. |
| media_not_uploaded | A local media_id is still pending. | PUT the GIF bytes, then poll GET/v1/media/:media_id until the media is ready. |
| mixed_media_unsupported | The request combines image-family media with video. | Do not combine the GIF with video. X and Facebook each require the GIF to be the only media item. |
| facebook_scheduled_media_unsupported | The Facebook GIF request includes scheduled_at. | Remove scheduled_at and publish the Facebook GIF immediately. |
| Asynchronous destination failure | UniPost accepted and queued the post, but X or Facebook later rejected delivery. | Poll GET/v1/posts/:post_id and inspect the failed destination's structured error fields. |