内容发布

您可以使用 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/v20.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/v20.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/v20.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/v20.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/v20.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 字段。

可续传上传协议

可续传上传协议是一个全新的 Instagram 内容发布流程，支持 Reels、视频快拍和视频轮播内容 media_types 的视频上传。

该新协议支持利用本地视频和公开托管网址视频来创建 Instagram 素材。该协议支持在出现网络中断或其他传输故障后恢复本地文件上传操作，从而在出现网络故障时节省时间和带宽。它将保留相同的素材规格。

端点

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media — 通过设置 upload_type=resumable 来启动视频创建容器。
POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id} — 通过使用可续传上传协议，更可靠地从本地视频文件或托管网址上传视频。
POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish — 使用素材容器发布已上传的素材。
GET /{ig-container-id}?fields=status_code — 检查素材容器的发布资格和状态。

HTML 网址编码提示

支持一些参数使用列表/字典格式。
对于部分字符，需要将其编码为可通过互联网传输的格式。例如：将 user_tags=[{username:’ig_user_name’}] 编码为 user_tags=%5B%7Busername:ig_user_name%7D%5D，在其中，将 [ 编码为 %5B，同时将 { 编码为 %7B。有关更多字符转换，请参阅 HTML 网址编码标准。

第 1 步：为 Reels、视频快拍或轮播内容发起上传会话

Reels 请求示例

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

视频快拍请求示例

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

轮播视频内容请求示例

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

响应示例

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

第 2 步：使用可续传上传协议上传视频

大多数图谱 API 调用使用 graph.facebook.com 主机，而 Reels 的上传视频调用使用 rupload.facebook.com。

支持以下文件来源的已上传视频文件：

您电脑上的文件
公开服务器（如 CDN）上托管的文件

本地视频文件上传请求示例

在可续传上传会话返回 ig-container-id 后，上传视频。

确保主机是 rupload.facebook.com。
所有 media_type 使用同一个流程来上传视频。
ig-container-id 是可续传上传会话调用返回的编号。
access-token 是之前步骤中使用的同一个访问口令。
offset 设为要上传的第一个字��，通常是 0。
file_size 设为文件大小，以字节为单位。
Your_file_local_path 设为本地文件的文件路径。例如：如果要上传 macOS 上 Downloads 文件夹中的一个文件，路径就会是 @Downloads/example.mov。

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

公开托管视频上传请求示例

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

响应示例

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

第 3 步（仅限轮播）：创建轮播容器

您可以再次使用第 1-2 步来创建多个 ig-container-ids，将 is_carousel_item 参数设为 true。然后创建一个轮播容器来容纳所有轮播内容，轮播内容可以与图片和视频混合使用。

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

第 4 步：发布素材

对于 Reels 和视频快拍，第 1 步中创建的 {ig-container-id} 用于发布视频；对于轮播容器，第 3 步中创建的 {ig-container-id} 用于发布轮播容器。

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

第 5 步：获取素材状态

graph.facebook.com 提供一个 GET 端点来读取上传状态，video_status 字段包含本地上传过程的详情。

uploading_phase 将表明文件是否已上传成功以及已传输多少字节。
processing_phase 包含视频文件上传后视频处理状态的详情。

// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

`graph.facebook.com` 端点返回的响应示例

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

合作者标记

您可以在图片、轮播和 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 分钟。

错误

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

内容发布

要求

访问口令

权限

公共服务器

公共主页发布授权

限制

流量限制

端点

单一素材帖子

请求示例

响应示例

请求示例

响应示例

轮播帖子

参数

请求示例

响应示例

参数

请求示例

响应示例

参数

请求示例

响应示例

Reels 帖子

快拍帖子

可续传上传协议

端点

HTML 网址编码提示

第 1 步：为 Reels、视频快拍或轮播内容发起上传会话

Reels 请求示例

视频快拍请求示例

轮播视频内容请求示例

响应示例

第 2 步：使用可续传上传协议上传视频

本地视频文件上传请求示例

公开托管视频上传请求示例

响应示例

第 3 步（仅限轮播）：创建轮播容器

第 4 步：发布素材

第 5 步：获取素材状态

graph.facebook.com 端点返回的响应示例

合作者标记

请求示例

备注

地点标签

限制

商品标记

用户标记

请求示例

备注

疑难解决

错误

`graph.facebook.com` 端点返回的响应示例