Instagram Story Highlights
Instagram 快拍精选是公开主页上长期保留的快拍集合，按标题组织，并带有所属账号、封面媒体和项目数量。这些容器记录可用于整理主页内容分类、比较不同账号的精选结构，以及筛选需要逐项查看的快拍集合。
主要特性
- 多个主页的精选清单一次提交一个或多个 Instagram username，列出每个账号公开展示的快拍精选容器，并保留所属账号信息。
- 容器身份与上下文以统一结构返回 Highlight ID、标题、URL、所属账号、直接提供的媒体、时间、公开计数和所报告的项目总数。
- 衔接逐项获取通过 extra.highlight_id 保留容器关系，并把数字 Highlight ID 传入逐项获取流程。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
usernames | 必填 | 一个或多个公开 Instagram username，每项均为非空账号名；允许带开头的 @，采集前会将其移除。 |
如何使用
把公开账号 username 作为异步任务提交，轮询 task ID，完成后再用结果 cursor 读取标准化的快拍精选容器。
- 准备一个或多个公开 Instagram username，使用账号名而不是主页 URL。
- 向 /v1/instagram/story-highlights POST usernames。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 读取 data.results.items，并在 results.has_more 为 true 时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/instagram/story-highlights" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["instagram"]}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续传 next_cursor最佳使用场景
- 整理公开主页内容分类： 利用精选标题、所属账号、URL 和媒体数量，整理主页上公开可见的长期快拍分类。
- 比较不同账号的精选结构： 结合所提交公开账号的容器标题、项目总数、媒体引用和可用时间，比较其精选内容结构。
- 筛选快拍集合： 结合 extra.highlight_id、标题和 media_count，选择需要随后逐项获取的数字 Highlight 容器。
使用建议
- 提交前移除开头的 @，再对处理后的 username 去重；主页 URL 不会自动转换为账号名。
- 每个 username 只发起一次精选列表请求，且没有 results_limit 或来源续页，因此每个账号实际公开的容器列表决定采集记录数。
- 仅使用任务结果的 next_cursor 翻阅已经保存的标准化记录；它不会向 Instagram 请求下一页快拍精选。
- 需要获取容器内的单条快拍时，只把存在且为数字的 extra.highlight_id 传给 instagram/highlight-items。
- 把空结果理解为可能没有公开精选或主页不可用，并对可选媒体、指标、URL 和时间做好缺失处理。
相关 API
需要其他类型的 Instagram 公开数据时，可以使用以下 API。
- Instagram Followers Count API — 获取公开账号身份以及可见粉丝数、关注数和帖子数。
- Instagram Posts API — 按 username 采集公开帖子、媒体、标签、提及、时间和互动指标。
- Instagram Reels API — 按 username 采集公开 Reels、媒体、音频、标签、提及和互动指标。
- Instagram Search API — 按关键词或账号名称搜索公开主页及可见账号信息。
- Instagram Comments API — 从帖子 URL 采集公开评论、作者、时间、点赞数和回复数。
- Instagram Profiles API — 按 username 获取公开主页身份、简介、链接、账号标记、分类和可见计数。
- Instagram Followers List API — 采集公开粉丝资料记录，并保留来源账号和关注关系上下文。
- Instagram Following List API — 采集 Instagram 账号公开可见的关注主页，返回身份、关注关系上下文和可见账号计数。
- Instagram Hashtag Posts API — 按 hashtag 发现公开帖子，返回来源标签、媒体、创作者、时间和可见互动指标。
- Instagram Tagged Posts API — 按 username 采集标记指定主页的公开帖子，返回作者、媒体、提及、被标记用户上下文和互动指标。
- Instagram Transcript API — 从公开 Post 或 Reel URL 提取字幕文本、语言、格式、来源 URL 和 shortcode。
- Instagram Audio Reels API — 按已知数字 audio ID 采集公开 Reels，返回说明文字、创作者、媒体、时间、可见互动和来源音频上下文。
- Instagram Highlight Items API — 通过已知 highlight ID 获取保存的公开 Story 内容，返回文本、作者身份、媒体、时间、可见指标和来源上下文。
- Instagram Post Info API — 通过已知公开帖子、Reel 或旧版 IGTV URL 查询说明文字、作者身份、媒体、时间、可见互动和输入上下文。
- Instagram Reels Search API — 按文本 query 搜索公开 Reels，返回说明文字、创作者、媒体、时间、可见互动指标和查询上下文。
- Instagram Trending Reels API — 采集趋势信息流当前展示的公开 Reel，返回说明文字、创作者、媒体、时间和可见互动指标。