视频详情
读取已存储的单个视频快照；不会触发 YouTube 实时抓取。
GET
https://api.shortsmonkey.com/v1/videos/abc123找到视频时扣 1 Credit
视频详情#
读取已存储的单个视频快照；不会触发 YouTube 实时抓取。
鉴权#
发送 Authorization: Bearer sm_live_...。完整 Key 不能放在 URL、Cookie、请求体、日志或 Analytics 中。
数据新鲜度#
榜单只读取 Worker 发布的稳定 Snapshot。公开读取绝不会触发 YouTube 刷新。
接口请求#
| 项目 | 值 | 说明 |
|---|---|---|
| 请求方法 | GET | HTTP 请求方法 |
| 完整 URL | https://api.shortsmonkey.com/v1/videos/abc123 | 生产环境 API 地址 |
| 鉴权 | Authorization: Bearer sm_live_... | 完整 Key 仅放在 Header 中 |
| 内容类型 | 无请求体 | GET 请求没有请求体 |
| 计费 | 找到视频时扣 1 Credit | 错误响应消耗 0 Credits |
请求参数#
| 参数名 | 位置 | 类型 | 必填 | 默认值 | 取值或限制 | 说明 |
|---|---|---|---|---|---|---|
video_id | Path | string | 是 | — | 6–32 个 URL-safe 字符 | 已存储的 YouTube 视频 ID；不存在时返回 404 且不扣费 |
成功返回字段#
all_data 是稳定 Snapshot 中未应用请求筛选的全部数据页；filter_data 是同一 Snapshot 应用本接口默认条件及用户参数后的数据页。两组数据各自分页。
字段路径使用点号表示嵌套对象，[] 表示数组元素。订阅者数未知时返回 null，并设置 subscriber_count_hidden: true。单次请求按两组实际返回条数中的较大值结算一次，不相加重复计费。
| 字段路径 | 类型 | 可为空 | 说明 |
|---|---|---|---|
data.all_data.items | array<object> | 否 | 未应用请求筛选的当前页视频列表 |
data.all_data.items[].video_id | string | 否 | YouTube 视频 ID |
data.all_data.items[].title | string | 否 | 视频标题 |
data.all_data.items[].video_url | string | 否 | YouTube 视频地址 |
data.all_data.items[].channel.id | string | 是 | 频道 ID |
data.all_data.items[].channel.title | string | 否 | 频道名称 |
data.all_data.items[].channel.subscribers | integer | 是 | 频道订阅数；隐藏时为 null |
data.all_data.items[].channel.subscriber_count_hidden | boolean | 否 | 订阅数是否隐藏 |
data.all_data.items[].views | integer | 否 | 播放量快照 |
data.all_data.items[].views_to_subscribers_ratio | number | 是 | 播放订阅比 |
data.all_data.items[].opportunity_score | number | 是 | 机会分数 |
data.all_data.items[].duration_seconds | integer | 否 | 视频时长，单位为秒 |
data.all_data.items[].published_at | string(date-time) | 是 | 视频发布时间，UTC ISO 8601 |
data.all_data.items[].snapshot_at | string(date-time) | 是 | 数据采集时间 |
data.all_data.items[].niche | string | 是 | 赛道或分类 |
data.all_data.items[].track | string | 是 | 数据赛道标识 |
data.all_data.items[].region | string | 是 | 地区代码 |
data.all_data.items[].reasons | array<string> | 否 | 入榜原因 |
data.all_data.items[].video_type | string | 否 | shorts 或 long |
data.all_data.next_cursor | string | 是 | 本结果集的下一页 Cursor；无下一页时为 null |
data.filter_data.items | array<object> | 否 | 应用默认条件与请求筛选后的当前页视频列表 |
data.filter_data.items[].video_id | string | 否 | YouTube 视频 ID |
data.filter_data.items[].title | string | 否 | 视频标题 |
data.filter_data.items[].video_url | string | 否 | YouTube 视频地址 |
data.filter_data.items[].channel.id | string | 是 | 频道 ID |
data.filter_data.items[].channel.title | string | 否 | 频道名称 |
data.filter_data.items[].channel.subscribers | integer | 是 | 频道订阅数；隐藏时为 null |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | 否 | 订阅数是否隐藏 |
data.filter_data.items[].views | integer | 否 | 播放量快照 |
data.filter_data.items[].views_to_subscribers_ratio | number | 是 | 播放订阅比 |
data.filter_data.items[].opportunity_score | number | 是 | 机会分数 |
data.filter_data.items[].duration_seconds | integer | 否 | 视频时长，单位为秒 |
data.filter_data.items[].published_at | string(date-time) | 是 | 视频发布时间，UTC ISO 8601 |
data.filter_data.items[].snapshot_at | string(date-time) | 是 | 数据采集时间 |
data.filter_data.items[].niche | string | 是 | 赛道或分类 |
data.filter_data.items[].track | string | 是 | 数据赛道标识 |
data.filter_data.items[].region | string | 是 | 地区代码 |
data.filter_data.items[].reasons | array<string> | 否 | 入榜原因 |
data.filter_data.items[].video_type | string | 否 | shorts 或 long |
data.filter_data.next_cursor | string | 是 | 本结果集的下一页 Cursor；无下一页时为 null |
meta.request_id | string | 否 | 请求追踪 ID |
credits.cost | integer | 否 | 找到视频时为 1 |
credits.remaining | integer | 否 | 账户剩余 Credits |
credits.period_ends_at | string(date-time) | 否 | 当前额度周期结束时间 |
分页与 Cursor#
limit 默认为 20，最大 50。all_data.next_cursor 传给 all_cursor，filter_data.next_cursor 传给 filter_cursor；两个 Cursor 独立、不透明、带签名并在 24 小时后过期，且始终读取同一 Snapshot。旧 cursor 仅作为 filter_cursor 的兼容别名。
ETag#
排行榜支持 If-None-Match。命中返回 304、X-Credits-Cost: 0，且不会重复执行。
错误与限流#
错误 Envelope 始终包含 code、固定英文 message、request_id 和 details。429 与所有 4xx/5xx 都不扣 Credits。
| HTTP 状态 | 错误码 | 原因 | 处理建议 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 参数格式、组合或范围错误 | 根据 details.issues 修正参数 |
| 401 | INVALID_API_KEY | Key 无效或已失效 | 检查 Bearer Header 和 Key 状态 |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | 订阅或 Credits 不可用 | 检查套餐、余额和 Key 安全预算 |
| 429 | RATE_LIMITED | 速率或并发超限 | 按 Retry-After 退避重试 |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | 数据或服务暂不可用 | 稍后重试并保留 request_id |
curl -X GET "https://api.shortsmonkey.com/v1/videos/abc123" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"