内容发布

您可以使用 Instagram 图谱 API 在 Instagram 专业账户上发布单张图片、单段视频或 Reels（即单一素材帖子），或发布包含多张图片和多段视频的帖子（轮播帖子）。

从 2023 年 7 月 1 日开始，通过 Instagram 内容发布 API 发布的所有单一动态视频都将作为 Reels 进行分享。

要求

访问口令

所有请求必须包含应用用户的用户访问口令。

权限

发布功能依赖于以下权限的组合。具体需要哪几种权限取决于应用所使用的端点。请参阅我们的端点参考文档，以确定各端点需要哪些权限。

如果您应用的使用对象是既没有应用身份，也没有公司身份（已认领应用）的用户，则您必须通过应用审核请求批准所需的每项权限。然后，没有身份的应用用户才能向您的应用授予这些权限。

公共服务器

我们会对您试图发布内容中所使用的素材执行 cURL 请求，因此在试图发布之时，该素材必须托管在公共服务器上。

公共主页发布授权

如果与 Instagram 专业账户关联的公共主页需要公共主页发布授权 (PPA)，则在完成 PPA 前，您无法向该专业账户发布内容。

应用用户也许可以在最初不需要 PPA 的公共主页上执行任务，但后来该公共主页又需要 PPA。在这种情况下，应用用户在完成 PPA 前将无法向其 Instagram 专业账户发布内容。鉴于您无法确定应用用户的公共主页是否需要 PPA，我们建议您告知应用用户预先完成 PPA。

限制

仅支持 JPEG 图片格式。不支持 MPO 和 JPS 等 JPEG 扩展格式。
不支持购物标签。
不支持品牌内容标签。
不支持滤镜。
不支持发布到 Instagram TV。

如需了解其他限制，请参阅各端点参考文档。

流量限制

Instagram 账户在 24 小时内仅能通过 API 发布 50 条帖子。轮播算作单个帖子。在试图发布素材容器时，我们将在 POST /{ig-user-id}/media_publish 端点上执行此限制。我们建议您对自己的应用同样执行发布流量限制。如果您的应用允许应用用户设置在未来发布定时帖，则更应如此。

如要查看 Instagram 专业账户当前的流量限制使用情况，请查询 GET /{ig-user-id}/content_publishing_limit 端点。

端点

此 API 包含以下端点。如需了解使用说明，请参阅各个端点的参考文档。

POST /{ig-user-id}/media — 上传素材并创建素材容器。
POST /{ig-user-id}/media_publish — 使用其素材容器发布已上传的素材。
GET /{ig-container-id}?fields=status_code — 检查素材容器的发布资格和状态。
GET /{ig-user-id}/content_publishing_limit — 检查应用用户当前对内容发布流量限制的使用情况。

单一素材帖子

发布单张图片、单个视频、快拍或 Reels 可分为两个步骤：

使用 POST /{ig-user-id}/media 端点，利用公共服务器上托管的图片或视频创建容器。
使用 POST /{ig-user-id}/media_publish 端点发布该容器。

第 1 步（共 2 步）：创建容器

举例来说，假设您想要发布位于以下网址的图片：

https://www.example.com/images/bronz-fonz.jpg

而且想加上“#BronzFonz”话题标签作为其说明。请向 POST /{ig-user-id}/media 端点发送请求：

请求示例

POST https://graph.facebook.com/v19.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

此操作将返回图片的容器编号。

响应示例

{
  "id": "17889455560051444"  // IG Container ID
}

第 2 步（共 2 步）：发布容器

使用 POST /{ig-user-id}/media_publish 端点发布上一步中返回的容器编号。

请求示例

POST https://graph.facebook.com/v19.0/17841400008460056/media_publish ?creation_id=17889455560051444

响应示例

{
  "id": "17920238422030506" // IG Media ID
}

轮播帖子

在单个轮播帖子中，发布的图片和/或视频总数不得超过 10。发布轮播帖子可分为三个步骤：

使用 POST /{ig-user-id}/media 端点为轮播中出现的每个图片和视频创建单独的项目容器。
再次使用 POST /{ig-user-id}/media 端点为项目创建单个轮播容器。
使用 POST /{ig-user-id}/media_publish 端点发布轮播容器。

根据账户的流量限制，轮播帖子算作单个帖子。

限制

轮播帖子无法速推。
轮播帖子中，图片和/或视频总数不得超过 10。
轮播图片都是根据轮播帖子中的第一张图片进行裁剪，默认为 1:1 宽高比。

第 1 步（共 3 步）：创建内容容器

使用 POST /{ig-user-id}/media 端点为轮播中将出现的图片或视频创建内容容器。轮播帖子中，图片和/或视频总数不得超过 10。

POST /{ig-user-id}/media

参数

以下参数为必要项。如需了解其他受支持的参数，请参阅 POST /{ig-user-id}/media 端点参考文档。

is_carousel_item — 设为 true。表示图片或视频将出现在轮播帖子中。
image_url — （仅适用于图片）图片的路径。我们将使用传入的网址对您的图片执行 cURL 请求，因此该图片必须位于公共服务器上。
media_type — （仅适用于视频）设为 VIDEO。表示素材为视频。
video_url — （仅适用于视频）视频的路径。我们将使用传入的网址对您的视频执行 cURL 请求，因此该视频必须位于公共服务器上。

如果操作成功，API 将返回一个项目容器编号，该编号可以在创建轮播容器时使用。

对应出现在轮播中的各个图片或视频重复此过程。

请求示例

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

响应示例

{
  "id": "17899506308402767"
}

第 2 步（共 3 步）：创建轮播容器

使用 POST /{ig-user-id}/media 端点创建轮播容器。

POST /{ig-user-id}/media

参数

以下参数为必要项。如需了解其他受支持的参数，请参阅 POST /{ig-user-id}/media 端点参考文档。

media_type — 设为 CAROUSEL。表示容器用于轮播。
children — 至多 10 个容器编号的数组，其中每个编号都对应着发布后的轮播帖子中将显示的各个图片和视频。轮播帖子中，图片和/或视频总数不得超过 10。

请求示例

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

响应示例

{
  "id": "18000748627392977"
}

第 3 步（共 3 步）：发布轮播容器

使用 POST /{ig-user-id}/media_publish 端点发布轮播容器（轮播帖子）。每个账户在 24 小时内仅能发布 50 条帖子。发布的轮播帖子算作单个帖子。

POST /{ig-user-id}/media_publish

参数

以下参数为必要项。

creation_id — 轮播容器编号。

如果操作成功，API 将返回一个轮播相册 Instagram 素材编号。

请求示例

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

响应示例

{
  "id": "90010778390276"
}

Reels 帖子

Reels 指代可显示在 Reels 图卡中的合格短视频，这类视频需符合一定规格，并被我们的算法选中。如要发布 Reels，请按照发布单一素材帖子的步骤操作，并使用 video_url 参数在视频路径中加入 media_type=REELS 参数。

虽然您在发布 Reels 时需要设置 media_type=REELS，但是 Reels 并非新的素材类型。如果您发布 Reels，然后请求其 media_type 字段，系统将返回的值为 VIDEO。如要确定是否已将发布的视频指定为 Reels，请改为请求其 media_product_type 字段。

您可使用 GitHub 中的代码示例 (insta_reels_publishing_api_sample) 了解如何向 Instagram 发布 Reels。

为进一步提升开发者的便利性，Meta 在 Postman API 平台上发布了一整套用于 Instagram Reels 的图谱 API 调用。详情请参阅用于 Facebook Reels 和 Instagram Reels 的 Postman 收藏夹。

如需详细了解 Reels，请参阅 Reels 开发者文档。

快拍帖子

目前，仅业务账户可使用内容发布 API 发布快拍。

快拍是在 Instagram 上发布为 Instagram 快拍的视频和图片。如要发布快拍，请按照与发布单一素材帖子相同的步骤操作，并加入 media_type=STORIES 参数，使用 image_url 或 video_url 参数设置图片或视频的路径。

注意：虽然您在发布快拍时需要设置 media_type=STORIES，但是快拍并非新的素材类型。如果您发布快拍，然后请求其 media_type 字段，系统将返回的值为 IMAGE/VIDEO。如要确定是否已将发布的图片或视频指定为快拍，请改为请求其 media_product_type 字段。

合作者标记

您可以在图片、轮播和 Reels 中将 Instagram 账户为公开的用户添加为合作者，他们会收到有关成为该特定素材合作者的邀请。如要标记图片中的用户，请按照上方“单一素材帖子”中的步骤操作，但在创建素材容器时，请添加 collaborators 参数和一个字符串数组，以表示您想要邀请成为该素材合作者的用户的 Instagram 账户。

请求示例

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

注意

collaborators 值必须为一个字符串数组。
您只能标记 Instagram 账户为公开的用户。
最多只能为一个素材添加 3 个合作者。
无法为快拍素材添加合作者。

地点标签

您可以使用公共主页搜索 API ，确保在查询中加入“地点”字段，以搜索名称与搜索字符串匹配的公共主页。然后解析结果，确定已为某个实际位置创建的任何公共主页。如果您在发布图片或视频时加入公共主页的编号，则系统将为该图片或视频标记与公共主页相关联的地点。

限制

为符合标记条件，公共主页必须拥有包含经纬度的位置数据。

验证您要使用的公共主页响应中是否包含经纬度数据。如果您试图用不具备位置数据的公共主页创建容器，操作会失败，并会返回异常代码 INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID。

获得公共主页编号后，请在发布单一素材或轮播内容容器时将该编号分配给 location_id 参数。

商品标记

您可以发布带有 Instagram 购物商品标签的单一素材帖子和轮播帖子。如需了解具体方法，请参阅商品标记指南。

用户标记

您可以在图片中标记公开账户的 Instagram 用户，他们将在被标记时收到通知。

如要标记图片中的用户，请按照上方单一素材帖子中的步骤进行操作，但在创建素材容器时，请添加 user_tags 参数和对象数组，以标示图片中的 Instagram 用户及其在图片中的 x/y 坐标。

请求示例

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 } ]

此操作将返回一个容器编号，然后您可以使用 Instagram 用户素材发布端点发布该编号。

注意

user_tags 值必须为 JSON 格式的对象数组。
您只能标记 Instagram 账户为公开的用户。
对象必须包含每位用户的所有三个属性（username、x 和 y）。
x 和 y 值必须为源自图像左上方的 float 数，范围为 0.0–1.0。
用户标记可用于轮播中的图片。

疑难解决

如果您能够创建视频容器，但 POST /{ig-user-id}/media_publish 端点并未返回要发布的素材编号，则可以通过查询 GET /{ig-container-id}?fields=status_code 端点获取容器的发布状态。此端点会返回以下其中一种状态：

EXPIRED — 容器未在 24 小时内发布，已过期。
ERROR — 容器无法完成发布流程。
FINISHED — 已准备好发布容器及其素材对象。
IN_PROGRESS — 容器仍处于发布阶段。
PUBLISHED — 已发布容器的媒体对象。

我们建议每分钟查询一次容器状态，查询时间不应超过 5 分钟。

错误

请查看错误代码参考文档。