Instagram 开放平台

Instagram oEmbed

您可查询 Instagram oEmbed 端点，从而获取 Instagram 帖子的嵌入式 HTML 和基本元数据，以便在其他网站或应用中展示帖子内容。支持照片、视频、Reels 和导览帖子。

常见用途

  • 在消息应用中展示帖子。
  • 在网站和博客中嵌入帖子。
  • 在内容管理系统中展示帖子。

端点

端点描述

GET /instagram_oembed

获取 Instagram 帖子的嵌入式 HTML 和基本元数据。

要求

限制

  • Instagram oEmbed 端点仅用于在网站和应用中嵌入 Instagram 内容。不可将其用于任何其他用途。严禁将来自端点的元数据、主页、帖子或视频内容（或其衍生内容）用于除提供主页、帖子或视频前端视图以外的任何其他用途。此限制涵盖使用、操纵、提取或保留元数据和内容的行为，包括但不限于从元数据中获取关于公共主页、帖子和视频的信息以供分析。
  • 不支持私密、不再使用和有年龄限制的 Instagram 账户上的帖子。
  • 不支持已禁用嵌入的账户。
  • 不支持快拍。
  • 不支持 Shadow DOM。

应用审核

如要使用 oEmbed，您的应用必须完成针对 oEmbed Read 功能的应用审核。

在填写提供用于测试 Oembed Read 的网址表单字段时，请使用 Instagram oEmbed 端点获取我们官方 Facebook 公共主页或 Instagram 公共主页上任一公开帖的嵌入式 HTML（或获取其中一个公共主页的嵌入式 HTML）。将返回的嵌入式 HTML 添加到您自己的页面（即要显示 oEmbed 内容的页面），然后在表单字段中输入该页面的网址。

在您获准使用 oEmbed Read 功能后，您可以使用相应网址嵌入您的公共主页、帖子或视频。

访问口令

Instagram oEmbed 端点需要使用应用访问口令（推荐）或客户端访问口令。

应用访问口令

如果您的应用需要使用后端服务器，推荐您使用应用访问口令来访问 oEmbed 端点。流量限制取决于请求中的口令类型，应用口令流量限制为每天 500 万次请求。

如需应用访问口令生成说明，请查阅访问口令文档中的应用口令版块。

请注意，应用访问口令不可用于客户端。口令必须始终在您的服务器上加密存储。如果您的应用必须使用客户端口令，请改为使用客户端访问口令。

客户端访问口令

如果应用必须通过移动设备、网页浏览器等用户代理访问 oEmbed 端点，则应用须使用客户端访问口令，并需遵循客户端口令流量限制。

要获取客户端访问口令，请登录应用面板，并前往设置 > 高级 > 账户安全 > 客户端口令。

不同于应用访问口令，客户端访问口令无法单独在 oEmbed 端点请求中使用，而须配合应用编号使用。如要执行此操作，请在应用编号末尾附加口令，并使用竖线 (|) 分隔：

{app-id}|{client-token}

例如：

access_token=1234|5678

流量限制

流量限制取决于每次请求中包含的应用访问口令类型。

应用口令流量限制

使用应用访问口令的应用每 24 小时最多可发出 500 万次请求。

客户端口令流量限制

客户端口令流量限制显著低于应用口令流量限制。由于实际的流量限制会因应用活动而异，所以我们没有列出实际数值。然而，应用一般不会达到此限制，除非其展示出类似于机器人的行为，例如批量发送数千次请求，或每个代理或应用用户均发出数千次请求。

获取嵌入式 HTML

要获取 Instagram 帖子的嵌入式 HTML，请发送请求至：

GET /instagram_oembed?url={url}&access_token={access-token}

将 {url} 替换为想要查询的 Instagram 帖子的网址，并将 {access-token} 替换为您的应用或客户端访问口令（或使用 HTTP 标头向我们传送口令）。如果您使用的是客户端访问口令，请务必将口令与应用编号结合使用，并用竖线分隔，否则请求将失败。

成功后，API 将在响应中返回 JSON 对象，其中包含帖子的嵌入式 HTML 和其他数据。嵌入式 HTML 将指定到 html 属性。

如需获取可用于扩展请求的查询字符串参数列表，请参阅 Instagram oEmbed 参考文档。您还可添加 fields 查询字符串参数，以指定需要返回的字段。如不指定，响应中将包含所有默认字段。

请求示例

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

响应示例

示例中使用省略号 (...) 截断了某些值以方便阅读。

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

网址格式

url 查询字符串参数接受下列网址格式：

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

嵌入式 JS

嵌入式 HTML 包含对 Instagram embed.js JavaScript 库的引用。库载入后会扫描页面中的帖子 HTML，并生成完全展示的帖子。如要单独加载库，请在请求中添加 omitscript=true 查询字符串参数。如要手动初始化嵌入式 HTML，请在库加载后调用 instgrm.Embeds.process() 函数。

帖子大小

嵌入式帖子为响应式，可适应容器的大小。这表示，帖子的高度会随容器宽度和文字长度而改变。您可在请求中添加 maxwidth 查询字符串参数以设置最大宽度。

获取缩略图

推荐您尽可能展示帖子的所有嵌入式 HTML。如果无法做到这一点，您可获取帖子的缩略图图像网址，并改为展示此缩略图。但要进行此操作，您必须在图像旁提供明确的来源（包括原作者和 Instagram 的来源），并要提供所查询的 Instagram 帖子的链接。

要获取帖子的缩略图网址和来源信息，请发送请求至：

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

将 {url} 替换为想要查询的 Instagram 帖子的网址，将 {maxwidth} 替换为想要展示的缩略图的最大尺寸，并将 {access-token} 替换为您的应用或客户端访问口令。

请求示例

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

响应示例

示例中使用省略号 (...) 截断了某些值以方便阅读。

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

使用标头传送访问口令

如果不想在请求的查询字符串中添加访问口令，您可改为使用 Authorization HTTP 标头将其传送给我们。

Authorization: Bearer {access-token}

例如：

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
  --header "Authorization: Bearer 96481..."