概览

Instagram Basic Display API 是一款基于 HTTP 的 API，应用可借此获取 Instagram 用户的个人主页、图片、视频和相册。

组件

基本网址

• api.instagram.com — 用于获取 Instagram 用户访问口令
• graph.instagram.com — 用于获取 Instagram 用户个人主页与多媒体素材

版本

API 支持与 Facebook 图谱 API 相同的版本管理协议与发布周期。新版本大约每 3 个月发布一次，每个版本可用时间约为 2 年，然后才会停用。

要查询指定 API 版本，请在基本网址后的查询路径中添加版本号。例如：

https://graph.instagram.com/v11.0/10218560180051171/media

如果您忽略了请求中的版本号，则该请求会解析应用面板 > 设置 > 高级 > 升级 API 版本版块中指定的版本。

授权窗口

借助授权窗口，您的应用可以获取应用用户的授权码和权限。授权码可用于交换 Instagram 用户访问口令，应用必须拥有此口令才能查询应用用户的个人主页或多媒体素材。

如要部署授权窗口，请参阅我们的获取访问口令指南。

授权码

授权码可用于交换短期 Instagram 用户访问口令。如要获取授权码，请将授权窗口部署到应用中。应用用户在通过窗口验证其身份信息并授予应用所需的所有权限后，我们会将用户重定向至您的应用，并附上授权码。然后，您可以使用 API 交换应用用户的短期 Instagram 用户访问口令代码。

授权码是短期口令，有效期仅为 1 小时。

Instagram 用户访问口令

API 身份验证由遵照 OAuth 2.0 协议的 Instagram 用户访问口令处理。访问口令是应用范围口令（应用和用户对的独有口令），可以是短期或者长期口令。查询 Instagram 用户或其多媒体素材的 API 请求必须包含 Instagram 用户访问口令。

短期访问口令

短期访问口令的有效期为 1 小时，但可更换为长期口令。如要获取短期访问口令，请将授权窗口部署到应用中。应用用户通过窗口验证其身份信息后，我们会将用户重定向回您的应用，并附上授权码，然后您可以用该授权码交换短期访问口令。

长期访问口令

尚未过期的短期口令可以更换为长期访问口令（有效期为 60 天）。您可以查询 GET /refresh_access_token 端点，在长期口令失效前刷新口令。

权限

数据访问授权由您的应用用户使用下列权限进行控制。用户必须通过授权窗口向您的应用授予这些权限，这样您的应用才可以访问用户数据。

• instagram_graph_user_profile — 允许您的应用读取代表 Instagram 用户的用户节点和节点连线。
• instagram_graph_user_media — 允许您的应用读取代表图片、视频或相册的素材节点和该节点的连线。

Instagram 测试者可以在任何时候为您的应用授予这些权限。为了让在您的应用上没有身份的应用用户能够向该应用授予这些权限，每个权限都必须首先通过应用审核流程获得高级访问级别，并且您的应用必须处于上线模式。

使用公开账户的应用用户的许可权限有效期为 90 天。如果授予口令的应用用户拥有公开账户，那么刷新应用用户的长期访问口令会将许可权限有效期再延长 90 天。如果应用用户的账户是私密账户，则许可权限的有效期无法延长，应用用户必须在该权限过期后再次将其授予给您的应用。

Instagram 测试者

如要通过 Instagram 用户测试您的应用，必须首先向 Instagram 用户账户发送邀请并且对方同意邀请。可以前往应用面板 > 身份 > 身份选项卡内的 Instagram 测试者版块发送邀请。

Instagram 用户登录账户后，可以前往 Instagram 网站或移动应用中的（个人主页图标）> 编辑个人主页 > 应用和网站 > 测试者邀请版块接受邀请。

资源

该 API 中的数据包括 Instagram 用户及其素材（图片、视频和相册）。所有数据均通过权限保护；为使您的应用能够访问用户数据，用户必须通过授权窗口向您的应用授予执行此操作的权限。

用户

Instagram 用户及其个人主页由用户节点表示。请注意，Instagram 旧版 API 用户编号与 Instagram Basic Display API 不兼容。

素材

照片、视频和相册由素材节点表示，并会根据各个用户进行创建。

流量限制

所有端点均需遵循图谱 API 的平台流量限制。

将 Instagram 产品添加到应用之后，您可在应用面板 > Instagram > 基本显示流量限制选项卡中查看应用当前已使用的调用次数。

应用类型

不支持指定为业务应用的应用。如果您的应用是业务应用，请改为使用 Instagram 图谱 API，或者创建一个新的非业务应用。

应用审核

Instagram 测试者可以在任何时候为您的应用授予 Instagram 权限。为了让在您的应用上没有身份的应用用户能够向该应用授予 Instagram 权限，每个权限都必须首先通过应用审核流程获得高级访问级别，并且您的应用必须处于上线模式。

完成应用开发并准备好将应用切换为上线模式后，请查看《应用审核》、《提交示例》和《常见被拒原因》文档，以了解应用审核流程。熟悉流程后，您可以通过应用面板 > 产品 > Instagram > 基本显示选项卡，请求批准 Instagram Basic Display API 权限。

如果仅出于使用用户口令生成器生成访问口令的目的而创建应用，则无需提交您的应用进行应用审核。用户口令生成器不需要任何权限，并且可以在您的应用处于开发模式时使用。

公司验证

在开发模式期间，应用只能访问 Instagram 测试者账户中的数据。在将应用切换为上线模式并访问非测试者账户中的数据之前，您必须先完成公司验证。

运作方式

如要使用 API，首先请获取授权窗口并将其显示给应用用户。应用用户会通过此窗口验证其身份信息，然后向您的应用授予特定权限，以授权应用访问其数据。完成验证后，窗口会重定向回您的应用，并附上一个授权码。捕获代码并用其交换短期 Instagram 用户访问口令。获得短期口令后，您可以使用该口令查询用户允许应用访问的任何数据的用户和多媒体素材端点，或将其更换为长期口令。

工具

用户口令生成器

利用 Instagram 用户口令生成器这一工具，您可以快速生成适用于您任何公开 Instagram 账户的长期 Instagram 用户访问口令。如果您正在测试您的应用，并且不希望因部署授权窗口而干扰测试，或者您在使用由第三方服务提供的可复制和粘贴的代码（例如在自己的网站上显示您个人的 Instagram 数据），则此工具非常有用。

该工具通过触发授权窗口来运行，您可以使用已指定为测试者账户的公开 Instagram 账户进行登录。当您登录后，该工具会生成可复制和粘贴的长期访问口令。请注意，该工具仅会生成适用于公开 Instagram 账户的口令。

您可在应用面板 > 产品 > Instagram > 基本显示选项卡中使用口令生成器。

如果仅出于使用用户口令生成器生成访问口令的目的而创建应用，则无需提交您的应用进行应用审核。用户口令生成器不需要任何权限，并且可以在您的应用处于开发模式时使用。

后续步骤

请遵循我们的新手入门指南，了解如何设置应用和执行基本 API 请求。