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](https://publer.com/docs/posting/create-posts/media-handling#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

https://app.publer.com/api/v1/media

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

**Authorizations**  
**BearerApiAuth**

**Authorization**  
string  
Required

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

**Header parameters**

- Publer-Workspace-Id: string Required (ID of the workspace to upload media)

**Body**  
multipart/form-data

- file: string Required  
- direct_upload: boolean Optional  
- in_library: boolean Optional

**Responses**

- **200**  
  Media file uploaded successfully

application/json

- id: string Optional  
  - path: string Optional  
  - thumbnail: string Optional  
  - validity: object Optional  
  - width: number Optional  
  - height: number Optional  
  - source: string Optional  
  - type: string Optional  
  - name: string Optional  
  - caption: string Optional

- **400**  
  Invalid request parameters

- **401**  
  Unauthorized

- **413**  
  Permission denied or missing required scope

**Example**

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

### 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

https://app.publer.com/api/v1/media/from-url

Upload media files by providing URLs.

**Authorizations**

**BearerApiAuth**

**Authorization**  
string  
Required

**Header parameters**

- Publer-Workspace-Id: string Required

**Body**  
application/json

- media: object[] Required (List of media URLs and metadata)  
- type: string Required (Upload type)
- direct_upload: boolean Optional  
- in_library: boolean Optional

**Responses**

- **200**  
  Media upload job created successfully

application/json
  
  - job_id: string Optional

**Example**

```json
{
  "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
}
```

### Checking Upload Status

#### Get job status

get

https://app.publer.com/api/v1/job_status/{job_id}

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

**Authorizations**

**BearerApiAuth**

**Authorization**  
string Required

**Path parameters**

- job_id: string Required

**Responses**

- **200**  
  Job status retrieved successfully

application/json

- **401**  
  Unauthorized

- **403**  
  Permission denied or missing required scope

**Example**

```json
{
  "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:

```json
{
  "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
- **Maximum file size**: Varies by platform, generally 5-10MB

#### Videos

- **Supported formats**: MP4, MOV, AVI, WEBM
- **Recommended dimensions**: Varies by platform
- **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.

### 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