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.

Upload Image or Video

POST https://app.ayrshare.com/api/media/upload

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. Your can pass the file either as a multipart form data as a form parameter or a Base64 encoded file as a body parameter. Note 1: Media is available for 90 days after upload. All sent posts are unaffected. Note 2: Max size is 10 MB. See uploadUrl API endpoint below for larger files. Premium or Business Plan required.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.
Content-Type*	string	multipart/form-data if sending a multipart form data - see below. Otherwise, send the standard application/json.

Request Body

Name	Type	Description
file*	string or object	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. 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.
fileName	string	The name of the file for later reference.
description	string	A description for later reference.

200 Return the URL of the uploaded image, id of the image, and metadata provided.

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

400: Bad Request Error in upload

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

Request Examples

cURL

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

Node JS

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

Python

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

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

---

Upload Large Media Files

GET https://app.ayrshare.com/api/media/uploadUrl

For file uploads greater than 10 MB, obtain a presigned URL to upload a file. Note: - Maximum file upload size 5 GB. - Upload presigned URL valid for 30 minutes after being generated. - Access URL available for 30 days after uploaded. All sent posts are unaffected. Premium or Business Plan required.

Query Parameters

Name	Type	Description
fileName*	string	If the contentType is not present, required. Name of the file to be uploaded. Must include an extension such as .png, .jpg, .mov, .mp4, etc.
contentType*	string	The content-type of the media being uploaded. Valid formats include: mp4, quicktime, png, jpg, or jpeg. If not present, application/octet-stream will be used.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.

200 An upload URL and access URL

{
    "accessUrl": "https://img.ayr.app/Aswmfs3dIEbwLSdhTwnTPJq5UlV2/test.mp4",
    "contentType": "video/mp4",
    "uploadUrl": "https://storage.googleapis.com/..."
}

400: Bad Request Error getting signed URL

{
    "action": "upload",
    "status": "error",
    "code": 301,
    "message": "The provided content-type 'movd' is not recognized."
}

Request Examples

cURL

curl \
-H "Authorization: Bearer [API Key]" \
-X GET https://app.ayrshare.com/api/media/uploadUrl?fileName=test.mov&contentType=mov

Node.js

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

Python

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

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

C#

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

curl -X PUT \
-H 'Content-Type: video/mp4' \
--upload-file LOCAL_FILE_PATH uploadUrl

Node.js

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

Python

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

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

C#

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

Java

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. Select the HTTP Method PUT.

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. In Headers set the Content-Type to be the content type returned in the /uploadUrl endpoint. For example: Content-Type: image/png.

4. Select Body -> binary and select the file to upload.

5. Press Send.

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.

---

Verify Media URL Exists

POST https://app.ayrshare.com/api/media/urlExists

Verify that the media file exists when uploaded. It should be used in conjunction with the /media/uploadUrl endpoint.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.

Request Body

Name	Type	Description
mediaUrl*	string	URL of the media to verify exists.

200: OK Media URL is valid

{
    "status": "success"
}

404: Not Found Media file not found

{
    "status": "error",
    "statusCode": 404,
    "statusText": "Not Found"
}

Request Examples

cURL

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

Node.js

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

Python

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

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

---

Get All Images/Videos in Gallery

GET https://app.ayrshare.com/api/media

Retrieve all the images uploaded to the image gallery include resized images ideal for Instagram.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_Key See Overview for more information.

200 Returns an array of images in the image gallery.

[
    {
        "id": "5553a26a-cffb-4a31-bd89-dee296d35648-jpeg",
        "timeCreated": "2020-07-30T20:23:49.774Z",
        "size": "223340",
        "url": "https://images.ayrshare.com/LW8kx9Q5smXeJl5CujF7DxFAF1q1/5553a26a-cffb-4a31-bd89-dee296d35648.jpeg",
        "fileName": "test1.jpeg",
        "description": "Test1"
    },
    {
        "id": "93383cc7-7a15-4d16-a5fa-fdda1f9bebe2-jpeg",
        "timeCreated": "2020-07-30T20:24:57.421Z",
        "size": "223340",
        "url": "https://images.ayrshare.com/LW8kx9Q5smXeJl5CujF7DxFAF1q1/93383cc7-7a15-4d16-a5fa-fdda1f9bebe2.jpeg",
        "fileName": "test2.jpeg",
        "description": "Test2"
    }
]

Request Examples

cURL

curl \
-H "Authorization: Bearer [API Key]" \
-X GET https://app.ayrshare.com/api/media

Node JS

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

Python

import requests

headers = {'Authorization': 'Bearer [API_KEY]'}

r = requests.get('https://app.ayrshare.com/api/media', headers=headers)
    
print(r.json())

PHP

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

C#

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

---

Resize an image

POST https://app.ayrshare.com/api/media/resize

The social networks have specific requirements for social media images. The resize endpoint allows you to choose a social network compatible image size, add watermarks, change backgrounds, add effects, and more.

By default resizing will change the dimensions of an image, but not crop the image. You may instead crop the image. See below for details.

Headers

Name	Type	Description
Authorization*	string	Authorization: Bearer API_KEY See Overview for more information.

Request Body

Name	Type	Description
imageUrl*	string	URL of image to be resized. Must begin with https://
file	object	Send the media file as a multipart form-data object. Required if imageUrl not present.
watermarkUrl	string	URL of watermark to be applied to resized image. The watermark will appear in the lower right corner of the image. Please see below for details.
platform*	string	Social media platform for which the URL will be resized. Please see below for details.
effects	object	Change opacity, colors, etc. Please see below for details.
dimensions	object	Object specifying width and height for resizing. If cropping optionally specify the center x and y coordinates. Default is the center of the image. E.g: { “width”: 500, “height”: 500, "xCoordinate: 35, // optional for crop mode "yCoordinate": 50 // optional for crop mode } Width and height required if platform is not specified.
mode	string	Value: blur or crop. Default: resize. Please see below for details.

200: OK Sucessful resize

{
    "status": "success",
    "url": "https://media.ayrshare.com/9abf1426d6ce9122ef11c72bd62e59807c5cc083/8UbyBjHTxgHkAC1I37e6O.jpg",
    "platform": "instagram",
    "mode": "blur",
    "effects": {
        "color": "#A020F0"
    }
}

400: Bad Request Failed resize

{
    "action": "resize",
    "status": "error",
    "code": 312,
    "message": "Invalid extension type. Extension: null. Please verify the extension is one of the following: png, jpg, jpeg and the file is accessible."
}

Request Examples

cURL

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

Node.js

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

Python

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

<?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. Or you may specify your own with dimension field.

For example "platform": "facebook" will set the dimension of the image as width 1200px 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

Crop

Crop will cut off "crop" the image to the specified dimensions. By default the center coordinate will be the center of the image. You may also specify your own x/y coordinates.

For example:

{
    "dimensions": {
        // If no width and height the platform dimensions will be used, for example Instagram
        "width": 1080, 
        "height": 1080,
        "xCoordinates": 35,
        "yCoordinates": 50
    }
} 

Either the platform or the dimensions field width and height must be specified.

For square crops, if width or height are less than the dimensions of the provided image, the small of the width or height will be used. For example, if the image is 1200x800 and the crop requested is 1080x1080, the image returned will be 800x800.

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:

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:

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:

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": {
        "color": "grayscale"
    }
}

Result in the image:

Opacity

Set the opacity of the image. Number value range: 0 - 1. For example: "opacity": 0.2

Quality

For JPG or JEPG images specify the quality, or amount of compression, of the image. The lower the number the more compressed, but lower the image quality. The higher the number the less compressed, but the higher the image quality. Number value range: 0 - 100. For example: "quality": 20

---

Metadata on a media file

GET https://app.ayrshare.com/api/media/meta

Get the metadata on a provided media file URL.

Query Parameters

Name	Type	Description
url*	string	Encoded URI of the externally accessible media file URL.

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.

200: OK Successful metadata.

{
    "codec": "h264",
    "duration": 28.24, // In seconds
    "filename": "https://img.ayrshare.com/random/landscape16.mp4",
    "format": "QuickTime / MOV",
    "height": 1080,
    "size": 16275959, // In bytes
    "type": "video",
    "width": 1920
}

400: Bad Request Bad media URL

{
    "action": "post",
    "status": "error",
    "code": 229,
    "message": "Error validating video. Please check the video or URL."
}

Request Examples

GET https://app.ayrshare.com/api/media/meta?url=https%3A%2F%2Fimg.ayrshare.com%2Frandom%2Flandscape16.mp4