Instagram 公开数据 API：资料、帖子和 Reels | SandBase

用程序抓 Instagram 的公开数据，麻烦的从来不是你要做的那个功能，而是开头那一个小时：绕登录墙、维护 token、还要一个个字段去试，才知道粉丝数到底藏在哪个字段里。浏览器里明明看得到的公开数据，真要稳定地接进 Agent，往往先变成一个独立的小工程。

SandBase 的 Instagram 公开数据 API 就是来省掉这段的。它通过一组普通 REST 端点 /v1/api/{vendor}/{path}，读取 Instagram 的公开资料、帖子、Reels、粉丝、评论和话题——一把 SandBase Key、同步返回 JSON，不走 Instagram OAuth，也不用装 SDK。端点参考只保证信封（id、status、model 和 outputs[0].data）；下面展示的业务字段是示例结构、并非保证的 schema，请以真实响应为准核对具体字段。

这不是 Meta 官方的 Instagram Graph API。 如果你要管理已授权的 Business/Creator 账号、发布内容、或读取只有账号所有者才能看的 insights，请用 Meta 的 Instagram Platform。而如果你的工作流需要的是公开、只读的发现或监控数据，就用 SandBase。想上手的话：获取 SandBase API Key、浏览 Instagram 端点。

先说结论

一套 API 读取 Instagram 资料、粉丝/关注、帖子、Reels、快拍、评论、话题和地点数据。

每个能力是独立的 POST /v1/api/instagram/<path> 端点——body 里只传该端点的参数，无 SDK，一把 SANDBASE_API_KEY。

接口有 v1/v2/v3 三代 schema，v3 最完整，且在大多数列表接口上支持分页。

只返回公开、只读数据；不能发帖、不走 Instagram OAuth 登录、也无法访问私密账号；用一把 SandBase API Key 鉴权。

你需要哪种 Instagram API？

你的需求	选谁	原因
发布内容、回复评论、或查看已授权的专业账号	Meta Instagram Graph API	Meta 官方 API 为 Business/Creator 账号管理和所有者 insights 而设计。
读取公开的资料、帖子、Reel、话题、地点或粉丝数据	SandBase Instagram 公开数据 API	普通 REST 调用、一把 SandBase Key、只读工作流的结构化 JSON。
访问私密账号、私信、或需登录才能看的数据	都不行	这类数据不在公开数据 API 的范围内。

Instagram API 能拿到什么

这套 Instagram 公开数据 API 面向的是公开、只读的发现和监控场景——不做账号管理、也不碰私密数据。做分析、监控、研究类 Agent 会用到的数据，基本都在里面，按用途分几类：

用户数据——资料与简介、profile/brief 视图、用户 ID 与用户名互转、历史用户名、粉丝与关注列表、相似与相关账号。
内容——某用户的帖子、Reels、被标记帖子、转发、快拍和精选；按 ID、URL 或 shortcode 取单条帖子；oEmbed 数据。
互动——帖子评论、评论回复、点赞，以及评论/文案翻译。
发现——按话题、地点、音乐取帖子；explore 信息流和推荐 Reels。
搜索——用户、话题、地点（含按坐标）、音乐、Reels，以及综合搜索。
工具——media ID 与 shortcode 互转，以及从 URL 提取 shortcode。
批量——一个 bulk 组，覆盖 profile、posts、hashtag-posts、search 和内容抽取；接入前请以线上 catalog 为准确认可用端点。

不用记这份清单。下面这个调用模式，对每一个接口都一样。

SandBase Instagram API 页面：描述、能力标签，以及 Instagram Endpoints 列表 SandBase 上的 Instagram API 页——带标签的概览和完整端点列表，每个端点都有 GET 路径和说明。

Instagram 提供什么，SandBase 补什么

公开数据本身来自 Instagram，SandBase 既不拥有也不运营 Instagram，它做的是为合规的公开数据场景提供一层统一的 API 接入：每个能力对应一个固定的端点名，鉴权收敛成一把 Key，响应结构也稳定可预期。这样一来，“先按用户名查到账号 → 再拉粉丝 → 再读他们的近期帖子”这样一条链路，Agent 就能顺着一套约定走完，不用为每一步各配一套鉴权和解析。

快速上手：第一次调用

每个能力都有自己的 REST 端点，路径为 /v1/api/{vendor}/{path}，与 model 名一一对应——instagram/v1/user-info-by-username 就在 /v1/api/instagram/v1/user-info-by-username 调用。SandBase 没有专属 SDK，这些都是普通 HTTP 调用。按用户名取资料：

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/instagram/v1/user-info-by-username",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"username": "nasa"},  # 只传该端点的参数
)
resp.raise_for_status()
body = resp.json()  # 同步返回，JSON 即结果，无需轮询
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "Instagram 请求未完成"))

# 业务字段是示例结构、并非保证的 schema，请用防御式读取。
profile = body["outputs"][0]["data"].get("data", {}).get("user", {})
print(profile.get("username"), profile.get("edge_followed_by", {}).get("count"))

curl -X POST https://api.sandbase.ai/v1/api/instagram/v1/user-info-by-username \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "nasa"}'

这个端点只有 username 一个必填参数。调哪个能力已经写在 URL 里了，所以 body 里只放这个端点自己的参数就行。数据端点都是 sync 模式，请求返回的 JSON 就是最终结果，没有 task ID，也不用轮询。

响应的外层结构是固定的：一个 id、一个 status（成功时是 completed）、model 名称，再加一个 outputs 数组，真正的业务数据放在它唯一那个元素的 data 里。下面是 user-info-by-username 的示例响应结构——其中业务字段是示例结构、并非保证的 schema，资料对象字段很多、这里只截取一部分，粉丝数等实时数值也会随时间变化；请以真实响应为准核对具体字段：

{
  "id": "1997037f-ddc0-40ab-b96f-dc32a524ebb0",
  "status": "completed",
  "model": "instagram/v1/user-info-by-username",
  "outputs": [
    {
      "data": {
        "data": {
          "user": {
            "username": "nasa",
            "full_name": "NASA",
            "is_verified": true,
            "is_private": false,
            "biography": "Making the seemingly impossible, possible. ✨",
            "external_url": "https://www.nasa.gov/",
            "edge_followed_by": { "count": 104335721 },
            "edge_follow": { "count": 89 },
            "edge_owner_to_timeline_media": { "count": 4934 }
          }
        }
      }
    }
  ]
}

如果 status 是 failed 或 timeout，响应里会有 error（带 type 和脱敏过的 message），且不会有 outputs，所以取 outputs[0].data 之前先判断一下 status。另外注意资料本身在 outputs[0].data.data.user 这一层——第一次接的时候，先打一条真实响应出来，把路径对准一次。

SandBase 上 POST /v1/api/instagram/v1/user-info-by-username 的 API 参考文档，展示 vendor-qualified URL、cURL 示例和响应结构 API 参考文档写明了这套约定：调用 vendor-qualified URL，body 里只放该操作的参数；每个端点都提供 cURL、Python、TypeScript 示例。

能力速查

能力簇	代表接口	典型用途
用户资料与 ID	`instagram/v1/user-info-by-username`	把用户名解析成资料字段和用户 ID
粉丝 / 关注	`instagram/v3/user-followers`	受众与关系网分析（分页）
帖子与 Reels	`instagram/v3/user-posts`、`instagram/v3/user-reels`	内容监控、互动追踪
评论与翻译	`instagram/v3/post-comments`、`instagram/v3/translate-comment`	情感分析、多语言评论处理
话题 / 地点 / 音乐	`instagram/v3/hashtag-posts`	趋势与活动发现
搜索	`instagram/v3/search-users`	查找账号、话题或地点
ID 工具	`instagram/v1/shortcode-to-media-id`	把帖子 URL 转成 media ID

接口分 v1、v2、v3 三代。当同一能力有多个版本时，优先用 v3——它最完整，并在大多数列表接口上提供 max_id 分页游标。

常见用例

用 Instagram profile API 做达人发现

先用 instagram/v1/user-info-by-username 解析账号，再读 edge_followed_by.count、分类和简介，按体量和领域筛出候选达人。输入：一个用户名或一批候选。输出：每个达人一条可对比的资料记录。端点：user-info-by-username，需要先找候选时配合 instagram/v3/search-users。

用 Instagram Reels API 做竞品监控

定时拉某竞品的近期帖子和 Reels，比较不同时间点的互动变化。输入：一个用户名。输出：带计数的帖子/Reels 时间序列。端点：instagram/v3/user-posts 和 instagram/v3/user-reels。

用 Instagram hashtag API 做活动研究

拉某活动或主题标签下的近期帖子，判断热度并找出高互动账号。输入：一个话题（不带 #）。输出：分页的话题帖子列表。端点：instagram/v3/hashtag-posts（用 max_id 翻页）。

一个小工作流：取某账号的粉丝

支持分页的列表端点都用同一套约定：第一次请求不传 max_id，之后每次把上一页返回的游标带上，接着往下翻。下面就是”先查账号、再一页页拉粉丝”的写法：

import os
import requests

BASE = "https://api.sandbase.ai/v1/api"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",  # key 不要写死在代码里
    "Content-Type": "application/json",
}

def call(endpoint, **params):
    resp = requests.post(f"{BASE}/{endpoint}", headers=HEADERS, json=params)
    resp.raise_for_status()
    body = resp.json()
    if body.get("status") != "completed":            # 读 outputs 前先判断 status
        err = body.get("error", {})
        raise RuntimeError(f"{endpoint} {body.get('status')}: {err.get('message', '无输出')}")
    return body["outputs"][0]["data"]

def all_followers(username, pages=3):
    collected, cursor = [], None
    for _ in range(pages):
        params = {"username": username, "count": 100}
        if cursor:
            params["max_id"] = cursor
        data = call("instagram/v3/user-followers", **params)
        collected.extend(data.get("users", []))
        cursor = data.get("next_max_id")   # 分页游标在 data 里
        if not cursor:
            break  # 没有更多分页
    return collected

followers = all_followers("nasa", pages=2)
print(f"共收集 {len(followers)} 个粉丝")

游标在响应的 data.next_max_id 里，下一页请求把它当作 max_id 传进去，取不到就说明翻到底了。count 每页 1–100 条（默认 12）。有一点是我看了真实响应才发现的：资料字段藏在好几层里面，游标也在 data 里而不是最外层——所以我会先拉一条真实 payload 把路径对准，再动手写解析，而不是照着想当然写。

SandBase Instagram Endpoints 列表，显示 user-posts、location-info、user-info-by-username、user-followers 等端点及其路径 Instagram 端点列表的一部分——user-followers、user-posts、user-about 等，每个都带说明和路径。

边界与限制

只读公开数据。 这些端点只读公开资料和内容，不能发帖、点赞、关注或私信，私密账号也拿不到。
注意速率和量级。 数据能不能拿到、拿多全，都按尽力而为对待：空结果和 HTTP 429 要做好退避重试；控制并发与节奏，接入更高量级的任务前先按线上 catalog 确认可用端点。
字段结构会随来源变。 响应字段跟着上游走，不同端点、不同版本都可能不一样。别照着文档想当然，先拉一条真实响应，按实际结构来写。
这不是和 Instagram 的官方合作。 SandBase 只是把公开数据的接入方式统一了，并不会给你超出源数据本身的权限。具体怎么用，请自行遵守 Instagram 的条款和相关隐私规定。

常见问题

需要 Instagram token 或应用审核吗？ 不需要。你用 SANDBASE_API_KEY 向 SandBase 鉴权，不必注册 Instagram 应用，也不用为这些读取接口管理 OAuth。

v1、v2、v3 有什么区别？ 是同一个平台的三代 schema。v3 覆盖最全、也最新，大多数列表端点都支持分页；v1/v2 继续保留，方便那些已经在用它们的项目不用改。

怎么把帖子 URL 转成 media ID？ 先从 URL 里取出 shortcode（即 instagram.com/p/<shortcode>/ 中的那段），调用 instagram/v1/shortcode-to-media-id；如果你只有原始 URL，可先用 instagram/v3/extract-shortcode 提取。

调用是同步的吗？ 是。Instagram 数据端点是 sync 模式——JSON 响应就是结果，没有轮询步骤。

分页怎么用？ 支持分页的列表端点用 max_id 游标：首次请求省略它，之后传上一次响应返回的值取下一页。count 控制每页大小（user-followers 最多 100，默认 12）。

能读私密账号或需要登录才能看的数据吗？ 不能。API 只返回公开数据。私密账号、私信，以及任何得登录成某个用户才能做的操作，都不在范围内。

某个任务该调哪个端点？ 先按上面的能力速查表把任务对到能力簇，有 v3 版本时优先用。例如取信息流用 instagram/v3/user-posts，取话题用 instagram/v3/hashtag-posts，找账号用 instagram/v3/search-users。

能拿 Reels、快拍和精选吗？ 可以。Reels 用 instagram/v3/user-reels，当前快拍用 instagram/v3/user-stories，保存的精选用 instagram/v3/user-highlights（配合 highlight-stories）。

触发限流会怎样？ 高负载下可能返回 HTTP 429。用有上限的指数退避重试；控制并发与节奏，而不是全速循环打单条调用。

从一次资料请求开始

先创建一把 SandBase API Key，拿一个公开用户名跑 user-info-by-username，把返回的结构看清楚，再扩展到粉丝、帖子或 Reels。准备好了就：