核心用法
maxhub-instagram 是一款专注Instagram数据采集的专业级工具，通过MaxHub API提供87个端点的全维度数据查询能力，覆盖V1/V2/V3三大版本接口。核心功能模块包括：
- 帖子域（34端点）：支持shortcode/media_id/URL三种入口查询帖子详情，涵盖Carousel、视频、Reels、Stories、Highlights、点赞、标记用户及音乐元数据
- 用户域（24端点）：多版本用户资料、Posts/Reels/Tagged内容、Followers/Following列表、About信息、曾用名及相似用户推荐
- 搜索域（23端点）：用户搜索、综合搜索、Hashtag、Location、坐标搜索、Explore探索页，支持游标翻页与排序
- 评论域（6端点）：一级评论+二级回复完整链路，V3版本需特别注意
media_id接力机制
使用流程遵循"意图匹配→加载reference→构建最小调用计划→执行并验证"四步法，强制依赖endpoints_whitelist.yaml白名单进行Pre-call自检，杜绝路径或参数臆造。
显著优点
- 数据覆盖极全：87端点覆盖Instagram公域数据的绝大多数场景，从单帖详情到粉丝结构分析均可支持
- 多版本灵活选型：V1/V2/V3三版本并行，V3字段最丰富（含Carousel/oEmbed），V2综合搜索与Stories稳定，V1兼容历史脚本
- 防臆造安全设计：四层防护机制（白名单→强标记→禁止规则→错误反馈），配合404/400时的A/B自检清单，大幅降低Agent误调用风险
- 链式调用图谱完善：字段流字典+Chain Recipes明确
user_id/media_id/shortcode/comment_id的传递路径，特别标注V3子评论需media_id而非code的关键陷阱 - 企业级错误处理：HTTP状态码权威定义+跨版本降级矩阵+业务code非零时不重试的策略，保障生产环境稳定性
- 零依赖轻量部署：仅需
curl和API Key，无第三方库依赖，OpenClaw配置即可运行
潜在缺点与局限性
- 只读限制明确：不支持发帖、点赞、关注等写入操作，纯数据采集工具，无法替代官方API的交互功能
- 第三方数据依赖：所有请求发送至
https://www.aconfig.cn，数据新鲜度与稳定性依赖MaxHub服务，非Instagram官方直连 - 版本参数不互通：V1/V2/V3的翻页参数（
max_id/pagination_token/after）与部分字段命名差异大，跨版本切换必须重新读取reference，增加心智负担 - V3评论调用复杂度：子评论回复需先通过
shortcode_to_media_id转换，链路比V2多一步，新手易踩坑 - 商业服务成本：需注册MaxHub控制台获取API Key，高频调用可能产生费用，文档未明确披露定价细节
适合人群
- 跨境DTC品牌投放经理：批量筛选网红KOL，量化粉丝量、互动率、Reels表现
- 海外品牌PR/公关团队：构建Hashtag+Location+评论的三维舆情监控网，快速响应负面事件
- 社媒数据分析师：批量采集竞品账号内容，建立素材库，支撑选题与广告Hook提炼
- 增长黑客/用户研究员：分析Followers/Following重合度，识别核心粉丝群体画像
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 数据隐私合规 | 采集用户公开数据仍需遵守GDPR/CCPA及平台ToS | 仅用于公开数据分析，不存储个人敏感信息 |
| API Key泄露 | `MAXHUB_API_KEY`为敏感凭证 | 使用独立测试账号，定期轮换，不暴露于日志 |
| 服务不可用 | MaxHub服务中断或限流 | 关注HTTP状态码，利用V1V2↔V3降级矩阵切换 |
| 数据时效性 | 非官方API可能存在延迟 | 关键业务场景需与官方数据交叉验证 |
| 误用导致封号 | 高频采集可能触发平台风控 | 控制请求频率，避免针对单一账号过度爬取 |