Ayrshare Docs
Ask or search…
βŒƒK
Links

media

Media API Endpoint: Upload and manage your images and videos. Premium or Business Plan required.

Media API Endpoint

Manage your image and video gallery by uploading and retrieving images and videos. Please be sure to verify the media URL before using it to post.
Recommendation: 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.
❗Click the β€Ί in the endpoint to view details.
post
https://app.ayrshare.com/api
/media/upload
Upload Image or Video

Request Examples

cURL
Node JS
Python
PHP
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://app.ayrshare.com/api/media/upload
const API_KEY = "API_KEY";
const base64 = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...";
​
fetch("https://app.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);
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://app.ayrshare.com/api/media/upload',
json=payload,
headers=headers)
print(r.json())
<?php
require 'vendor/autoload.php';// Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client();
$res = $client->request(
'POST',
'https://app.ayrshare.com/api/media/upload',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
],
'file' => 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
'fileName' => "test.png",
'description' => "best image"
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);

get
https://app.ayrshare.com/api
/media/uploadUrl
Upload Large Media Files

Request Examples

cURL
Node.js
Python
PHP
C#
curl \
-H "Authorization: Bearer [API Key]" \
-X GET https://app.ayrshare.com/api/media/uploadUrl?fileName=test.mov&contentType=mov
const fetch = require("node-fetch");
const API_KEY = "Your API Key";
​
fetch("https://app.ayrshare.com/api/media/uploadUrl?fileName=test.mov&contentType=mov", {
method: "GET",
headers: {
"Authorization": `Bearer ${API_KEY}`
}
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
​
headers = {'Authorization': 'Bearer [API_KEY]'}
​
r = requests.get('https://app.ayrshare.com/api/media/uploadUrl?fileName=test.mov&contentType=mov', headers=headers)
print(r.json())
<?php
require 'vendor/autoload.php'; // Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client();
$res = $client->request(
'GET',
'https://app.ayrshare.com/api/media/uploadUrl?fileName=test.mov&contentType=mov',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
]
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
using System;
using System.Net;
using System.IO;
​
namespace MediaGETRequest_charp
{
class Media
{
static void Main(string[] args)
{
string API_KEY = "API_KEY";
string url = "https://app.ayrshare.com/api/media/uploadUrl?fileName=test.mov&contentType=mov";
​
var httpWebRequest = WebRequest.CreateHttp(url);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);
​
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
var response = streamReader.ReadToEnd();
Console.WriteLine(response);
}
}
}
}
  • accessUrl is the URL to access the media file after upload.
  • contentType is the content-type set for the media being upload. Use this in the Content-Type header when uploading the media.
  • uploadUrl is the URL used to PUT the media file. Please see below.

Additional Endpoint Examples

The process to upload larger files:
  • Obtain an uploadURL and accessURL via the /media/uploadUrl endpoint. Please see above.
  • Upload the file via a PUT with Content-Type set to the returned contentType.
  • Upload the media by using the --upload-file with a media file and the uploadUrl.
  • After uploading the media file, POST to the /post endpoint with the accessUrl in the mediaUrls body parameter.
  • The presigned upload URL may only be uploaded to once. If you sent a bad file you must create a new upload URL. No error response will occur if the file is not successfully uploaded. See below of verifying the URL exists.
cURL
Node.js
Python
PHP
C#
Java
curl -X PUT \
-H 'Content-Type: video/mp4' \
--upload-file LOCAL_FILE_PATH uploadUrl
const fs = require("fs").promises;
const uploadFileToSignedUrl = async (signedUrl, filePath) => {
try {
const fileBuffer = await fs.readFile(filePath);
const response = await fetch(signedUrl, {
method: "PUT",
body: fileBuffer,
headers: {
"Content-Type": "video/mp4"
}
});
​
if (response.ok) {
console.log("File upload successful:", response.status);
} else {
console.error("File upload failed:", response.status);
}
} catch (error) {
console.error("Error uploading file:", error);
}
};
​
// Use the signed URL generated from the previous step
const signedUrl = "SIGNED_URL";
const filePath = "LOCAL_FILE_PATH";
​
uploadFileToSignedUrl(signedUrl, filePath);
import requests
​
def upload_file_to_signed_url(signed_url, file_path):
try:
with open(file_path, 'rb') as file:
response = requests.put(signed_url, data=file, headers={'Content-Type': 'video/mp4'})
​
if response.ok:
print("File upload successful:", response.status_code)
else:
print("File upload failed:", response.status_code)
except Exception as error:
print("Error uploading file:", error)
​
# Use the signed URL generated from the previous step
signed_url = "SIGNED_URL"
file_path = "LOCAL_FILE_PATH"
​
upload_file_to_signed_url(signed_url, file_path)
<?php
​
function uploadFileToSignedUrl($signedUrl, $filePath) {
try {
$fileHandle = fopen($filePath, 'rb');
if ($fileHandle === false) {
throw new Exception('Cannot open the file');
}
​
$ch = curl_init($signedUrl);
​
curl_setopt($ch, CURLOPT_PUT, true);
curl_setopt($ch, CURLOPT_INFILE, $fileHandle);
curl_setopt($ch, CURLOPT_INFILESIZE, filesize($filePath));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: video/mp4'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
​
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
​
if ($httpCode == 200) {
echo "File upload successful: " . $httpCode;
} else {
echo "File upload failed: " . $httpCode;
}
​
fclose($fileHandle);
curl_close($ch);
} catch (Exception $e) {
echo "Error uploading file: " . $e->getMessage();
}
}
​
// Use the signed URL generated from the previous step
$signedUrl = "SIGNED_URL";
$filePath = "LOCAL_FILE_PATH";
​
uploadFileToSignedUrl($signedUrl, $filePath);
?>
​
using System;
using System.Net.Http;
using System.IO;
using System.Threading.Tasks;
​
class Program
{
static async Task Main(string[] args)
{
string signedUrl = "SIGNED_URL"; // Replace with your signed URL
string filePath = "LOCAL_FILE_PATH"; // Replace with your file path
​
try
{
await UploadFileToSignedUrl(signedUrl, filePath);
}
catch (Exception ex)
{
Console.WriteLine("Error uploading file: " + ex.Message);
}
}
​
static async Task UploadFileToSignedUrl(string signedUrl, string filePath)
{
using (var client = new HttpClient())
using (var fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read))
using (var content = new StreamContent(fileStream))
{
content.Headers.Add("Content-Type", "video/mp4");
​
var response = await client.PutAsync(signedUrl, content);
​
if (response.IsSuccessStatusCode)
{
Console.WriteLine("File upload successful: " + response.StatusCode);
}
else
{
Console.WriteLine("File upload failed: " + response.StatusCode);
}
}
}
}
​
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.nio.file.Path;
import java.io.IOException;
import java.nio.file.Files;
​
public class FileUploader {
​
public static void main(String[] args) {
String signedUrl = "SIGNED_URL"; // Replace with your signed URL
String filePath = "LOCAL_FILE_PATH"; // Replace with your file path
​
try {
uploadFileToSignedUrl(signedUrl, filePath);
} catch (IOException | InterruptedException e) {
System.out.println("Error uploading file: " + e.getMessage());
}
}
​
private static void uploadFileToSignedUrl(String signedUrl, String filePath) throws IOException, InterruptedException {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(signedUrl))
.header("Content-Type", "image/jpg")
.PUT(BodyPublishers.ofFile(Path.of(filePath)))
.build();
​
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
​
if (response.statusCode() == 200) {
System.out.println("File upload successful: " + response.statusCode());
} else {
System.out.println("File upload failed: " + response.statusCode());
}
}
}
​
Please be sure that the contentType set when creating the uploadUrl matches the Content-Type and the file type when PUTing the file. For example, if you set the contentType to "image/png" when creating the uploadUrl, be sure to set the "Content-Type: image/png" and the uploaded file ends in ".png".

Example Upload File Binary in Node.js

Here is an example of uploading a binary media file using Node with JavaScript:
const fs = require("fs");
const request = require("request");
​
const API_KEY = "Your API Key";
const fileName = "test.png";
const endpoint = `https://app.ayrshare.com/api/media/uploadUrl?fileName=${fileName}&contentType=png`;
​
const run = async () => {
request.get(
{
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`,
},
url: endpoint,
},
(err, res, body) => {
if (err) {
return console.error(err);
}
​
const json = JSON.parse(body);
console.log("Upload URL:", json);
​
return fs.createReadStream(`./${fileName}`).pipe(
request.put(
json.uploadUrl,
{
headers: {
"Content-Type": json.contentType,
},
},
(err, httpsResponse, body) => {
if (err) {
console.error("err", err);
} else {
console.log(body);
}
}
)
);
}
);
};
​
run();

Example Upload Binary File in Postman

You may also use Postman to upload the binary file to the uploadUrl.
In Postman:
  1. 1.
    Select the HTTP Method PUT.
  2. 2.
    Paste your uploadUrl in the url field. Note, the url will expire after an hour and may only be used once. If you make a call and it fails, you must regenerate the uploadUrl.
  3. 3.
    In Headers set the Content-Type to be the content type returned in the /uploadUrl endpoint. For example: Content-Type: image/png.
  4. 4.
    Select Body -> binary and select the file to upload.
  5. 5.
    Press Send.
  6. 6.
    Important: No return response will occur, so you should check if the upload was successful by opening the accessUrl returned from the /uploadUrl endpoint in a browser. You may also use the verify URL endpoint.
Postman Binary Upload
Postman Binary Upload
Large Media File Upload.postman_collection.json
2KB
Code
Postman Sample File

post
https://app.ayrshare.com/api
/media/urlExists
Verify Media URL Exists

Request Examples

cURL
Node.js
Python
PHP
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"mediaUrl": "https://img.ayrshare.com/012/vid.mp4"}' \
-X POST https://app.ayrshare.com/api/media/urlExists
const API_KEY = "API_KEY";
​
fetch("https://app.ayrshare.com/api/media/urlExists", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${API_KEY}`
},
body: JSON.stringify({
mediaUrl: "https://img.ayrshare.com/012/vid.mp4"
}),
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
​
payload = {'mediaUrl': 'https://img.ayrshare.com/012/vid.mp4'}
headers = {'Content-Type': 'application/json',
'Authorization': 'Bearer API_KEY'}
​
r = requests.post('https://app.ayrshare.com/api/media/urlExists',
json=payload,
headers=headers)
print(r.json())
<?php
require 'vendor/autoload.php';// Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client();
$res = $client->request(
'POST',
'https://app.ayrshare.com/api/media/urlExists',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
],
'mediaUrl' => 'https://img.ayrshare.com/012/vid.mp4'
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);

Request Examples

cURL
Node JS
Python
PHP
C#
curl \
-H "Authorization: Bearer [API Key]" \
-X GET https://app.ayrshare.com/api/media
const API_KEY = "Your API Key";
​
fetch("https://app.ayrshare.com/api/media", {
method: "GET",
headers: {
"Authorization": `Bearer ${API_KEY}`
}
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
​
headers = {'Authorization': 'Bearer [API_KEY]'}
​
r = requests.get('https://app.ayrshare.com/api/media', headers=headers)
print(r.json())
<?php
require 'vendor/autoload.php'; // Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html
​
$client = new GuzzleHttp\Client();
$res = $client->request(
'GET',
'https://app.ayrshare.com/api/media',
[
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer API_KEY'
]
]
);
​
echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);
using System;
using System.Net;
using System.IO;
​
namespace MediaGETRequest_charp
{
class Media
{
static void Main(string[] args)
{
string API_KEY = "API_KEY";
string url = "https://app.ayrshare.com/api/media";
​
var httpWebRequest = WebRequest.CreateHttp(url);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);
​
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
var response = streamReader.ReadToEnd();
Console.WriteLine(response);
}
}
}
}

post
https://app.ayrshare.com/api
/media/resize
Resize an image

Request Examples

cURL
Node.js
Python
PHP
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"mediaUrl": "https://img.ayrshare.com/012/gb.jpg", "platform": "instagram"' \
-X POST https://app.ayrshare.com/api/media/resize
const API_KEY = "API_KEY";
​
fetch("https://app.ayrshare.com/api/media/resize", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${API_KEY}`
},
body: JSON.stringify({
mediaUrl: "https://img.ayrshare.com/012/gb.jpg", // required
platform: "instagram"
}),
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
​
payload = {'mediaUrl': 'https://img.ayrshare.com/012/gb.jpg',
'platforms': 'instagram'}
headers = {'Content-Type': 'application/json',
'Authorization': 'Bearer API_KEY'}
​
r = requests.post('https://app.ayrshare.com/api/media/resize',
json=payload,
headers=headers)
print(r.json())
<?php
​
$curl = curl_init();
$data = array (
"mediaUrl" => "https://img.ayrshare.com/012/gb.jpg",
"platforms" => "instagram"
);
​
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://app.ayrshare.com/api/media/resize',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => http_build_query($data),
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY',
'Accept-Encoding: gzip'
),
));
​
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Platform Options

Specify a platform as a String to use predefined dimensions of the image. If may specify your own with dimension field.
For example "platform": "facebook" will set the dimension of the image as width 1200 px and height 630px.
  • facebook: 1200px width, 630px height.
  • instagram: 1080px width, 1080px height.
  • instagram_landscape: 1080px width, 680px height.
  • instagram_portrait: 1080px width, 1350px height.
  • instagram_special: 1080px width, 800px height.
  • linkedin: 1200px width, 627px height.
  • pinterest: 1080px width, 1920px height.
  • twitter: 1600px width, 900px height.

Mode

Blur

Blur effect will duplicate the image as a background and blur.
For example:
{
"mediaUrl": "https://img.ayrshare.com/012/gb.jpg",
"platform": "instagram",
"mode": "blur"
}
Results in the image:
Blur resize effect
Background with Blur

Watermark

You may add a watermark to the image by providing a URL, which must begin with https://. The watermark will appear in the bottom right corner of the image. We recommend a PNG with a transparent background.
For example:
{
"mediaUrl": "https://img.ayrshare.com/012/gb.jpg",
"platform": "facebook",
"watermarkUrl": "https://img.ayrshare.com/012/100-percent.png"
}
Result in the image:
Watermark on an Image
Watermark in bottom right corner

Effects Options

Color Hexadecimal

Hexadecimal value for color of background for blur. Only applicable if "mode": "blur". String value, e.g. "#A020F0"
For example:
{
"mediaUrl": "https://img.ayrshare.com/012/gb.jpg",
"platform": "instagram",
"mode": "blur",
"effects": {
"color": "#A020F0"
}
}
Result in the image:
Blur image with purple
Colored background

Color: Grayscale, Sepia, Invert

You made change the primary image color by specifying grayscale, sepia, or invert. The field "blur": true is not required and should not be used if you do not want a background.
For example:
{
"mediaUrl": "https://img.ayrshare.com/012/gb.jpg",
"platform": "instagram",
"effects"