Upload Image or Video

Upload an image or small video file to include in your post

POST /media/upload

cURL

# 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

// 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);

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

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

200: Success

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

{
  "action": "request",
  "status": "error",
  "code": 101,
  "message": "Missing or incorrect parameters. Please verify with the docs. .../ayrshare.com/rest-api/endpoints"
}

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

   • Hosting media files on your own server (e.g. AWS S3).
   • Passing the media URL directly in the mediaUrls parameter of the /post endpoint.
   • This approach is faster than uploading files through this endpoint.

2. Media file retention

   • Uploaded files are stored for 90 days.
   • After 90 days:
   • Published posts on social networks are unaffected.
   • Scheduled posts will fail to publish if they reference expired media.

3. File size limits

   • Maximum file size: 30 MB.
   • For larger files, see our guide on handling large media uploads.

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

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:

• Image: https://base64.guru/converter/encode/image
• Video: https://base64.guru/converter/encode/video

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

cURL

# 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

// 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);

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

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

200: Success

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

{
  "action": "request",
  "status": "error",
  "code": 101,
  "message": "Missing or incorrect parameters. Please verify with the docs. .../ayrshare.com/rest-api/endpoints"
}