Instagram Highlight Items API

Instagram Highlight Items

主要特性

• 多个精选动态输入一次提交一个或多个数字 highlight ID，采集器会分别查询每个所提交的标识。
• 标准化 Story 内容记录以统一结构返回内容 ID、公开 URL、标题或说明文字、作者身份、可见指标、媒体元数据和时间。
• 来源 Highlight 归属每条结果在 extra.highlight_id 中保留所提交的 highlight ID，便于区分来自不同精选动态的内容。

参数

如何使用

把已知 highlight ID 作为异步任务提交，轮询 task ID，完成后再用结果 cursor 读取保存的标准化记录。

1. 准备一个或多个当前有效的数字 highlight ID；如果不知道 ID，先按 username 采集 Story Highlights，并从返回的容器记录读取 extra.highlight_id。
2. 向 /v1/instagram/highlight-items POST highlight_ids。
3. 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
4. 通过 /v1/tasks/{task_id}?limit=50 读取 results.items，在 results.has_more 为 true 时继续传 results.next_cursor。

# 运行前请把文档示例替换为当前有效的 highlight ID。
curl -X POST "https://api.socq.ai/v1/instagram/highlight-items" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"highlight_ids":["18067016518767507"]}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续传 next_cursor

最佳使用场景

• 精选动态内容清单： 把返回的内容 ID、文本、公开 URL、媒体引用和时间整理成已知精选动态的可审核清单。
• 精选动态媒体审核： 检查当前公开 Story 内容的图片或视频 URL、缩略图、尺寸、时长、说明文字和作者上下文。
• 跨精选动态对比： 按 extra.highlight_id 对记录分组，对比所选精选动态的内容类型、发布时间、作者和可见指标。

使用建议

• 不知道 highlight ID 时，先按 username 调用 instagram/story-highlights，并从成功结果读取 extra.highlight_id；本接口不能通过 username 发现 ID。
• 提交前去除重复 ID，因为采集器会分别查询每个所提交的值。
• 不要添加 results_limit；每个 highlight ID 会返回其单次上游响应中当前可用的内容。
• 由于两类标准化记录都使用 type story，请用 resource 区分 highlight-items 和 story-highlights。
• 将文本、作者字段、指标、媒体、URL 和时间按可选值处理，已不可用或被移除的 Story 内容可能不产生记录。
• results.next_cursor 只用于继续读取任务已保存的记录，不会向 Instagram 发起下一页采集。

相关 API