Media Handling

Manage your media assets before attaching them to posts. Publer’s API supports direct uploads and URL imports, returning media IDs you can reference when creating or updating posts.

Overview

Before including media in your social media posts, you must first upload those files to Publer's servers. The API provides two methods for uploading media:

1. Direct file upload

2. Upload from URL

Once uploaded, you'll receive a media ID that can be referenced in your post requests.

Direct File Upload

Use this method when you have local media files that you want to upload directly.

Limitation

• Maximum file size for direct uploads: 200MB per file.

• Requests exceeding 200MB will be rejected (typically with HTTP 413 Payload Too Large). For larger files, use the Upload from URL method.

Request Format

This endpoint expects a multipart/form-data request with the file included in the file field.

Upload a media file directly

post

Upload a media file (image, video, or document) to be used in social media posts

Authorizations

BearerApiAuth

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to upload media

Body

multipart/form-data

filestringRequired

direct_uploadbooleanOptional

Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)

Default: false

in_librarybooleanOptional

Whether to save to media library

Default: false

Responses

200

Media file uploaded successfully

application/json

idstringOptional

Unique identifier for the uploaded media

Example: 6813892b5ec8b1e65235ae9e

pathstringOptional

URL path to access the uploaded media

Example: https://cdn.publer.io/uploads/tmp/1746110763-128246820936684-0001-1648/mini_magick20250501-29172-ce1rot.png

thumbnailstringOptional

URL path to access a thumbnail version of the media

Example: https://cdn.publer.io/uploads/tmp/1746110763-128246820936684-0001-1648/mini_magick20250501-29172-ce1rot.png

validityobjectOptional

Indicates which networks and post types support this media

widthnumberOptional

Width of the media in pixels

Example: 1451

heightnumberOptional

Height of the media in pixels

Example: 1005

sourcestringOptional

Source attribution for the media

typestringOptional

Media type (photo, video, document)

Example: photo

namestringOptional

Original filename

Example: 123_1kdw8ry.png

captionstringOptional

Caption for the media

400

Invalid request parameters

application/json

401

Unauthorized

application/json

413

Permission denied or missing required scope

application/json

post

/media

HTTPcURLJavaScriptPython

POST /api/v1/media HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 56

{
  "file": "text",
  "direct_upload": false,
  "in_library": false
}

{
  "id": "6813892b5ec8b1e65235ae9e",
  "path": "https://cdn.publer.io/uploads/tmp/1746110763-128246820936684-0001-1648/mini_magick20250501-29172-ce1rot.png",
  "thumbnail": "https://cdn.publer.io/uploads/tmp/1746110763-128246820936684-0001-1648/mini_magick20250501-29172-ce1rot.png",
  "validity": {},
  "width": 1451,
  "height": 1005,
  "source": null,
  "type": "photo",
  "name": "123_1kdw8ry.png",
  "caption": null
}

Key Response Fields

Field	Description
id	Unique identifier for the uploaded media (use this in post requests)
path	URL path to access the uploaded media
thumbnail	URL path to access a thumbnail version of the media
validity	Indicates which networks and post types support this media
width, height	Dimensions of the uploaded media in pixels
type	Media type (photo, video, document)
name	Original filename

Upload from URL

Use this method when your media is already hosted elsewhere and you want to import it by URL.

Upload media from URL

post

Upload media files by providing URLs

Authorizations

BearerApiAuth

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to upload media

Body

application/json

typestring · enumRequired

Upload type

Example: singlePossible values:

direct_uploadbooleanOptional

Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)

Default: false

in_librarybooleanOptional

Whether to save to media library

Default: false

Responses

200

Media upload job created successfully

application/json

job_idstringOptional

ID of the created job

Example: 68138a295ec8b1e65235aea0

400

Invalid request parameters

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

post

/media/from-url

HTTPcURLJavaScriptPython

POST /api/v1/media/from-url HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 220

{
  "media": [
    {
      "url": "https://example.com/path/to/image.jpg",
      "name": "instagram: @auchynnikau",
      "caption": "Photo by Slava Auchynnikau on Unsplash",
      "source": "unsplash"
    }
  ],
  "type": "single",
  "direct_upload": false,
  "in_library": false
}

{
  "job_id": "68138a295ec8b1e65235aea0"
}

Request Parameters

Parameter	Description	Required
media[].url	URL of the media file to download	Yes
media[].name	Custom name for the media file	Yes
media[].caption	Caption for the media	No
media[].source	Source attribution	No
type	Upload type (single or bulk)	No
direct_upload	Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL) (default: false)	No
in_library	Whether to save to media library (default: false)	No

Unlike direct uploads, URL uploads are processed asynchronously. Use the returned job_id to check the status of your upload.

Checking Upload Status

Get job status

get

Check the status of an asynchronous job, including URL media uploads

Authorizations

BearerApiAuth

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Path parameters

job_idstringRequired

ID of the job to check

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to retrieve posts from

Responses

200

Job status retrieved successfully

application/json

successbooleanOptional

Whether the request was successful

Example: true

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

get

/job_status/{job_id}

HTTPcURLJavaScriptPython

GET /api/v1/job_status/{job_id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "success": true,
  "data": {
    "status": "complete",
    "result": {
      "status": "working",
      "payload": {
        "failures": {
          "error": "Failed to upload media",
          "code": 500
        }
      },
      "plan": {
        "rate": "business",
        "locked": false
      }
    }
  }
}

Using Media in Posts

Once you've uploaded media and have the media ID, you can reference it in your post requests:

{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "default": {
            "type": "photo",
            "text": "Check out our latest product!",
            "media": [
              {
                "id": "6813892b5ec8b1e65235ae9e",
                "type": "image",
                "alt_text": "Product on white background"
              }
            ]
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "scheduled_at": "2025-05-15T14:30:00Z"
          }
        ]
      }
    ]
  }
}

Supported Media Types

Images

• Supported formats: JPG, PNG, GIF, WEBP

• Recommended dimensions: Varies by platform (see Networks Reference)

• Maximum file size: Varies by platform, generally 5-10MB

Videos

• Supported formats: MP4, MOV, AVI, WEBM

• Recommended dimensions: Varies by platform (see Networks Reference)

• Maximum file size: Varies by platform, generally 512MB-2GB

• Duration limits: Varies by platform and content type

Documents

• Supported formats: PDF

• Maximum file size: 100MB

• Supported networks: LinkedIn only

Network Validation

The validity object in the media upload response indicates which networks and post types can use the uploaded media. This helps prevent errors when attempting to use incompatible media in your posts.

For example, if validity.instagram.reel is false, the uploaded media cannot be used for Instagram Reels.

Best Practices

Image Optimization

1. Resolution: Use appropriate image resolutions for each platform

2. Aspect ratio: Follow recommended aspect ratios to avoid cropping

3. File size: Optimize images for web to reduce file size

4. Alt text: Always include descriptive alt text for accessibility

Video Optimization

1. Format: Use MP4 with H.264 encoding for maximum compatibility

2. Dimensions: Use 1080p (1920x1080) for standard videos

3. Aspect ratio: 16:9 for horizontal, 9:16 for vertical/stories/reels

4. Duration: Keep videos under platform limits

5. Thumbnails: Consider uploading custom thumbnails for videos

General Tips

1. Pre-check compatibility: Review the validity object before using media

2. Error handling: Implement robust error handling for upload failures

3. Caching: Cache media IDs to avoid unnecessary re-uploads

Related Topics

• Content Types - Details on different content formats

• Network Reference - Platform-specific media requirements

• Publishing Methods - Using media in different post types