upload_media
Upload media to the library. Three methods supported:
url — import from a PUBLIC https URL (e.g. a hosted image link). NEVER pass a local sandbox path — the URL must be reachable from our servers.
base64_data — pass base64-encoded file data directly. ONLY use this for tiny files (≲50 KB). MCP tool inputs are token-capped — anything larger gets silently truncated and uploads a corrupted file. For any user-pasted image, use upload_url instead.
upload_url — PREFERRED for any file the user attached to the chat. Call with method="upload_url" to get a one-time presigned URL plus a ready-to-run snippet. Execute the snippet in your code-execution tool against the actual file path. The response JSON contains the media id you pass to create_post.
Size limits: base64/direct uploads are capped at 100 MB. For anything larger — up to 1 GB — use a public url (fetched server-side, bypasses the cap), OR have the user upload the file in the OmniSocials Library UI at https://app.omnisocials.com/library . IMPORTANT: if the user has a large LOCAL file (over ~100 MB) with no public url, do NOT tell them to compress it — point them to the Library UI link above. Large videos (over 100 MB) are processed in the background — the response status is "processing" and the file is NOT usable in a post until it becomes "ready" (re-check with list_media).
Compatibility: every upload response includes a "compatibility" summary of any CONNECTED platforms that would reject the file (e.g. too large for Instagram). If there are warnings, RELAY them and ask the user whether to continue before posting — the file still uploads and can post to platforms that accept it. To check BEFORE uploading, call check_media_compatibility first.
PDF = carousel: upload a PDF (via a public url, or base64_data with mime_type "application/pdf", or the upload_url snippet) and it is split into one image slide per page (max 20). The response lists a Media ID for EVERY slide — pass ALL of them, in order, as media_ids to create_post to post the deck as a carousel. On LinkedIn the slides post as a native swipeable DOCUMENT made from the ORIGINAL PDF file (the file is kept: text stays sharp, in-document links work, viewers download the real file, and every page is included even past the 20-slide cap) as long as the slides are posted unchanged and in order; on Instagram, TikTok, Threads and Pinterest as an image carousel. Set linkedin.document_source to 'slides' on the post to send a document rebuilt from the slide images instead. This is how a user posts an existing slide deck (Canva/PowerPoint/Figma exported to PDF) as a carousel. Prefer pdf_mode "document" when the user wants ONE library item for the deck (no per-page clutter): the response then has a single Media ID whose media_ids entry expands into every page at post time.
Supported: JPEG, PNG, GIF, WebP, MP4, MOV, AVI, PDF.
For user-attached files: ALWAYS try upload_url first. Call upload_media with method="upload_url", then in your code-execution sandbox run the returned Python (ChatGPT Code Interpreter, file at /mnt/data/) or curl (Claude Code Execution) snippet against the actual file path. Only react to a failure AFTER actually executing the snippet.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL of the media file (method=url). Use this when the user pasted an image link or you generated one via DALL·E. | |
| file | No | OpenAI Apps SDK file reference. Set when the user attached a file in ChatGPT — the platform fills this in automatically. | |
| name | No | Human-readable label so you can find this asset by name later instead of re-uploading it, e.g. "pp-play5get50". Strongly recommended on every upload. | |
| folder | No | Optional folder name to file this asset under (created at the top level if it does not exist), e.g. "win-graphics". Use list_folders to see existing folders. | |
| method | No | Upload method: "file" (ChatGPT user-attached image — preferred), "url", "base64_data", or "upload_url". Auto-detected from which arg you pass. | |
| filename | No | Optional filename with extension | |
| pdf_mode | No | PDF uploads only. "slides" (default): one image media item per page, one Media ID each (pass ALL of media_ids to create_post). "document": ONE media item for the whole PDF (type "document"); pass its single Media ID in media_ids and the post gets every page in order. Both keep the original file, which LinkedIn receives. For method="upload_url", send it as a form field: -F pdf_mode=document. | |
| mime_type | No | MIME type (e.g. 'image/jpeg'). Required for base64_data and upload_url. | |
| base64_data | No | Base64-encoded file data (method=base64_data). Only safe for files <50 KB. |