Instagram Settings

Settings Schema

When creating a post for Instagram, use the following settings schema:

{
  "settings": {
    "__type": "instagram",
    "post_type": "post",
    "is_trial_reel": false,
    "collaborators": [],
    "audio": {
      "id": "587784541076604",
      "audio_volume": 100,
      "video_volume": 100
    }
  }
}

Use __type: "instagram" for Facebook Business-linked accounts and __type: "instagram-standalone" for standalone Instagram accounts. Both use the same settings schema, except audio, which is only available for Facebook Business-linked accounts.

Fields

Field	Type	Required	Description
`__type`	`string`	Yes	`instagram` or `instagram-standalone`
`post_type`	`string`	Yes	Type of Instagram post
`is_trial_reel`	`boolean`	No	Whether to post as a trial reel
`graduation_strategy`	`string`	No	Graduation strategy for trial reels
`collaborators`	`array`	No	List of collaborator usernames
`audio`	`object`	No	Audio to attach to a Reel (single video only)

`post_type`

Value	Description
`post`	Regular feed post
`story`	Instagram Story (24-hour visibility)

`is_trial_reel`

When set to true, the post will be published as a trial reel with limited initial visibility.

`graduation_strategy`

Controls how trial reels graduate to full visibility. Only applicable when is_trial_reel is true.

Value	Description
`MANUAL`	Manually graduate the reel
`SS_PERFORMANCE`	Automatically graduate based on performance

`collaborators`

Array of collaborator objects. Each collaborator will receive an invite to be added as a collaborator on the post.

{
  "collaborators": [
    { "label": "username1" },
    { "label": "username2" }
  ]
}

`audio`

Attach music or an original sound to a Reel, based on the Instagram Audio API.

Audio can only be attached to a Reel — a single video with post_type: "post". It is not supported on Stories, carousels, image posts, or on instagram-standalone channels (the Audio API requires Facebook Login).

Field	Type	Required	Description
`id`	`string`	Yes	The audio asset ID
`title`	`string`	No	Audio title (display only)
`artist`	`string`	No	Artist or creator name (display only)
`image`	`string`	No	Cover artwork URL (display only)
`audio_volume`	`number`	No	Volume of the attached audio, `0`-`100` (default `100`)
`video_volume`	`number`	No	Volume of the original video audio, `0`-`100` (default `100`)

To find audio IDs, use the trigger endpoint with the audioSearch tool:

curl -X POST https://api.postiz.com/public/v1/integration-trigger/{integrationId} \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"methodName": "audioSearch", "data": {"q": "summer vibes", "type": "music"}}'

Parameter	Description
`q`	Search query — leave empty to get trending audio
`type`	`music` (royalty-free catalog) or `original_sound` (user-generated), defaults to `music`

The response contains { output: [{ id, title, artist, image, duration, previewUrl }] } — pass the chosen id into settings.audio.id.

Only audio authorized for third-party use is returned, so the catalog can be smaller than what you see in the Instagram app.

Complete Example

Feed Post

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "Beautiful sunset today! 🌅\n\n#sunset #photography #nature",
          "image": [
            {
              "id": "image-id",
              "path": "https://uploads.postiz.com/sunset.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post",
        "is_trial_reel": false,
        "collaborators": []
      }
    }
  ]
}

Story Post

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "",
          "image": [
            {
              "id": "story-image-id",
              "path": "https://uploads.postiz.com/story.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "story"
      }
    }
  ]
}

Collaborative Post

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "Amazing collab with @partner! 🤝",
          "image": [
            {
              "id": "collab-image-id",
              "path": "https://uploads.postiz.com/collab.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post",
        "collaborators": [
          { "label": "partner_username" }
        ]
      }
    }
  ]
}

Reel with Audio

Attach audio found with audioSearch to a single-video Reel:

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "New reel with trending audio! 🎵",
          "image": [
            {
              "id": "video-id",
              "path": "https://uploads.postiz.com/reel.mp4"
            }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post",
        "audio": {
          "id": "587784541076604",
          "audio_volume": 80,
          "video_volume": 20
        }
      }
    }
  ]
}

Carousel Post

Create a carousel by adding multiple images:

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-instagram-integration-id"
      },
      "value": [
        {
          "content": "Swipe to see all the photos! 📸",
          "image": [
            { "id": "img1", "path": "https://uploads.postiz.com/1.jpg" },
            { "id": "img2", "path": "https://uploads.postiz.com/2.jpg" },
            { "id": "img3", "path": "https://uploads.postiz.com/3.jpg" }
          ]
        }
      ],
      "settings": {
        "__type": "instagram",
        "post_type": "post"
      }
    }
  ]
}

Overview

Integrations

Posts

Analytics

Notifications

Uploads

Video Generation

Provider Settings (25 with custom settings)

Settings Schema

Fields

`post_type`

`is_trial_reel`

`graduation_strategy`

`collaborators`

`audio`

Complete Example

Feed Post

Story Post

Collaborative Post

Reel with Audio

Carousel Post

​Settings Schema

​Fields

​post_type

​is_trial_reel

​graduation_strategy

​collaborators

​audio

​Complete Example

​Feed Post

​Story Post

​Collaborative Post

​Reel with Audio

​Carousel Post

Settings Schema

Fields

`post_type`

`is_trial_reel`

`graduation_strategy`

`collaborators`

`audio`

Complete Example

Feed Post

Story Post

Collaborative Post

Reel with Audio

Carousel Post