Skip to content

Instagram Create Post API

The Instagram Create Post API sends Instagram feed posts, Instagram Stories, Instagram Reels, and Instagram carousels through a single creation request. First connect a professional Instagram account and look up its integration identifier, then supply the caption, target, and media in the payload. Feed and Reel publishing call for a Business or Creator professional account, whereas Stories call for a Business account. The default direct sign-in route works without tying the account to a Facebook Page. Choosing the Facebook sign-in route is optional, and it unlocks catalog audio for Reels.

Overview and account requirements

One creation request covers four Instagram formats: feed posts, Stories, Reels, and carousels. The workflow begins with account connection, continues with an identifier lookup, and ends with a post payload carrying the caption, the Instagram target, and the media items. Account eligibility depends on format. A Business or Creator professional account covers feed posts and Reels, while Stories are limited to Business accounts. Signing in directly through Instagram is the default path and works without a Facebook Page connection. The Facebook sign-in path is an optional alternative whose main added value is catalog audio for Reels.

Quick start: connect, get the account ID, and publish

Request an authorization URL for Instagram first. Whoever completes authorization needs a professional Instagram account. Once that step finishes, list integrations and locate the entry marked platform instagram. Its id becomes the accountId you place in the Instagram target. Next, build the creation payload with content, a platforms array, mediaItems, and publishNow true when immediate publication is wanted. A completed publication returns success true, status published, a postId, and a per-platform object that includes platformPostUrl. Before sending, confirm three things: the account type suits the chosen format, at least one media item is present, and the media format and dimensions meet the tables below. An empty integrations list means the connection step still needs completion. A response that does not show published should not be treated as delivered; inspect the status and platform result instead.

Feed posts, Stories, Reels, and carousels

A feed post carries one image or one video together with a caption and hashtags. Media is mandatory, so a caption-only request has no valid Instagram representation. For accessibility, place altText on an image item. Carousel images may each carry a different altText. This description field applies to feed images and image carousel items only; videos, Reels, and Stories do not accept it. Stories are chosen by setting platformSpecificData.contentType to story. That format needs a Business account, exactly one image or video, and it vanishes after 24 hours. Caption text from the request does not appear on a Story, and sticker features such as links, polls, music, locations, and mentions are unavailable in this flow. Reels are produced by sending a video item without the story marker. Unless you change it, a Reel also shows in the main feed grid. Setting shareToFeed to false inside platformSpecificData limits placement to Reels. For cover selection, supply a public HTTPS image through platformSpecificData.coverUrl, or supply platformSpecificData.thumbOffset as a millisecond timestamp from which Instagram extracts a frame. When both appear, coverUrl wins. Cover images must be JPEG or PNG and should share the video ratio, 9:16 for Reels, since mismatched ratios are rejected. Neither cover option has any effect on non-video posts. Setting isAiGenerated to true inside platformSpecificData tells Instagram the media itself was AI-generated, prompting its AI info label. The flag concerns the media, not prose written with AI help. It applies across feed images, Reels, Stories, and carousels, with carousels receiving the disclosure on the parent container only. To control the audio label shown on a Reel, pass audioName inside platformSpecificData. That label names sound already embedded in the file. Catalog tracks follow a different route: connect via Facebook and use audioConfiguration, never alongside audioName. Trial Reels first reach people who do not follow the account, giving a low-risk test before followers see the clip. Inside trialParams, graduationStrategy MANUAL keeps the clip in trial until you promote it manually, while SS_PERFORMANCE hands promotion to Instagram once performance criteria are met. A trial entry must contain a single video; mixing in Stories, still images, or carousels is not allowed, and the connected professional account must be eligible for the feature. Carousels come from sending several mediaItems in one request, up to 10 images or videos. Keep a single ratio across every item and consult the media table first, since inconsistent ratios and unsupported formats frequently cause rejection.

Media requirements and Reel specifications

Validate image and carousel inputs against the media requirements table before sending anything. Validate Reel files against the Reel specifications table, covering container, codec, audio, frame rate, dimensions, bitrate, duration, and file size. A 9:16 ratio is recommended to prevent cropping or empty bands. When a Reel is rejected, work through the specification rows in order: container and moov placement, codec and chroma settings, audio rate and bitrate, frame rate bounds, width ceiling, ratio bounds, bitrate ceiling, duration bounds, and size ceiling. Each row is a separate rejection trigger.

Platform-specific data field map

Instagram-specific customization travels in platformSpecificData on the Instagram target. Setting contentType to story switches the request to Story mode. Leaving it out preserves the default mapping where images go to Feed and videos become Reels. The field map below lists every field with its type, requiredness, allowed values, and format applicability. For similar-looking choices, pick audioName when labeling embedded sound and audioConfiguration when attaching a catalog track through Facebook Login. Pick coverUrl for an explicit cover image and thumbOffset only when no cover image is provided. Pick MANUAL for manual Trial Reel promotion or SS_PERFORMANCE for performance-driven promotion.

Facebook Login, capabilities, headless selection, reconnects, catalog audio, and location tags

Direct Instagram sign-in stays the default and needs no Facebook Page. Choose Facebook sign-in when you need catalog-audio search or Reel audio publishing. That route expects a Business or Creator Instagram account, a Facebook Page already tied to it, someone able to administer both assets, and approved Meta permissions if you bring your own OAuth app. Begin by adding loginMethod facebook_login to the connect call, then direct the user to the returned URL. After authorization, the user picks a professional Instagram account that is linked to a Page. When using your own OAuth app, add appId carrying the Facebook app identifier; even though the finished integration is for Instagram, that identifier must belong to a Facebook app. Each Instagram integration reports its sign-in route and feature set through platformMetadata. Inspect capabilities.catalogAudio before rendering audio search or audio publishing controls. A false value comes with catalogAudioReason, and the table below maps each reason to its remedy. For headless selection, send headless true plus redirectUri, collect the returned selectionToken through GET /v1/connect/instagram/selection/{token}, and submit a single identifier with POST using selectedAccountIds. Tokens expire quickly and work once only, and the access key belongs on the server. For reconnects, add reconnectAccountId to the Facebook sign-in connect call. When identities match, the integration and its scheduled posts survive. When Meta hands back a different identifier across sign-in routes, the upgrade is refused and the original connection stays intact, so create a separate connection in that case. Catalog audio search uses the audio endpoint with accountId set to the connected integration identifier, audioType music, and q carrying the query text. Leaving q out returns trending audio, and audioType original_sound targets original sounds. Each result carries a track identifier, title, type, artist, duration, and preview links. To refresh a previously saved track, send audioId in place of the search parameters. Because preview and download links can expire, persist the audioId. To publish a chosen track, place audioConfiguration inside platformSpecificData on the Instagram target, with audioId mandatory and audioVolume plus videoVolume as integers between 1 and 100, both defaulting to 100. Only single-video Reels accept catalog audio; Stories, photos, and carousels reject audioConfiguration. Publishing rechecks the track, and a track that is no longer available causes failure instead of silent removal, so re-search and pick a live track after such a failure. Catalog contents can differ from what the Instagram app shows, since account, region, and Meta licensing all influence availability. For location tags, put the numeric identifier of a Facebook Page that has physical location data into locationId. Feed posts, Reels, and whole carousels accept this tag; Stories do not, and neither Story stickers nor location search are available. Pages that do not exist or lack location data are rejected, so confirm both the identifier and its location data beforehand. Collaborators are invited by listing up to three Instagram usernames in collaborators for feed posts, carousels, and Reels; each invited account must accept inside Instagram.

Media requirements
TypeRequirement
ImageJPG or PNG; aspect ratio from 4:5 through 1.91:1
CarouselUp to 10 JPG, PNG, MP4, or MOV items; use one aspect ratio throughout

Source-stated media requirements for Instagram publishing.

Reel specifications
SpecificationInstagram requirement
ContainerMOV or MP4; no edit lists; moov atom at the front
VideoH.264 or HEVC; progressive scan; closed GOP; 4:2:0 chroma subsampling
AudioAAC; 48 kHz maximum; mono or stereo; 128 kbps
Frame rate23-60 FPS
Picture sizeMaximum 1,920 px wide; aspect ratio from 0.01:1 through 10:1
Video bitrateVariable bitrate, 25 Mbps maximum
Duration3 seconds-15 minutes
File size300 MB maximum

Source-stated Reel specifications; Instagram recommends 9:16 video to avoid cropping or blank space.

Platform-specific data fields
FieldTypeRequiredValues and constraintsDescription
locationIdstringNo—Numeric Facebook Page ID with location data. Feed posts, Reels and whole carousels only; not Stories.
audioConfigurationobjectNo—Catalog audio for single-video Reels, requires Facebook Login. Volumes default to 100. Audio must remain available at publish time.
audioConfiguration.audioIdstringYes, when audioConfiguration is provided——
audioConfiguration.audioVolumeintegerNoRange: 1–100—
audioConfiguration.videoVolumeintegerNoRange: 1–100—
contentTypestringNostorySet to "story" to publish an Instagram Story. Omit for the existing behavior: images publish to Feed and videos publish as Reels.
isAiGeneratedbooleanNo—Self-discloses that the post contains AI-generated images or video so Instagram can show its AI info label. Applies to feed posts, Reels, Stories, and carousel parents; it does not describe AI-written captions.
shareToFeedbooleanNo—Reels-only. When true (default), the Reel also appears in the account's main feed grid. Set false to publish to Reels only.
trialParamsobjectNo—Reels-only. Publishes a single video as a Trial Reel, initially shown to non-followers.
trialParams.graduationStrategystringYes, when trialParams is providedMANUAL, SS_PERFORMANCEControls how a Trial Reel is shared with followers. MANUAL keeps graduation manual; SS_PERFORMANCE lets Instagram share it automatically when it performs well.
coverUrlstringNoFormat: uriVideo-only. Public URL of an image Instagram will use as the cover frame for the Reel/video post. Ignored for image posts.
thumbOffsetintegerNoRange: 0–unboundedVideo-only. Timestamp in milliseconds Instagram extracts as the cover frame. Ignored when coverUrl is set or for image posts.
audioNamestringNoLength: 1–100Reels-only. Sets the name shown for the Reel audio. This only labels audio already in the video file. Use audioConfiguration to attach catalog audio through Facebook Login.
collaboratorsstring[]NoItems: 1–3Feed posts, carousels, and Reels only. Up to three Instagram usernames to invite as collaborators. Each account must accept the invitation in Instagram.

Complete platformSpecificData field map preserved from the source contract.

Catalog audio unavailable reasons
ReasonResolution
facebook_login_requiredConnect or reconnect through Facebook Login
publishing_permission_missingReconnect and approve the requested Instagram publishing access
facebook_user_token_expiredReconnect through Facebook Login

Source-stated catalogAudioReason values and resolutions.

Frequently asked questions

Which Instagram account types can publish each format?

Feed posts and Reels need a Business or Creator professional account. Stories need a Business account specifically. Check the account type before sending media, because the wrong type will block that format.

When should I use audioName instead of audioConfiguration?

Use audioName to label sound already inside your video file. Use audioConfiguration, after Facebook Login, to attach a licensed catalog track to a single-video Reel. Do not send both together.

How do coverUrl and thumbOffset interact?

Send coverUrl for an explicit JPEG or PNG cover image. Send thumbOffset, in milliseconds, only when you want Instagram to pick a frame from the video. If both are present, coverUrl wins.

What is the difference between MANUAL and SS_PERFORMANCE for Trial Reels?

MANUAL leaves the trial in non-follower view until you share it yourself. SS_PERFORMANCE lets Instagram move it to followers automatically once performance is strong enough.

Connect an Instagram account
curl {{API_BASE_URL}}/v1/connect/instagram \
  -H "x-access-key: YOUR_API_KEY"
List integrations to find the Instagram account ID
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Publish an Instagram feed post
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/photo.jpg" }
    ],
    "publishNow": true
  }'
Published post response
{
	"success": true,
	"status": "published",
	"postId": "post_def456",
	"platforms": [
		{
			"platform": "instagram",
			"success": true,
			"platformPostUrl": "https://www.instagram.com/p/ABC123/"
		}
	]
}
Feed image with alt text
{
	"content": "A short example update.",
	"platforms": [{ "platform": "instagram", "accountId": "ig_456" }],
	"mediaItems": [
		{
			"type": "image",
			"url": "https://cdn.example.com/blocks.jpg",
			"altText": "An illustrative image."
		}
	]
}
Publish an Instagram Story
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "",
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "ig_456",
        "platformSpecificData": {
          "contentType": "story"
        }
      }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/story.jpg" }
    ],
    "publishNow": true
  }'
Publish an Instagram Reel
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/reel.mp4" }
    ],
    "publishNow": true
  }'
Publish a Reel with a custom cover
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "ig_456",
        "platformSpecificData": {
          "coverUrl": "https://cdn.example.com/reel-cover.jpg"
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/reel.mp4" }
    ],
    "publishNow": true
  }'
Publish a Reel without sharing it to the feed grid
"platformSpecificData": { "shareToFeed": false }
Disclose AI-generated media
"platformSpecificData": { "isAiGenerated": true }
Set the displayed Reel audio name
"platformSpecificData": { "audioName": "Original audio - yourbrand" }
Publish a Trial Reel with manual graduation
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "ig_456",
        "platformSpecificData": {
          "trialParams": {
            "graduationStrategy": "MANUAL"
          }
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/reel.mp4" }
    ],
    "publishNow": true
  }'
Publish an Instagram carousel
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/slide1.jpg" },
      { "type": "image", "url": "https://cdn.example.com/slide2.jpg" },
      { "type": "image", "url": "https://cdn.example.com/slide3.jpg" }
    ],
    "publishNow": true
  }'
Start Facebook Login for Instagram
curl "{{API_BASE_URL}}/v1/connect/instagram?loginMethod=facebook_login" \
  -H "x-access-key: YOUR_API_KEY"
Facebook Login with an application ID
GET /v1/connect/instagram?loginMethod=facebook_login&appId=APP_ID
Instagram integration capabilities
{
	"platformMetadata": {
		"loginMethod": "facebook_login",
		"capabilities": {
			"publish": true,
			"insights": true,
			"comments": true,
			"messages": true,
			"catalogAudio": true,
			"catalogAudioReason": null
		}
	}
}
Reconnect an Instagram integration through Facebook Login
GET /v1/connect/instagram?loginMethod=facebook_login&reconnectAccountId=INTEGRATION_ID
Search Instagram catalog audio
curl "{{API_BASE_URL}}/v1/instagram/audio?accountId=ACCOUNT_ID&audioType=music&q=summer" \
  -H "x-access-key: YOUR_API_KEY"
Attach catalog audio to a single-video Reel
{
	"audioConfiguration": {
		"audioId": "482851939985510",
		"audioVolume": 80,
		"videoVolume": 50
	}
}