Instagram 开放平台
返回中文(简体)
文档已更新。
中文(简体) 译文尚未完成。
英语更新时间：10月27日

Instagram 媒体

表示 Instagram 相册、照片或视频（已上传的视频、直播视频、使用 Instagram TV 应用创建的视频、Reels 或快拍）。

从 2024 年 6 月 3 日开始，您可以使用 boost_eligibility_info 字段作为一种方便高效的方式，来确定媒体是否符合以广告形式速推的条件，还可以使用 boost_ads_list 来追踪与相应广告相关的速推后 Instagram 广告信息。详情请参阅此博客。仅适用于 Instagram 图谱 API。

创建

不支持此操作。

读取

GET /<IG_MEDIA_ID>

获取 Instagram 媒体的字段和连线。

限制

  • 返回总值的字段不会包括广告带来的数据。例如，comments_count 会计算照片的评论量，但不会计算包含该照片的广告的评论量。
  • 除非应用用户也可在应用上执行管理员级别的任务，否则说明将不包含 @ 符号。
  • 某些字段（如 permalink）不适用于相册中的照片（子媒体）。
  • 直播视频 Instagram 媒体仅在直播时才能读取。
  • 此 API 仅返回 Instagram 专业账户所拥有媒体的数据，无法用来获取 Instagram 个人账户所拥有媒体的数据。

请求语法

GET https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?fields=<LIST_OF_FIELDS>
  &access_token=<ACCESS_TOKEN>

路径参数

占位符值

<API_VERSION>

API 版本。

<IG_MEDIA_ID>

必要。待发布素材的编号。

查询字符串参数

键占位符值

access_token

<ACCESS_TOKEN>

必要。应用用户的用户访问口令

fields

<LIST_OF_FIELDS>

您希望返回的以逗号分隔的字段清单。

字段

可通过字段扩展读取的公开字段。

字段描述

boost_ads_list

概要提供了与特定自然媒体关联的所有 Instagram 广告信息，包括相应的广告编号和广告投放状态。仅适用于 Instagram 图谱 API。

boost_eligibility_info

此字段提供了相关信息，说明 Instagram 媒体是否符合以广告形式进行速推的资格，并且如果不符合资格，还会提供更多详情。仅适用于 Instagram 图谱 API。

caption
公开

说明。不包括相册子媒体。如果已将 Facebook 公共主页绑定到用于创建此说明的 Instagram 账户（仅适用于 Instagram 图谱 API），而应用用户无法在该公共主页上执行管理员级别的任务，则不包括 @ 符号。

comments_count
公开

针对媒体的评论数量。不包括对相册子媒体及媒体说明的评论。包括对评论的回复。

copyright_check_information.status

返回 status 和 matches_found 对象

状态对象描述

status

  • completed – 检测过程已结束
  • error – 检测过程中出现错误
  • in_progress – 正在检测
  • not_started – 检测过程尚未开始

matches_found

设为以下值之一：

  • false – 如果视频未侵犯版权
  • true – 如果视频侵犯了版权

如果视频正在侵犯版权，系统将返回 copyright_matches，其中包含关于以下内容的一组对象：受版权保护材料，视频中发生侵权的时间以及为减轻侵权而采取的措施。

copyright_matches 对象描述

author

受版权保护视频的作者

content_title

受版权保护视频的名称

matched_segments

包含以下键值对的一组对象：*duration_in_seconds – 内容侵犯版权的秒数 * segment_type – AUDIO 或 VIDEO * start_time_in_seconds – 设为视频的开始时间

owner_copyright_policy

返回的对象中包含：

  • name – 版权所有者所遵循的版权保护政策名称

  • actions – 一组 action 对象，其中包含根据版权所有者所遵循的版权保护政策规定，为减轻违规影响而需要采取的措施。针对不同位置，可能包含不同减轻步骤。

    • action – 针对侵犯版权的视频的减轻措施。不同的国家可采取不同的减轻步骤。可以是以下值之一：
      • BLOCK – 阻止 geos 数组中列出的受众观看某个视频
      • MUTE - 为 geos 数组中列出的受众关闭视频的声音

id
公开

媒体编号。

is_comment_enabled

表示评论处于启用还是停用状态。不包括相册子媒体。

is_shared_to_feed
公开

仅适用于 Reels。如果为 true，表示 Reels 可以同时在动态和 Reels 选项卡中显示。如果为 false，则表示 Reels 只可在 Reels 选项卡中显示。

这两个值都不表示 Reels 是否会实际显示在 Reels 选项卡中，因为 Reels 可能不符合资格要求或未被我们的算法选中。有关资格标准，请参阅 Reels 规格。

like_count

媒体的获赞数，包括对评论的赞。不包括相册子图片媒体和使用此媒体创作的推广帖子获得的赞。


如果媒体所有者已隐藏获赞数，则用户通过另一个端点或字段扩展间接查询 like_count 字段时，此字段将省略。

media_product_type
公开

媒体的发布平台。可以是 AD、FEED、STORY 或 REELS。仅适用于 Instagram 图谱 API。

media_type
公开

媒体类型。可以是 CAROUSEL_ALBUM、IMAGE 或 VIDEO。

media_url
公开

媒体网址。

如果媒体包含受版权保护的内容，或者已被标记为违反版权的内容，系统会从响应中删除 media_url 字段。在 Reels 上，受版权保护的内容示例可包含音频。

owner
公开

创建媒体的 Instagram 用户的编号。仅在发出查询请求的应用用户也是媒体的创建者时才会返回此字段，否则将返回 username 字段。

permalink
公开

媒体的永久网址。

shortcode
公开

媒体的短代码。

thumbnail_url
公开

媒体缩略图网址。仅适用于 VIDEO 媒体。

timestamp
公开

ISO 8601 格式的创建日期（UTC 时间，默认值为 UTC ±00:00）。

username
公开

创建媒体的用户的账号。

连线

可通过字段扩展返回的公开连线。

连线描述

children
公开。

表示 Instagram 媒体相册中的 Instagram 媒体对象集合。

collaborators

表示作为合作者添加到 Instagram 媒体对象上的用户的名单。仅适用于 Instagram 图谱 API。

comments

表示对 Instagram 媒体对象的 Instagram 评论的集合。

insights

代表 Instagram 媒体对象的社交互动指标。仅适用于 Instagram 图谱 API。

cURL 示例

请求示例

curl -X GET \
  'https://graph.instagram.com/v21.0/17895695668004550?fields=id,media_type,media_url,owner,timestamp&access_token=IGQVJ...'

响应示例

{
  "id": "17918920912340654",
  "media_type": "IMAGE",
  "media_url": "https://sconten...",
  "owner": {
    "id": "17841405309211844"
  },
  "timestamp": "2019-09-26T22:36:43+0000"
}

更新

POST /<IG_MEDIA_ID>

启用或禁用对 Instagram 媒体的评论。

限制

不支持直播视频 Instagram 媒体。

Requirements

Instagram API with Instagram LoginInstagram API with Facebook Login

Access Tokens

  • Instagram User access token

Host URL

graph.instagram.com

graph.facebook.com

Login Type

Business Login for Instagram

Facebook Login for Business

Permissions
  • instagram_business_basic
  • instagram_business_manage_comments
  • instagram_basic
  • instagram_manage_comments
  • pages_read_engagement
  • pages_show_list

If the app user was granted a role via the Business Manager on the Page connected to the targeted IG User, you will also need one of:

  • ads_management
  • business_management

请求语法

POST https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?comment_enabled=<BOOL>
  &access_token=<ACCESS_TOKEN>

路径参数

占位符值

<API_VERSION>

API 版本。

<IG_MEDIA_ID>

必要。Instagram 媒体编号。

查询字符串参数

键占位符值

access_token

<ACCESS_TOKEN>

必要。应用用户的用户访问口令。

comment_enabled

<BOOL>

必要。设置为 true 可启用评论，设置为 false 可禁用评论。

cURL 示例

请求示例

curl -i -X POST \
 "https://graph.instagram.com/v21.0/17918920912340654?comment_enabled=true&access_token=EAAOc..."

响应示例

{
  "success": true
}

删除

不支持此操作。