Skip to main content
A post’s media is a list of files of three types: image, video and document (PDF). You can hand a file to TryPost in several ways; pick the one that fits where the file lives.

​
Accepted files

HEIC and HEIF photos are accepted too when the server can convert them, and are stored as JPEG. These are the caps for any upload. Each network has its own, usually smaller, limits on count, size, duration and aspect ratio, checked when the post is scheduled or published. List content types returns them per content type (max_media_count, max_image_bytes, max_video_bytes, max_video_duration_sec, …), and each network page lists them, for example Instagram, TikTok or LinkedIn. A file whose type the channel does not accept is refused with 422.

​
Media on create and update

Create post, Create posts in batch and Update post take a media list. Each item gives exactly one source:
The order of the list is the order of the media in the post. On Update post, media replaces the post’s media; omit it to keep the current media.

​
Upload a file

Create upload takes one file as multipart/form-data, without a post, and returns an upload_token:
Use the token as a media item ({ "upload_token": "..." }) on create or update, or attach it to an existing post with Attach media from upload:
  • A token is single use: the first post that takes it consumes it. To put the same file on a second post, pass that post’s media[].id.
  • Use it before expires_at, 24 hours after the upload. Unused uploads are then deleted, and a spent or expired token fails with 422: This upload expired. Add the file again.
To upload straight to a post that already exists, Upload media does both steps in one call:
Both append the file to the end of the post’s media and return the post.

​
Attach from URLs

Attach media from URL downloads 1 to 10 files and appends them to a post:
Each URL must serve the file itself. Redirects are not followed, web pages and private-network hosts are refused, and each download has 20 seconds to finish. Only types the post’s channel accepts are kept. The call succeeds even when some URLs fail, so check the result:
reason is one of unreachable, type_not_allowed, too_large or host_not_allowed. A media[].url item on create or update is downloaded the same way: no redirects, no private-network hosts. Unlike this call, a URL that fails there fails the whole request with 422.

​
Reuse media from another post

There is no separate media library in the API. To reuse a file, take the id of an item in another post’s media (from Get post or List posts) and pass it as { "id": "..." }. TryPost copies the file, so deleting either post leaves the other’s media intact.

​
Signed upload URLs

AI assistants connected through the MCP server cannot send file bytes over MCP. The request-media-upload-tool gives them a one-time signed URL instead, and the file goes to Upload to signed URL without an API key; the signature authorizes the request:
  • The URL works once, until it expires (15 minutes by default). A second upload to it returns 409.
  • The response holds an upload_token, used like a token from Create upload.
Scripts holding an API key do not need this flow: use Create upload.

​
Alt text and media settings

Each media item takes optional settings:

​
Which posts take media

Media can be added and replaced until the post goes out. Posts that are publishing, published, partially_published or failed cannot take media: the API answers 422 with This post has already been processed and cannot be re-published. Duplicate it to try again.