Instagram 主页研究 API 教程 | SandBase

如果你在 Instagram 上研究创作者或品牌,你想要一个可复用的循环:读一个公开主页拿关键信号、拉近期帖子、翻页 feed 看互动怎么走。这篇 Instagram 主页研究 API 教程用两个 SandBase 端点把这个循环串起来,让 Agent 能端到端跑完。它建立在 Instagram 公开数据 API 汇总页之上;建议先读那篇了解全局。

这里的一切都是公开、只读数据。不需要登录 Instagram、不需要 SDK——但仍需要一个 SandBase API 密钥来鉴权。端点 API 参考是参数和响应信封的权威来源。参考只保证信封本身;下面的载荷字段名来自我实际跑的调用(测试于 2026-09-28,UTC),是示意性的、仅供观测——并非文档保证——请以真实响应为准核对。

先说结论

• 两个端点构成循环:user-profile(关键信号)→ user-posts(近期 feed)。
• 每次调用都是 POST /v1/api/instagram/v3/<path>,带一个 username,一个 SANDBASE_API_KEY。
• 用返回的 next_max_id 翻 feed。仅公开、只读数据。
• 防御式读字段——信封有保证,业务字段仅供观测。

SandBase vs. 官方 Instagram API

你的需求	用
公开、只读的资料和帖子	SandBase Instagram 公开数据 API
发帖、以账号身份操作,或用 Graph API	Instagram 官方平台
私有或仅账号可见的数据	两种公开方案都不适用

工作流一览

1. 用 instagram/v3/user-profile 以一个 username 读主页。
2. 用同一个 username 调用 instagram/v3/user-posts 拉近期帖子,用 next_max_id 翻页。

每个端点返回共享信封——一个 id、一个 status、model,以及在 completed 运行上 outputs[0].data 下的负载。

SandBase 上的 Instagram 端点——user-profile 和 user-posts 驱动这个循环。

第 0 步:一个辅助函数管所有调用

import os
import requests

API = "https://api.sandbase.ai/v1/api"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
    "Content-Type": "application/json",
}

def call(path: str, payload: dict) -> dict:
    resp = requests.post(f"{API}/{path}", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    if body.get("status") != "completed":
        raise RuntimeError(body.get("error", {}).get("message", f"{path} 未完成"))
    # 信封可能不同:优先读顶层 output,否则 outputs[0].data。
    output = body.get("output")
    if output is None and body.get("outputs"):
        output = body["outputs"][0].get("data", {})
    return output or {}

第 1 步:读主页

profile = call("instagram/v3/user-profile", {"username": "nasa"})
print(profile.get("full_name"), "|", profile.get("follower_count"), "粉丝")
print("简介:", profile.get("biography"))

在我抓到的响应里(user-profile run id c52039c0-5a64-4b87-93c2-1b7a6995c23d,测试于 2026-09-28,UTC),负载带 full_name、biography、category、follower_count、following_count、media_count 和 is_verified——这些是示意性的、仅供观测的字段。用 .get() 读每个,并对照真实响应核对。

user-profile 参考——username 参数和响应路径的事实来源。

第 2 步:拉近期帖子

feed = call("instagram/v3/user-posts", {"username": "nasa"})
posts = feed.get("items", []) or feed.get("data", [])
next_max_id = feed.get("next_max_id")
for p in posts[:5]:
    print(p.get("like_count"), "赞,", p.get("comment_count"), "评论 -", p.get("shortcode"))

在我这次运行里(user-posts run id 4e058e6d-1e9e-4dd1-8f08-412258df9a7a),负载带 items(每条含 caption_text、like_count、comment_count、view_count、is_video、shortcode、taken_at)、一个 count 和一个用于翻页的 next_max_id。翻页时,用返回的 next_max_id 重发 user-posts——确切参数名对照参考核对。

user-posts 参考——传一个 username;用返回的 next_max_id 翻页。

串起来

def research(username: str):
    profile = call("instagram/v3/user-profile", {"username": username})
    feed = call("instagram/v3/user-posts", {"username": username})
    posts = feed.get("items", []) or feed.get("data", [])
    engagement = [
        {"shortcode": p.get("shortcode"), "likes": p.get("like_count"), "comments": p.get("comment_count")}
        for p in posts if isinstance(p, dict)
    ]
    return {
        "followers": profile.get("follower_count"),
        "media_count": profile.get("media_count"),
        "recent": engagement,
    }

因为两个端点共享同一个信封和同一个 username,循环保持扁平:call(...) 里一次 status 检查、profile 和 posts 用一套 .get() 模式。

常见用例

创作者甄别

读一个创作者的主页拿粉丝数和类目,再拉近期帖子,用真实互动(赞和评论)而非光看粉丝数来衡量。输入:一个 username。输出:主页信号加一份近期帖子互动样本。端点:user-profile、user-posts。

竞品内容追踪

按计划轮询一个竞品的 user-posts,按 shortcode 做 diff 以捕捉新帖并追踪它们随时间的互动。输入:一个 username。输出:连续的帖子页。端点:user-posts。

受众与垂类研究

对比若干主页的 category、follower_count 和发帖节奏,画出谁在领跑一个垂类。输入:一组 username。输出:可比的主页信号。端点:user-profile。

互动率估算

把两个端点组合起来近似一个互动率:拉近期帖子,对它们的 like_count 和 comment_count 取平均,再除以主页的 follower_count。这给出一个跨创作者可比、光看粉丝数会掩盖的粗略信号——一个高互动的小号可能跑赢一个大号。防御式读每个字段,并把结果当作估算,因为观测字段和帖子样本会变。输入:一个 username。输出:一个互动率估算。端点:user-profile、user-posts。

实操要点

• 信封可能不同。 参考记录的是 outputs[0].data;两种结构都读(优先 output,回退 outputs[0].data)。
• 用 next_max_id 翻页。 在还有更多帖子时用返回值重发 user-posts。
• 业务字段仅供观测。 把 follower_count、like_count、caption_text 之类当作观测到的、以真实响应核对。
• 仅公开、只读数据。 不发帖、不涉及私有/仅账号可见数据。用 SandBase API 密钥鉴权。
• 做个好客户端。 遇到 HTTP 429 等瞬时错误按退避重试;翻页而不是猛打。

常见问题

我需要 Instagram/Facebook 开发者应用或登录吗? 不需要。你用自己的 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你这边有 Instagram 账号或 OAuth。

什么标识一个主页? 一个 username。user-profile 和 user-posts 都接同一个 username。

怎么翻更多帖子? user-posts 负载带一个 next_max_id;用它重发 user-posts。确切参数对照参考核对。

我能读私密账号吗? 不能。这套 API 只返回公开数据。私有和账号授权内容不在范围内。

小结

两个端点、一个信封、一个 username——这就是整个主页研究循环。完整端点目录见 Instagram 公开数据 API 汇总页。准备好后:

• 获取 SandBase API 密钥
• 浏览 Instagram 端点
• 打开 user-profile API 参考