How does an AI agent upload images and videos?

An AI agent has two ways to get a file into your Media library: import it from a public link, or upload the bytes itself in three steps. Either way it gets back a media ID, which it attaches to a post with media_ids.

From a public link (simplest)#

1. The agent calls upload_media_from_url with the file's public HTTPS address.
2. Images (JPEG, PNG, GIF, WebP, HEIC, HEIF) up to 25 MB are imported at once. The media ID is ready to use immediately.
3. Videos (MP4 only) up to 4 GB are imported in the background. The agent gets a media ID with status uploading, then checks get_media until the status is ready. If it becomes failed, get_media says why (too large, not an MP4, out of storage, link not reachable).

The link must be reachable from the public internet. Private or local addresses are refused.

A local file (three steps)#

Use this when the file is on the agent's machine and has no public link, for example a PDF for a LinkedIn document post.

1. create_media_upload with the filename, content type and size in bytes. It returns a media ID and a short-lived upload address.
2. The agent sends the file to that address the way the response says: a direct PUT for videos and PDFs, or a multipart form for images.
3. complete_media_upload with the media ID. PostEverywhere checks the file arrived and matches its type.

Accepted types: JPEG, PNG, GIF, WebP, HEIC, MP4 and PDF. Images and PDFs up to 20 MB, videos up to 4 GB.

AI images#

generate_image makes an image from a prompt and saves it to your Media library, ready for media_ids. It uses AI credits and needs the AI scope. It is not available in the Claude directory listing or the ChatGPT app. See What are AI credits and how do they work?.

Attaching and reusing media#

• Pass the media IDs to create_post in media_ids. Each platform's limit on how many files a post can carry is enforced, not trimmed: for example Pinterest takes one video or up to five images, and more is refused with a message that names the limit.
• Files already in your library can be reused. list_media finds them (filter by image, video or document) and get_media shows size, dimensions and status. Nothing needs uploading twice.
• Only attach a video whose status has reached ready.

Deleting media and storage#

Uploaded files count against your plan's storage. delete_media removes a file and frees that space. If a post that has not gone out yet uses the file, the call is refused with media_in_use and says how many posts use it. Deleting anyway with force: true cancels those posts, so the agent should ask you first. See How much storage do I get and how is it counted?.

Limits#

• There is no cap on how much media you upload. Very fast bursts of uploads can be rate limited for a moment; the API tells your agent when to retry.
• A file that does not fit your remaining storage is refused with a message that says how much you are using. Delete unused media, add storage in Settings > Billing, or upgrade.

Developer detail: media requirements and error codes.