OMomnisocials
Media

Upload a file

Changed on

Upload an image or video, or a PDF. A PDF is rasterized into one image slide per page and returned as a carousel (see PdfUploadResult): pass all of media_ids to POST /posts. On LinkedIn the slides post as a native swipeable document; on Instagram, TikTok, Threads and Pinterest as an image carousel. PDFs are capped at 20 pages.

post/media/upload

Request

  • Base URL
    https://api.omnisocials.com/v1
  • URL
    https://api.omnisocials.com/v1/media/upload
  • Auth
    HTTP bearer

Request body multipart/form-data

filestring binary required

The file to upload: an image, video, or PDF (max 100MB). Per-platform caps apply at scheduling: Mastodon 99MB, Bluesky 100MB, X 512MB (free tier), Threads/Reddit 1GB, Pinterest 2GB, Facebook/Instagram/TikTok 4GB, LinkedIn 5GB, YouTube 256GB. A PDF is split into image slides (max 20 pages) and returned as a carousel.

namestring

Optional human-readable label (e.g. "pp-play5get50") so the asset is findable by name later. If the same bytes were already uploaded, the existing file is returned and labelled with this name.

folderstring

Optional folder name to file the asset under (created at the top level if it does not exist). Use folder_id instead to target an existing folder.

folder_idstring

Optional id of an existing folder to file the asset under.

pdf_mode'slides' | 'document'

PDF uploads only. slides (default): one image media item per page, one id each; pass ALL of media_ids to POST /posts. document: ONE media item for the whole PDF (type document, its pages in pdf.pages); pass its single id in media_ids and the post gets every page, in order. Both modes keep the original file, which LinkedIn receives when the pages are posted unchanged.

Example request

{
  "name": "autumn-menu-hero",
  "folder": "Autumn campaign",
  "folder_id": "12"
}

Response

File uploaded successfully. For an image or video the body has a single data (Media). For a PDF the body is a PdfUploadResult with slides + media_ids for the whole carousel.

OR

Example response

{
  "data": {
    "id": "482913",
    "url": "https://cdn.omnisocials.com/file/library-omnisocials/312a658f-2b45-4289-b240-890807221a74/library/1792573200000-k3j9xq_0c9e6b1a-2f4d-4b8e-a7c3-9d1e5f6a2b70.jpg",
    "thumbnail_url": "https://cdn.omnisocials.com/file/library-omnisocials/312a658f-2b45-4289-b240-890807221a74/library/thumbnails/1792573200000-k3j9xq_0c9e6b1a-2f4d-4b8e-a7c3-9d1e5f6a2b70_thumbnail.webp",
    "name": "autumn-menu-hero",
    "folder_id": "12",
    "filename": "0c9e6b1a-2f4d-4b8e-a7c3-9d1e5f6a2b70.jpg",
    "size": "2.50 MB",
    "created_at": "2026-10-20T14:32:10.000Z",
    "pdf": {
      "id": "9a7e3c1f-5b2d-4e8a-b6c4-1f3d5e7a9b20",
      "name": "deck.pdf",
      "url": "https://cdn.omnisocials.com/file/library-omnisocials/312a658f-2b45-4289-b240-890807221a74/library/1792573200000-p7m2wd_9a7e3c1f-5b2d-4e8a-b6c4-1f3d5e7a9b20.pdf",
      "page": 1,
      "total_pages": 8,
      "rendered_pages": 8,
      "pages": [
        {
          "url": "https://cdn.omnisocials.com/file/library-omnisocials/312a658f-2b45-4289-b240-890807221a74/library/1792573200000-p7m2wd_4c2e8a6f-1d3b-4f5a-9e7c-0b2d4f6a8c13.png",
          "width": 1080,
          "height": 1350
        }
      ]
    }
  },
  "compatibility": {
    "warnings": [
      {
        "platform": "instagram",
        "display_name": "Instagram",
        "reasons": [
          "max 300 MB"
        ]
      }
    ],
    "summary": "This file (450 MB) won't post to: Instagram (max 300 MB)."
  },
  "message": "File uploaded successfully. Use the 'id' in your post request."
}

Changes

  • d28eab4dda4eRevision changes
    • info

      added the non-success response with the status

  • a2a4ef9be162Revision changes
    • warning

      added the new document enum value to the ///// response property for the response status

    • warning

      added the new document enum value to the ////// response property for the response status

    • warning

      added the new document enum value to the // response property for the response status

    • info

      added the new optional request property

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property // to the response with the status