手动查看一条 Instagram Reel 很简单，但要持续监控数百个公开创作者就困难得多：Reels 会下线，指标会变化，媒体 URL 可能失效，不同内容可见字段也不完全一致。
本文介绍如何使用 SocQ Instagram Reels API 按用户名采集公开 Reels，轮询异步任务，将稳定实体字段与指标快照分开存储，并把结果用于监控和分析。
**快速结论：**向
POST /v1/instagram/reels提交公开用户名和每个用户名的results_limit，保存task_id，轮询任务接口，再从data.results.items读取标准化记录。当前接口接受用户名，不接受单条 Reel URL。
官方 Instagram API 还是公开 Reels API？
当用户授权受支持的专业账号，且应用需要发布、洞察、评论管理或其他权限操作时，Meta 官方 Instagram API 是正确选择。
官方接口不是任意公开消费者资料的通用采集端点。访问取决于账号类型、权限、token、App Review 和具体产品。设计授权流程前，应查看 Instagram Platform 文档。
SocQ 适用于受支持的公开读取；Meta 官方 API 适用于账号操作和授权洞察。使用第三方接口不会免除 Instagram 条款、隐私和知识产权责任。
提交 Instagram Reels 任务
curl -X POST "https://api.socq.ai/v1/instagram/reels" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["natgeo", "instagram"],
"results_limit": 100
}'
提交前应：
- 去掉用户名开头的
@。 - 清理首尾空格。
- 在输入层把资料 URL 转成用户名。
- 不区分大小写去重。
- 拒绝空值。
results_limit 是每个用户名的请求上限，不保证每个创作者都有这么多公开 Reels。
轮询异步任务
保存返回的 task_id：
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued 和 running 是正常状态。使用指数退避，不要高频死循环轮询。成功后读取 data.results.items，并在 has_more 为真时使用 next_cursor。
建议持久化批次 ID、SocQ 任务 ID、提交用户名、提交/完成时间、终态、错误分类和最后处理的游标，这样进程重启后无需重复提交。
理解 Reel 响应
{
"id": "3138424916027781494",
"platform": "instagram",
"resource": "reels",
"type": "reel",
"shortcode": "CtjoC2BNsB2",
"url": "https://www.instagram.com/reel/CtjoC2BNsB2/",
"caption": "一条公开 Instagram Reel。",
"author": {
"id": "123",
"username": "natgeo",
"name": "National Geographic"
},
"metrics": {
"likes_count": 21904,
"comments_count": 502,
"views_count": 284110,
"plays_count": 284110
},
"duration_seconds": 42,
"audio": {
"title": "Original audio",
"artist": "natgeo"
},
"created_at": "2026-07-08T16:05:00",
"collected_at": "2026-07-19T10:00:00"
}
优先用 id 作为实体键，缺失时用 shortcode。保留 url 以便溯源。指标、媒体、音频和部分资料字段可能不可用，应保存为 null，不要强行转换为零或空字符串。
分离实体和指标快照
Reel 身份字段和互动指标变化速度不同。
实体表保存：
reel_id、shortcode、canonical_url、author_id
caption、created_at、duration_seconds、audio
first_seen_at、last_seen_at
快照表保存：
reel_id、collected_at
likes_count、comments_count
views_count、plays_count
这样每日监控不会制造重复 Reel，同时能保留增长轨迹。任一快照缺少指标时不要计算增长；隐藏计数不是零。
构建增量 Reels 监控
创作者注册表
↓
小时或每日计划
↓
异步任务轮询
↓
Schema 校验
↓
按 ID 更新 Reel 实体
↓
追加指标快照
↓
预警与报表
每个创作者应获取合理的近期窗口，按 created_at 排序，按 Reel ID 幂等更新，成功采集后才追加快照。Instagram 信息流受排序影响，接口不能当作完整历史档案。
Python 分页示例
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
created = requests.post(
f"{BASE}/instagram/reels",
headers=HEADERS,
json={"usernames": ["natgeo"], "results_limit": 200},
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
break
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
生产环境还需要处理游标分页、429、5xx、网络超时和有限重试。
入库前校验
platform必须为instagram。resource必须为reels。id、shortcode或url至少存在一个。- 可用时作者用户名应与输入匹配。
- 计数只能是非负数字或 null。
- 时间字段必须能正确解析。
- 媒体 URL 只能视为来源引用。
无效记录应进入隔离表并保留原任务与校验错误，不要静默修正字段类型。
媒体 URL 不是永久存储
视频、封面和头像 URL 可能带签名、限流或变化。如果产品需要长期保存媒体：
- 先确认存储权限。
- 只下载业务必要资产。
- 记录原 URL 和采集时间。
- 应用保留和删除策略。
- 安全地提供存储文件。
如果分析只需要文案和指标，保存大量视频可能只会增加成本和风险。
谨慎衡量 Reel 表现
每次播放互动率 =
(点赞 + 评论) / 播放量
每日播放增长 =
(当前播放 - 上次播放) / 间隔天数
只有输入指标完整时才计算。比较创作者时使用相同观察窗口和采集频率。公开视频计数是快照，不是经审计的后台洞察；对于自有专业账号，应优先使用官方 Instagram Insights。
常见失败处理
| 情况 | 处理 |
|---|---|
| 用户名无效 | 提交前拒绝 |
| 私密账号 | 标记不可用，不绕过 |
| 账号改名 | 人工解析或更新注册表 |
| 没有公开 Reels | 保存成功的空观察 |
| 任务超时 | 先继续轮询，再考虑重提 |
| 指标缺失 | 保留 null |
| Reel 重复 | 按 ID 或 shortcode 更新 |
| 媒体 URL 失效 | 仅在允许的场景刷新 |
成功空结果和失败任务是不同运营状态。
负责任使用
- 只采集合法目的需要的公开数据。
- 不访问私密资料或绕过控制。
- 避免敏感个人画像。
- 处理删除、隐私和版权请求。
- 保护 API Key、导出和媒体。
- 遵守 Instagram 与供应商条款。
- 账号操作使用 Meta 官方授权。
SocQ 提供技术采集流程，不授予内容的额外权利。
Instagram Reels API 常见问题（FAQ）
SocQ 可以直接抓取单条 Reel URL 吗？
当前 Reels 接口接受公开用户名，不接受单条 Reel URL。
接口会返回视频文件吗？
可用时返回标准化公开媒体引用。媒体 URL 可能临时失效，不应视为永久下载地址。
浏览量和播放量总会返回吗？
不会。Instagram 可能隐藏或省略指标，应保留 null。
可以采集私密账号 Reels 吗？
不可以。公开数据流程不应绕过私密账号控制。
如何避免重复？
优先使用 Reel ID，缺失时使用 shortcode；指标单独存入快照表。
什么时候应该使用 Meta 官方 API？
需要授权专业账号、发布、洞察或账号操作时使用官方 API。