Publish GIFs to X and Facebook
Publish a hosted or local GIF to X and Facebook, compare official platform support with UniPost support, and prepare for upcoming conversion workflows.
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 | Coming soon | A UniPost GIF-to-MP4 conversion option is coming soon. | |
| TikTok | No direct GIF publishing surface | Coming soon | A UniPost GIF-to-MP4 conversion option is coming soon. |
| No direct animated GIF publishing surface in the supported organic Pin API flow | Coming soon | A UniPost GIF-to-MP4 conversion option is coming soon. | |
| YouTube | No GIF post type; publishing requires video media | Coming soon | A UniPost GIF-to-MP4 conversion option is coming soon. |
| Bluesky | No stable direct GIF file publishing path exposed by UniPost | Coming soon | A UniPost GIF-to-MP4 conversion option is coming soon. |
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 GIF URL. Do not reserve the URL in the media library. |
| 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.
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.What is coming soon
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.
Instagram, TikTok, Pinterest, YouTube, and Bluesky need a video-compatible path. A UniPost GIF-to-MP4 conversion option is coming soon so an integration can provide a GIF and publish the converted video to an eligible destination. Conversion is not available yet, and this guide does not define a future API field, quality setting, file limit, retention policy, or release date.
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, or wait for the documented coming-soon path. |
| 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 GIF was combined with another media kind. | Send the GIF as the only media item for that destination. |
| 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. |