Instagram

Post images, videos, reels, stories, and carousels to Instagram through the PublishQ API.

What you can post

Type	Supported	Max media	Notes
Feed image	✅	1	JPEG (PNG accepted, converted). Max 8 MB
Reels	✅	1	MP4/MOV. Max 300 MB, 3s–15 min
Story	✅	1	Image or video. Disappears after 24h
Carousel	✅	10	Mix of images and videos. Min 2 items. Videos up to 300 MB, 60 min

Limitations

Instagram requires a Business or Creator account. Personal accounts cannot post via the API.
2200 character caption limit. Max 30 hashtags and 20 @mentions per caption. First 125 characters are visible before the "more" fold.
100 API-published posts per 24-hour moving period. Carousels count as 1 post.
The first item in a carousel determines the aspect ratio for the entire carousel, with a default of 1:1.
GIF files are not supported. Only JPEG images and MP4/MOV videos.

Content types

Instagram has four content types: feed image, carousel, reels, and story. You only need to set contentType for stories — everything else is auto-detected. Single videos are automatically published as Reels (Instagram no longer supports standalone video posts). Omit contentType for feed images and carousels.

Quick start

Post an image

A regular feed post with a single image. Shows up in your profile grid.

Get your media ready

curl -X POST https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..." \
  -F "[email protected]"

curl https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..."

Pick the id of the media you want to use from the response.

Create the post

curl -X POST https://publishq.com/api/v1/posts \
  -H "Authorization: Bearer pq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Golden hour 🌅",
    "mediaIds": ["media-id-from-step-1"],
    "accounts": [
      { "accountId": "your-instagram-account-id" }
    ],
    "publishNow": true
  }'

Post a reel

A short-form video (3s–15 min) that appears in the Reels tab and optionally in your feed. Single videos are automatically detected and published as Reels by PublishQ — you can set contentType: "reels" explicitly, but it's optional.

Get your media ready

curl -X POST https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..." \
  -F "[email protected]"

curl https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..."

Pick the id of the video you want to use from the response.

Create the post

curl -X POST https://publishq.com/api/v1/posts \
  -H "Authorization: Bearer pq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes 🎬",
    "mediaIds": ["video-id-from-step-1"],
    "thumbnailTimestamp": 3000,
    "accounts": [
      {
        "accountId": "your-instagram-account-id",
        "platformSpecificSettings": {
          "shareToFeed": true,
          "audioName": "Original Sound"
        }
      }
    ],
    "publishNow": true
  }'

Post a carousel

A swipeable post with 2–10 images, videos, or a mix of both. The first item determines the aspect ratio for the entire carousel (default 1:1).

Get your media ready

curl -X POST https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..." \
  -F "[email protected]"

Repeat for each file. You need at least 2 media IDs.

curl https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..."

Pick the id of each media item you want to use from the response.

Create the post

curl -X POST https://publishq.com/api/v1/posts \
  -H "Authorization: Bearer pq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Weekend highlights 📸",
    "mediaIds": ["media-id-1", "media-id-2", "media-id-3"],
    "accounts": [
      { "accountId": "your-instagram-account-id" }
    ],
    "publishNow": true
  }'

Post a story

Set contentType: "story" to publish to Stories. Stories disappear after 24 hours. Text captions are not displayed on stories. Supports a single image or video.

Get your media ready

curl -X POST https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..." \
  -F "[email protected]"

curl https://publishq.com/api/v1/media \
  -H "Authorization: Bearer pq_live_..."

Pick the id of the media you want to use from the response.

Create the post

curl -X POST https://publishq.com/api/v1/posts \
  -H "Authorization: Bearer pq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["media-id-from-step-1"],
    "accounts": [
      {
        "accountId": "your-instagram-account-id",
        "platformSpecificSettings": {
          "contentType": "story"
        }
      }
    ],
    "publishNow": true
  }'

Platform-specific settings

Pass these inside platformSpecificSettings on the Instagram account entry. All fields are optional — omit the entire object for a regular feed post or carousel.

Field	Type	Description
`contentType`	`enum (optional)`	Set to "story" for ephemeral content that disappears after 24 hours. Set to "reels" to explicitly publish as a Reel. Omit for a regular feed post or carousel — single videos are automatically published as Reels.
`shareToFeed`	`boolean (optional)`	Reels only. When true (default), the reel can appear in both the Feed and Reels tabs. When false, it only appears in the Reels tab. Neither value guarantees placement — Instagram's algorithm decides based on eligibility and relevance.
`trialParams`	`object (optional)`	Reels only. Publish as a trial reel — shown only to non-followers first.
`audioName`	`string (optional)`	Reels only. Custom name for the audio track of your reel. Can only be set once — either at creation time or later from the audio page in the Instagram app.

Full schema: InstagramPlatformSpecificSettings

Trial reels example

Trial reels are shown only to non-followers first. If the reel performs well, Instagram can automatically promote it to your followers.

{
  "content": "Testing this new format",
  "mediaIds": ["video-media-id"],
  "thumbnailTimestamp": 5000,
  "accounts": [
    {
      "accountId": "instagram-account-id",
      "platformSpecificSettings": {
        "shareToFeed": true,
        "audioName": "Original Sound",
        "trialParams": {
          "graduationStrategy": "SS_PERFORMANCE"
        }
      }
    }
  ],
  "publishNow": true
}

Media specs

Images

Spec	Feed / Carousel	Story
Formats	JPEG (PNG accepted, converted)	JPEG
Max file size	8 MB	8 MB
Aspect ratio	4:5 to 1.91:1	9:16 recommended
Min width	320px (upscaled)	320px
Max width	1440px (downscaled)	1440px

Videos

Spec	Reels	Feed / Carousel	Story
Formats	MP4, MOV	MP4, MOV	MP4, MOV
Max file size	300 MB	300 MB	100 MB
Duration	3s – 15 min	3s – 60 min	3s – 60s
Frame rate	23–60 FPS	23–60 FPS	23–60 FPS
Max resolution	1920px wide	1920px wide	1920px wide
Aspect ratio	0.01:1 to 10:1 (9:16 recommended)	4:5 to 1.91:1	0.1:1 to 10:1 (9:16 recommended)
Video codec	H.264 or HEVC	H.264 or HEVC	H.264 or HEVC
Audio codec	AAC, max 48kHz, stereo	AAC, max 48kHz, stereo	AAC, max 48kHz, stereo

Not yet supported

GIF attachments — Instagram does not accept GIF files through the API.
Location tagging
Stickers on stories — Link, poll, and location stickers are not supported by the Instagram API.
First comment (coming soon)
User tagging — @mentioning users at specific coordinates in images/stories. (Comsing soon)
Cover image for reels — Custom cover photo via cover_url. (Coming soon)

On this page