Options for posting via the API to Instagram
Post images or videos directly to Instagram.
Instagram has the following requirements and restrictions:
- Only 50 Instagram posts are allowed over a 24 hour period. See below for
usedQuota
- The
post
text may contain up to 30 hashtags (e.g. #wildtimes) and 3 username mentions (e.g. @natgeo). - @mention Instagram users will receive a notification.
- Maximum 2,200 post characters.
- Multi-image posts are supported via a carousel. Multiple videos are not supported.
- Delete not supported using the /delete endpoint.
- If your video doesn't end in a known video extension such as mp4, please use the
isVideo
parameter. See the /post endpoint for details. - Instagram also supports sending media without post text. If you do not want post text included send an empty String
post: ""
Note: The aspect ratio of images & videos and the duration of video are very important to successfully post to Instagram. If they do not meet the requirements, the post will be rejected.
Please see the Instagram section of Image and Video Guidelines:
JSON for a basic post with an image and hashtags to Instagram:
{
"post": "The best IG ever #best #awesome https://www.instagram.com",
"mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
"platforms": ["instagram"]
}
Hashtags are clickable in Instagram posts, but links are not.
Your Instagram account must be a Business or Creator Account and connected with a Facebook Page. The setup is free and easy.
See here for detailed instructions:
You can post multiple images to Instagram as a carousel; up to 10 images may be use in a carousel. Just add your additional images to the
mediaUrls
array and the carousel will automatically be created. Videos are not supported in carousel."mediaUrls": ["https://url1.com", "https://url2.com" ...]; // Max 10 images
You can post a video to Instagram Reels API with the following
instagramOptions
. {
"post": "The description of the video",
"mediaUrls": ["https://img.ayrshare.com/012/reel.mp4"],
"instagramOptions": {
"reels": true, // required for Reels
"shareReelsFeed": true, // optional
"audioName": "My song", // optional
"coverUrl": "https://mycover.com/cover.jpg" // optional
"thumbNailOffset": 3000 // optional
}
}
reels
: set totrue
to post the video to Reels.shareReelsFeed
: set totrue
to indicate that the Reel can appear in both the Feed and Reels tabs orfalse
to indicate the Reel can only appear in the Reels tab. This value is a hint to Instagram where you would like the Reel to appear, but neither value determines whether the Reel actually appears in the Reels or Feed tab because the Reel may not meet eligibility requirements or may not be selected by Instagram's algorithm.audioName
: Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.
You can post a single image or video as an Instagram Story with the following
instagramOptions
. Instagram stories disappear after 24 hours.{
"post": "The description of the video",
"mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
"instagramOptions": {
"stories": true,
}
}
Instagram currently only supports Story publishing on Instagram Business Accounts and not Creator Accounts.
You may select a frame in the video or Reel as the thumbnail image. Also, Reels support a cover image from an external URL. Instagram does not support external cover images for regular videos.
{
...
"instagramOptions": {
"thumbNailOffset": 30000 // milliseconds
"coverUrl": "https://img.ayrshare.com/012/gb.jpg" // Reels only. If both coverUrl and thumbNailOffset includes, coverUrl will be used.
}
}
The offset is the location in milliseconds of the thumbnail frame. Default value is
0
, which is the first frame of the video or Reel.If you specify both a cover image URL and a thumbnail offset, the thumbnail offset will be ignored.
The Instagram user will be notified when you use their username in a post. Please be cautious to not spam users or post with their username repeatedly. If you do, Instagram will suspend or deactivate your account.
An image or a Reel can be tagged with Instagram users and an image, video, or a Reel can be tagged with a location using the
instagramOptions
parameter.A location is specified by a
locationId,
which is a Facebook Page ID or Facebook Page name. For example, Facebook page Id of the Guggenheim Museum is 7640348500
or Facebook page name "@guggenheimmuseum"
. Pages must be associated with a physical location.// Using the Facebook Page Id - must be associated with a location
{
...
"instagramOptions": {
"locationId": 7640348500 // Guggenheim Museum Page Id
}
}
// Using the Facebook Page name - must be associated with a location
{
...
"instagramOptions": {
"locationId": "@guggenheimmuseum" // Guggenheim Museum Page name. Must begin with @
}
}
Users are specified by a
userTags
containing an Array of objects with an Instagram username and x/y coordinates (image only). User tags can be added for single images or Reels, but not regular videos, multiple images, or Stories. - Usernames must be public Instagram accounts.
x
andy
values must befloat
numbers that originate from the top-left of the image, with a range of0.0
–1.0
. Single images only and not to be used with Reels or an error will occur.
{
...
"instagramOptions": {
"userTags": [
{
"username": "ayrshare", // Required: Instagram username
"x": 0.5, // Required for Images, can not be used with Reels
"y": 1.0 // Required for Images, can not be used with Reels
},
{
"username": "johnboy", // Required: Instagram username
"x": 0.1, // Required for Images, can not be used with Reels
"y": 0.9 // Required for Images, can not be used with Reels
}
]
}
}
Mention another Instagram handle by adding @handle in the post text. For example:
{
"post": "The best social media API @Ayrshare ever!",
"mediaUrls": ["https://images.com"],
"platforms": ["instagram"]
}
Enterprise Plans required.
Images are automatically resized to 1080 x 1080 px to work with Instagram with the autoResize parameter. Please note, this will resize the image for all included platforms, so we recommend making one call for Instagram and a different /post call for additional platforms.
{
"post": "Let it go!",
"platforms": [
"instagram"
],
"mediaUrls": [
"https://images.ayrshare.com/imgs/GhostBusters.jpg"
],
"instagramOptions": {
"autoResize": true, // Enterprise Plans only
"locationId": 7640348500,
"userTags": [
{
"username": "ayrshare",
"x": 0.5,
"y": 0.5
},
{
"username": "ayrshare",
"x": 0.3,
"y": 0.2
}
]
}
}
Mention other Instagram handles by simply including the handle beginning with the @ symbol in the
post
text. For example:{
"post": "Love the @ayrshare social media api"
}
The Instagram response will include the current
usedQuota
for the number of Instagram posts done over a rolling 24-hours period. Only 25 Instagram posts are permitted by Instagram in a 24-rolling-hour period.{
"status": "success",
"errors": [],
"postIds": [
{
"status": "success",
"id": "17823977408036085",
"postUrl": "https://www.instagram.com/p/CeBrkQuN1Kv/",
"usedQuota": 15,
"platform": "instagram"
}
],
"id": "l4FaPHSXWJNdmMfm3dIE"
"refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
"post": "Luckily for Alice, the little magic bottle had now had its full effect."
}
If the quota has been reached, an error message will be returned.
Rich text, such as bold or italic lettering, can be added to a Instagram post with a few html elements.
Instagram Stories posting is not yet supported by Facebook's official API integration. However Facebook Reels and Instagram Reels can be posted via Ayrshare's API.
Last modified 1mo ago