Instagram Graph API

Media

This edge allow you to:

Creating

Creating Photo Containers

This operation is only available to partners in the Content Publishing API beta program.

You can create media containers for photos that meet the following specifications:

  • Maximum file size: 8MB
  • Aspect ratio: Must be within a 4:5 to 1.91:1 range
  • Minimum resolution: 150x150 (lower resolutions will be scaled up to the minimum)
  • Maximum resolution: 1920x1080 (higher resolutions will be scaled down to the maximum)
  • Formats: JPEG, PNG, BMP, and non-animated GIFs

To create a media container for a photo, send a POST request to the /user/media edge and include the following parameters:

Parameter Description

caption

A caption for the photo. Like the app, you can include hashtags (e.g., #crazywildebeest) and usernames of Instagram Users (e.g., @natgeo). @Mentioned Users will receive a notification when you publish the media object container.

image_url (required)

The path to the photo. We will cURL your photo using the passed in URL so it must be on a public server.

location_id

The ID of a Places Graph Place location you want to tag the photo with. Use the Places Search API to discover Place IDs.

user_tags

An array of public usernames and x/y coordinates for any public Instagram Users who you want to tag in the photo. The array must be formatted in JSON and contain a username, x, and y, property, such as [{username:'natgeo',x:0.5,y:1.0}]. x and y values must be float numbers that originate from the top-left of the image, with a range of 0.0–1.0. Tagged users will receive a notification when you publish the media container.

If successful, this edge will respond with the newly created media object container's id. You can then use the id to publish the media object container. If you don't publish the media object container within 24 hours, it will expire.

Permissions

A User access token with the following permissions:

  • instagram_basic
  • instagram_content_publish

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=https//www.example.com/images/bronzed-fonzes.jpg
  &caption=#BronzedFonzes!
  &user_tags=
    [
      {
        username:'kevinhart4real',
        x: 0.5,
        y: 0.8
      },
      {
        username:'therock',
        x: 0.3,
        y: 0.2
      }
    ]

Sample Response

{
  "id": "17889455560051444"
}

Creating Video Containers

This operation is only available to partners in the Content Publishing API beta program.

You can create media containers for videos that meet the following specifications:

  • Container: MOV or MP4 (MPEG-4 Part 14), no edit lists, moov atom at the front of the file.
  • Audio codec: AAC, 48khz sample rate maximum, 1 or 2 channels (mono or stereo).
  • Video codec: HEVC or H264, progressive scan, closed GOP, 4:2:0 chroma subsampling.
  • Frame rate: 23-60 FPS.
  • Picture size:
    • Maximum columns (horizontal pixels): 1920
    • Minimum aspect ratio [cols / rows]: 4 / 5
    • Maximum aspect ratio [cols / rows]: 16 / 9
  • Bitrate: VBR, 5Mbps maximum
  • Duration: 60 seconds maximum, 3 seconds minimum
  • File size: 100MB maximum

To create a media container for a video, send a POST request to the /user/media edge and include the following parameters:

Parameter Description

caption

A caption for the video. Like the app, you can include hashtags (e.g., #crazywildebeest) and usernames of Instagram Users (e.g., @natgeo). @Mentioned Users will receive a notification when you publish the media object container.

location_id

The ID of a Places Graph Place location you want to tag the photo with. Use the Places Search API to discover Place IDs.

media_type (required)

Set value to VIDEO for video publishing.

thumb_offset

Location, in milliseconds, of the video frame to be used as the video's cover thumbnail image. Default value is 0, which is the first frame of the video.

video_url (required)

The path to the video. We will cURL your video using the passed in URL so it must be on a public server.

If successful, this edge will respond with the newly created media object container's id. You can then use the id to publish the media object container. If you don't publish the media object container within 24 hours, it will expire.

Permissions

A User access token with the following permissions:

  • instagram_basic
  • instagram_content_publish

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?media_type=VIDEO
  &video_url=https//www.example.com/videos/hungry-fonzes.mov
  &caption=#Heyyyyyyyy!

Sample Response

{
  "id": "17889455560051444"
}

Reading

Getting Media Objects

To get all media objects on an Instagram Business User, send a GET request to the User's /media edge.

Permissions

A User access token with the following permissions:

  • instagram_basic

If the token is for a User whose Page role was granted via the Business Manager, one of the following permissions is also required:

  • ads_management
  • manage_pages
  • business_management

Limitations

This edge will return a maximum of 10K of the most recently created media objects.

Sample Request

GET graph.facebook.com/17841405822304914/media

Sample Response

{
  "data": [
    {
      "id": "17895695668004550"
    },
    {
      "id": "17899305451014820"
    },
    {
      "id": "17896450804038745"
    },
    {
      "id": "17881042411086627"
    },
    {
      "id": "17869102915168123"
    }
  ]
}

Updating

This operation is not supported.

Deleting

This operation is not supported.