Copy page

Guides

Media

Upload and manage media files for use in posts. Every media file is stored in your workspace's media library and can be referenced by multiple posts.

Upload a file

Use POST /media/upload with a multipart form. Maximum file size is 50 MB.

Code
curl -X POST https://api.omnisocials.com/v1/media/upload \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -F "[email protected]"

Response:

Code
{
  "id": "123",
  "url": "https://cdn.omnisocials.com/workspace-42/photo.jpg",
  "type": "image",
  "mime_type": "image/jpeg",
  "size": 842311,
  "created_at": "2026-04-10T14:22:00Z"
}

Save the id. You reference media on posts by ID through the media_ids field.

Upload from a URL

Skip the download-and-reupload dance by pointing OmniSocials at a public URL. The server fetches the file and stores it in your media library.

Code
curl -X POST https://api.omnisocials.com/v1/media/upload-from-url \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/photo.jpg" }'

The response shape matches POST /media/upload.

Inline URLs on a post

If you only need the media for a single post, skip the media library entirely. Pass URLs directly in media_urls on the post body.

Code
{
  "content": { "default": "Check this out" },
  "accounts": ["your-account-id"],
  "media_urls": ["https://example.com/photo.jpg"]
}

The API downloads, validates, and attaches the file automatically. Maximum 10 URLs per post. Use the media library (via upload or upload-from-url) when the same file appears on multiple posts, to save on download bandwidth.

Supported formats

Media type	Formats
Images	JPEG, PNG, GIF, WebP
Videos	MP4, MOV

Platform-specific size, aspect ratio, and duration requirements are enforced at publish time, not upload time. A video can upload successfully and still fail to publish to Instagram if it exceeds Instagram's length limit. See the Platforms section for per-platform media specs.

Listing and deleting

Endpoint	Description
GET /media	List everything in the library
GET /media/:id	Fetch a single media record
DELETE /media/:id	Delete from the library

Deleting a media file does not remove it from posts that have already been published.