Snapchat Spotlight
公开 Snapchat Spotlight 记录可以包含来源链接、说明文字、创作者身份、媒体引用、发布时间、时长、音频信息和可见互动数量。标准化结果会将这些可用字段与采集时间一并保留，便于进行指定视频审阅、内容目录补全和分时点比较。
主要特性
- 解析已知 Spotlight提交一个公开 snapchat.com URL，将对应详情响应整理为至多一条标准记录，不扩展为内容信息流。
- 创作者与视频上下文在固定结果结构中保留来源 URL，以及可用的说明文字、作者身份、媒体、时长、音频、标签、提及和发布时间。
- 可见互动快照返回可用的点赞、评论、分享、播放和观看数量，并配合 collected_at 保留实际观察时间。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
url | 必填 | 必填且非空的 http 或 https URL，host 必须为 snapchat.com 或其任意子域。runtime 不限制 pathname；建议使用 /@username/spotlight/{spotlight_id} 形式的公开 Spotlight 链接。 |
如何使用
提交一个公开 Snapchat Spotlight URL，跟踪异步任务，并读取其已存储的标准化结果。
- 复制 snapchat.com 或其子域上的一个公开 Snapchat Spotlight URL。
- 将链接作为 url 提交到 /v1/snapchat/spotlight，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或报告失败。
- 读取 data.results.items；如果存储结果响应的 has_more 为 true，则继续使用其 next_cursor。
curl -X POST "https://api.socq.ai/v1/snapchat/spotlight" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.snapchat.com/@queenhaley_13/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pnZnF0bG52AZslQsUdAZslQoRQAAAAAQ"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；next_cursor 只用于已存储结果分页最佳使用场景
- 审阅指定 Spotlight： 将一个已知公开链接转换为可追溯记录，保留来源、说明文字、作者、媒体、时间和可用互动字段。
- 补全内容目录： 为现有 URL 清单补充标准化视频身份、创作者信息、时长、音频、标签、提及和采集时间。
- 比较互动快照： 将可见计数与 collected_at 配对后比较多次观察，不把这些数值理解为实时或完整统计。
使用建议
- 只在 url 中提交一个链接；此 endpoint 不接受数组、results_limit、usernames 或 callback_url。
- 即使校验只检查 Snapchat host 而不强制 pathname，也应使用公开 Spotlight 链接；无关的 Snapchat 路径可能在 provider 处失败。
- 不要把任务结果中的 next_cursor 当作来源信息流分页，因为 provider 只执行一次详情查询并最多返回一条记录。
- 允许 ID、说明文字、作者字段、媒体、时间、音频和单项互动指标为空，避免公开响应缺少字段时中断处理。
- 将 collected_at 与互动数量一起保存，确保每项测量都对应明确的采集时间。
- 每个成功任务按固定 0.19 积分预留预算；费用不随返回字段或结果数量变化。
相关 API
需要其他类型的 Snapchat 公开数据时，可以使用以下 API。