Instagram 用户媒体

表示一系列 Instagram 用户的 Instagram 媒体对象。

自 2023 年 11 月 9 日起，media_type 将不再支持 VIDEO 值。请改为使用 REELS 媒体类型向您的动态发布视频。

创建

POST /{ig-user-id}/media

为图片、轮播、快拍或 Reels 创建相应的 Instagram 容器，以便在帖子发布流程中使用。请参阅内容发布指南，了解完整的发布步骤。

限制

一般限制

容器将于 24 小时后过期。
如果与目标 Instagram 专业帐户关联的公共主页需要公共主页发布授权 (PPA)，则必须完成 PPA，否则请求将失败。
如果与目标 Instagram 专业帐户关联的公共主页需要双重验证，则 Facebook 用户还必须执行双重验证，否则请求将失败。
不支持发布到 Instagram TV。

Reels 限制

Reels 在相册轮播中无法显示。
在发布内容时遵循应用帐户隐私设置。举例来说，如已启用允许合拍设置，发布的 Reels 便会在发布时启用合拍设置，但您也可以通过 Instagram 应用在已发布的 Reels 上手动停用此设置。
音乐标记只适用于原声。

快拍限制

快拍将于 24 小时后过期。
支持使用视频网址或 Reels 网址，但两者不可同时使用。
不支持发布贴图（即链接、投票、位置）。

要求

类型	描述
访问口令	用户
商务管理平台用户身份	如要创建商品标记容器，应用用户必须在拥有此 Instagram 用户的 Instagram 店铺的商务管理平台上获得管理员身份。
Instagram 店铺	如要创建商品标记容器，Instagram 用户必须拥有已获批准的 Instagram 店铺，以及包含商品的商品目录。
权限	`instagram_basic` `instagram_content_publish` `pages_read_engagement` 或 `pages_show_list` 若通过商务管理平台向应用用户授予了公共主页身份，您还将需要以下其中一项权限： `ads_management` `business_management` 如要建立商品标记容器，您还需要以下内容： `catalog_management` `instagram_shopping_tag_products`
任务	若在请求中使用了应用用户的口令，则该用户必须能够在与目标 Instagram 帐户关联的公共主页上执行 `MANAGE` 或 `CREATE_CONTENT` 任务。

图片参数

格式：JPEG
文件大小：不超过 8 MB。
宽高比：必须在 4:5 到 1.91:1 范围内
最小宽度：320（必要时将扩大至最小值）
最大宽度：1440（必要时将缩小至最大值）
高度：视宽度和宽高比而变
色彩空间：sRGB。若图片使用其他色彩空间，系统会将其色彩空间转换为 sRGB。

Reels 规格

Reels 规格如下所示：

容器：MOV 或 MP4 (MPEG-4 Part 14)，无编辑列表，文件前面有 moov atom。
音频编解码器：AAC，采样率不超过 48khz，1 或 2 个通道（单声道或立体声）。
视频编解码器：HEVC 或 H264，逐行扫描，封闭式图片组，4:2:0 色度抽样。
帧率：23-60 FPS。
图片尺寸：
- 最大列数（水平像素）：1920
- 宽高比要求为 0.01:1 至 10:1，但我们建议使用 9:16 的宽高比，以避免图片被裁剪或出现空白位置。
视频比特率：可变码率，不超过 25Mbps
音频比特率：128kbps
时长：不超过 15 分钟，不短于 3 秒
文件大小：不超过 1GB

Reels 封面照片的规格如下所示：

格式：JPEG
文件大小：不超过 8MB
色彩空间：sRGB。若图片使用其他色彩空间，系统会将其色彩空间转换为 sRGB。
宽高比：推荐使用 9:16，以避免图片被裁剪或出现空白位置。如果原始图片的宽高比不是 9:16，我们会裁剪图片，并使用正中 9:16 矩形作为 Reels 的封面照片。如果您在动态中分享 Reels，我们会裁剪图片，并使用正中 1:1 正方形作为动态帖子的封面照片。

快拍图片规格

格式：JPEG
文件大小：不超过 8 MB。
宽高比：推荐使用 9:16，以避免图片被裁剪或出现空白位置
色彩空间：sRGB。若图片使用其他色彩空间，系统会将其色彩空间转换为 sRGB

快拍视频规格

容器：MOV 或 MP4 (MPEG-4 Part 14)，无编辑列表，文件前面有 moov atom。
音频编解码器：AAC，采样率不超过 48khz，1 或 2 个通道（单声道或立体声）。
视频编解码器：HEVC 或 H264，逐行扫描，封闭式图片组，4:2:0 色度抽样。
帧率：23-60 FPS。
图片尺寸：
- 最大列数（水平像素）：1920
- 宽高比要求为 0.1:1 至 10:1，但我们建议使用 9:16 的宽高比，以避免图片被裁剪或出现空白位置
视频比特率：可变码率，不超过 25Mbps
音频比特率：128kbps
时长：不超过 60 秒，不短于 3 秒
文件大小：不超过 100MB

请求语法

图片容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
  ?image_url={image-url}
  &is_carousel_item={is-carousel-item}
  &caption={caption}
  &location_id={location-id}
  &user_tags={user-tags}
  &product_tags={product-tags}
  &access_token={access-token}

Reels 容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?media_type=REELS
&video_url={reel-url}
&caption={caption}
&share_to_feed={share-to-feed}
&collaborators={collaborator-usernames}
&cover_url={cover-url}
&audio_name={audio-name}
&user_tags={user-tags}
&location_id={location-id}
&thumb_offset={thumb-offset}
&share_to_feed={share-to-feed}
&access_token={access-token}

轮播容器

仅限轮播容器。如要创建轮播项目容器，请改为创建图片容器或视频容器（不支持 Reels）。请参阅轮播帖子，了解完整发布步骤。

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?media_type=CAROUSEL
&caption={caption}
&share_to_feed={share-to-feed}
&collaborators={collaborator-usernames}
&location_id={location-id}
&product_tags={product-tags}
&children={children}
&access_token={access-token}

图片快拍容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
  ?image_url={image-url}
  &media_type=STORIES
  &access_token={access-token}

视频快拍容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
  ?video_url={video-url}
  &media_type=STORIES
  &access_token={access-token}

路径参数

占位符	值
`{api-version}`	API 版本。
`{ig-user-id}` 必要项	应用用户的应用范围用户编号。

查询字符串参数

键	占位符	描述
`access_token`	`{access-token}`	必要项。应用用户的用户访问口令。
`audio_name`	`{audio-name}`	仅适用于 Reels。您 Reels 媒体的音频名称。在创建 Reels 期间或之后，您只能从音频页面重命名一次。
`caption`	`{caption}`	图片、视频或轮播的说明。可以在其中加入话题标签（例如 `#crazywildebeest`）和 Instagram 用户的帐号（例如 `@natgeo`）。受到 @提及的 Instagram 用户将在您发布容器时收到通知。最多可包括 2200 个字符、30 个话题标签和 20 个 @ 标签。不支持为轮播中的图片或视频使用此参数。
`collaborators`	`{caption}`	对于动态图片，此参数仅适用于 Reels 和轮播。表示 Instagram 帐号清单，对于 Instagram 媒体，至多支持将 3 个此类帐号添加为合作者。不支持快拍。
`children`	`{children}`	轮播的必要项。仅适用于轮播。容器编号数不超过 10 个的数组，其中各个编号对应着已发布轮播中出现的各个图片和视频。轮播中的图片和/或视频总数不得超过 10。
`cover_url`	`{cover-url}`	仅适用于 Reels。用作 Reels 选项卡封面图片的图片路径。我们将使用您指定的网址对图片执行 cURL 请求，因此该图片必须位于公共服务器上。如果您同时指定了 `cover_url` 和 `thumb_offset`，我们将使用 `cover_url` 并忽略 `thumb_offset`。图片必须符合 Reels 封面照片规格的要求。
`image_url`	`{image-url}`	仅适用于图片，且是图片的必要项。图片的路径。我们将使用您指定的网址对图片执行 cURL 请求，因此该图片必须位于公共服务器上。
`is_carousel_item`	`{is-carousel-item}`	仅适用于图片和视频。设为 `true`。表示图片或视频将出现在轮播中。
`location_id`	`{location-id}`	与您希望在图片或视频中标记的地点相关联的公共主页编号。您可以使用公共主页搜索 API 搜索名称与搜索字符串相匹配的公共主页，然后分析结果，找出任何为实际地点创建的公共主页。在您的查询中加入 `location` 字段，并验证您想使用的公共主页是否具有地点数据。如果试图使用无地点数据的公共主页创建容器，则操作会失败，并会返回异常代码 `INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID`。轮播中的图像或视频不支持此参数。
`media_type`	`{media-type}`	轮播、快拍和 Reels 的必要项。表示容器是用于轮播、快拍，还是 Reels。值可以是： `CAROUSEL` `REELS` `STORIES`
`product_tags`	`{product-tags}`	商品标记的必要项。仅适用于图像和视频。对象数组，用于指定标记图像或视频要使用的商品标记（最大值为 5；标记和商品编号必须唯一）。每个对象均应具有以下信息： `product_id` — 必要项。商品编号。 `x` — 仅适用于图像。可选浮点数，表示到已发布媒体图像左侧边缘的距离百分比。值必须在 `0.0`–`1.0` 范围内。 `y` — 仅适用于图像。可选浮点数，表示到已发布媒体图像上边缘的距离百分比。值必须在 `0.0`–`1.0` 范围内。例如： `[{product_id:'3231775643511089',x: 0.5,y: 0.8}]`
`share_to_feed`	`{share-to-feed}`	仅适用于 Reels。如果值为 `true`，则表示 Reels 可以同时在动态和 Reels 选项卡中显示。如果为 `false`，则表示 Reels 只可在 Reels 选项卡中显示。这两个值都不表示 Reels 是否实际显示在 Reels 选项卡中，因为 Reels 可能不符合资格要求或未被我们的算法选中。请参阅 Reels 规格，以了解相关资格标准。
`thumb_offset`	`{thumb-offset}`	适用于视频和 Reels。要用作封面缩略图的视频或 Reels 帧的位置（以毫秒为单位）。默认值为 `0`，即视频或 Reels 的第一帧画面。对于 Reels，如果您同时指定了 `cover_url` 和 `thumb_offset`，我们将使用 `cover_url` 并忽略 `thumb_offset`。
`user_tags`	`{user-tags}`	用户标记的必要项。适用于图像和视频。您希望在图像中标出的任何公开 Instagram 用户的一组公开帐号和 `x`/`y` 坐标。每个对象均应具有以下信息： `usernames` — 必要项。公开帐号。 `x` — 仅限图像。可选浮点数，表示到已发布媒体图像左侧边缘的距离百分比。值必须在 `0.0`–`1.0` 范围内。 `y` — 仅适用于图像。可选浮点数，表示到已发布媒体图像上边缘的距离百分比。值必须在 `0.0`–`1.0` 范围内。
`video_url`	`{video-url}`	视频和 Reels 的必要项。仅适用于视频和 Reels。视频的路径。我们使用传入的网址对视频执行 cURL 请求，因此该视频必须位于公共服务器上。

响应

JSON 格式的对象，其中包含用以发布容器的 Instagram 容器编号。

视频上传是异步操作，因此收到容器编号并不能确保上传成功。如需验证视频是否已经上传，请在 Instagram 容器中请求 status_code 字段。如果值为 FINISHED，则视频已成功上传。

{
  "id":"{ig-container-id}"
}

请求示例

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

响应示例

{
  "id": "17889455560051444"
}

读取

GET /{ig-user-id}/media

获取 Instagram 用户的所有 Instagram 媒体。

限制

最多返回 1 万个最近创建的媒体。
不支持快拍 Instagram 媒体，需改为使用 GET /{ig-user-id}/stories 端点。

要求

类型描述

访问口令

用户

权限

instagram_basic
pages_read_engagement 或 pages_show_list

若通过商务管理平台向应用用户授予了公共主页用户身份，您还将需要以下其中一项权限：

ads_management
business_management

基于时间的分页

此端点支持基于时间的分页。加入带有 Unix 时间戳或 strtotime 数据值的 since 和 until 查询字符串参数，以确定时间范围。

请求示例

GET graph.facebook.com/17841405822304914/media

响应示例

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

更新

不支持此操作。

删除

不支持此操作。