> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Image or Video

> Upload an image or small video as multipart form data or Base64 encoded file to get a URL for the /post endpoint, with a 30 MB limit and 90 day storage.

This endpoint allows you to upload a file or an image or small video to include in your post. Returned will be the URL to the image that can be used in the /post endpoint.

You can pass the file either as a ***multipart form data*** as a form parameter or a **Base64 encoded file** as a body parameter.

Important notes about media uploads:

1. For best performance, we recommend
   <ul>
     <li>Hosting media files on your own server (e.g. AWS S3).</li>
     <li>Passing the media URL directly in the `mediaUrls` parameter of the [/post](https://www.ayrshare.com/docs/apis/post/overview.md) endpoint.</li>
     <li>This approach is faster than uploading files through this endpoint.</li>
   </ul>

2. Media file retention

   <ul>
     <li>Uploaded files are stored for 90 days.</li>
     <li>After 90 days:</li>

     <ul>
       <li>Published posts on social networks are unaffected.</li>
       <li>Scheduled posts will fail to publish if they reference expired media.</li>
     </ul>
   </ul>

3. File size limits
   <ul>
     <li>Maximum file size: 30 MB.</li>
     <li>For larger files, see our guide on [handling large media uploads](https://www.ayrshare.com/docs/apis/media/upload-large-media.md).</li>
   </ul>

> [!TIP]
>
> If you already have your media accessible by an external URL, such as an S3 bucket, you can skip uploading the files to Ayrshare. Just POST to the `/post` endpoint with your externally accessible URL in the `mediaUrls` body parameter and your file will automatically be uploaded.

## Header Parameters

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`

**Content-Type** `string` *required*

Use `multipart/form-data` if sending a multipart form data - see below. Otherwise, send the standard `application/json`.

## Body Parameters

**file** `string or object` *required*

Max 30 MB file size.

We recommend sending as a multipart form-data object instead of Base64 encoding.

**fileName** `string`

The name of the file to be uploaded.

**description** `string`

A description of the file.

### Send as Multipart Form-Data

Send the media file as a multipart form-data object. Please be sure to specify the `Content-Type` as mentioned above.

### Send as Base64

Send the media file as a Base64 encoded string as a Data URI string. The string should begin with `data:content/type;base64`

Example encoding with Output Format Data URI:

<ul>
  <li>Image: [https://base64.guru/converter/encode/image](https://base64.guru/converter/encode/image)</li>
  <li>Video: [https://base64.guru/converter/encode/video](https://base64.guru/converter/encode/video)</li>
</ul>

Note: The /post endpoint accepts larger files via an external URL with the `mediaUrls` parameter.

```bash cURL theme={"system"}
# Send as Multipart Form-Data
curl \
-H "Authorization: Bearer API_KEY" \
-F "file=@test.png" \
-F "fileName=test.png" \
-F "description=best image" \
-X POST https://api.ayrshare.com/api/media/upload

# Send as Base64
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "fileName": "test.png", "description": "best image"}' \
-X POST https://api.ayrshare.com/api/media/upload
```

```javascript JavaScript theme={"system"}
// Send as Multipart Form-Data
const FormData = require('form-data');
const fs = require('fs');

const API_KEY = "API_KEY";
const imagePath = './test.png';

const form = new FormData();
form.append('file', fs.createReadStream(imagePath));
form.append('fileName', 'test.png');
form.append('description', 'best image');

fetch("https://api.ayrshare.com/api/media/upload", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`
    // Don't set Content-Type header - FormData will set it automatically with boundary
  },
  body: form
})
.then(res => res.json())
.then(json => console.log(json))
.catch(console.error);

// Send as Base64
const API_KEY = "API_KEY";
const base64 = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...";

fetch("https://api.ayrshare.com/api/media/upload", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        file: base64,
        fileName: "test.png",
        description: "best image"
      }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);
```

```python Python theme={"system"}
# Send as Multipart Form-Data
import requests

# For a local file:
files = {
    'file': ('test.png', open('test.png', 'rb')),
}

# Form data
data = {
    'fileName': 'test.png',
    'description': 'best image'
}
headers = {
    'Authorization': 'Bearer API_KEY'
}

r = requests.post(
    'https://api.ayrshare.com/api/media/upload',
    files=files,
    data=data,
    headers=headers
)

print(r.json())

# Send as Base64
import requests

payload = {'file': 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
        'fileName': "test.png",
        'description': "best image"}
headers = {'Content-Type': 'application/json',
        'Authorization': 'Bearer API_KEY'}

r = requests.post('https://api.ayrshare.com/api/media/upload',
    json=payload,
    headers=headers)

print(r.json())
```

```php PHP theme={"system"}
# Send as Multipart Form-Data
<?php
  // Generate a boundary string
  $boundary = uniqid();

  // Open the file
  $file = file_get_contents('test.png');

  // Build the multipart form data
  $data = '';
  $data .= "--" . $boundary . "\r\n";
  $data .= 'Content-Disposition: form-data; name="file"; filename="test.png"' . "\r\n";
  $data .= "Content-Type: image/png\r\n\r\n";
  $data .= $file . "\r\n";

  $data .= "--" . $boundary . "\r\n";
  $data .= 'Content-Disposition: form-data; name="fileName"' . "\r\n\r\n";
  $data .= "test.png\r\n";

  $data .= "--" . $boundary . "\r\n";
  $data .= 'Content-Disposition: form-data; name="description"' . "\r\n\r\n";
  $data .= "best image\r\n";

  $data .= "--" . $boundary . "--\r\n";

  // Setup the context for the request
  $options = [
      'http' => [
          'method' => 'POST',
          'header' => "Authorization: Bearer API_KEY\r\n" .
                    "Content-Type: multipart/form-data; boundary=" . $boundary . "\r\n" .
                    "Content-Length: " . strlen($data) . "\r\n",
          'content' => $data
      ]
  ];

  // Send the request
  $context = stream_context_create($options);
  $result = file_get_contents('https://api.ayrshare.com/api/media/upload', false, $context);

  // Print the response
  echo $result;

# Send as Base64
<?php
$data = [
    'file' => 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
    'fileName' => "test.png",
    'description' => "best image"
];

$ch = curl_init('https://api.ayrshare.com/api/media/upload');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer API_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
```

```javascript 200: Success theme={"system"}
{
    "id": "1167335b-6c37-4fc6-ab8a-044e0005d335-jpeg",
    "url": "https://images.ayrshare.com/q3Ls85VTsrbODnGIJHpy7PaHWwA3/1167335b-6c37-4fc6-ab8a-044ed885d.jpeg",
    "fileName": "fun.jpg",
    "description": "good times"
}
```

```json 400: Bad Request Error in upload theme={"system"}
{
  "action": "request",
  "status": "error",
  "code": 101,
  "message": "Missing or incorrect parameters. Please verify with the docs. .../ayrshare.com/rest-api/endpoints"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.