中文低粉长视频榜
独立的中文长视频机会榜接口，默认仅返回 Strict 数据。
GET
https://api.shortsmonkey.com/v1/rankings/chinese-low-subscriber-long-videos?start_date=2026-07-01&end_date=2026-07-20&quality=strict&limit=20每实际返回 1–20 条扣 1 Credit
中文低粉长视频榜#
独立的中文长视频机会榜接口，默认仅返回 Strict 数据。
鉴权#
发送 Authorization: Bearer sm_live_...。完整 Key 不能放在 URL、Cookie、请求体、日志或 Analytics 中。
数据新鲜度#
榜单只读取 Worker 发布的稳定 Snapshot。公开读取绝不会触发 YouTube 刷新。
接口请求#
| 项目 | 值 | 说明 |
|---|---|---|
| 请求方法 | GET | HTTP 请求方法 |
| 完整 URL | https://api.shortsmonkey.com/v1/rankings/chinese-low-subscriber-long-videos?start_date=2026-07-01&end_date=2026-07-20&quality=strict&limit=20 | 生产环境 API 地址 |
| 鉴权 | Authorization: Bearer sm_live_... | 完整 Key 仅放在 Header 中 |
| 内容类型 | 无请求体 | GET 请求没有请求体 |
| 计费 | 每实际返回 1–20 条扣 1 Credit | 错误响应消耗 0 Credits |
请求参数#
| 参数名 | 位置 | 类型 | 必填 | 默认值 | 取值或限制 | 说明 |
|---|---|---|---|---|---|---|
period | Query | string | 否 | today | today / 7d / all_time | 预设发布日期范围；使用自定义日期时不要传 |
start_date | Query | string(date) | 条件必填 | — | YYYY-MM-DD | UTC 开始日期，包含当天；必须和 end_date 一起传 |
end_date | Query | string(date) | 条件必填 | — | YYYY-MM-DD | UTC 结束日期，包含当天；不得早于开始日期 |
track | Query | string | 否 | all | 1–80 个字符 | 按赛道标识筛选；all 表示全部 |
quality | Query | string | 否 | strict | strict / all | 仅返回严格数据，或包含扩展候选 |
limit | Query | integer | 否 | 20 | 1–50 | 本页最多返回的条数 |
all_cursor | Query | string | 否 | — | all_data.next_cursor，24 小时有效 | 获取未筛选数据的下一页 |
filter_cursor | Query | string | 否 | — | filter_data.next_cursor，24 小时有效 | 获取筛选后数据的下一页；筛选参数必须保持不变 |
cursor | Query | string | 否 | — | 旧版兼容参数 | 等同 filter_cursor；两者不能同时传 |
成功返回字段#
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 |
data.all_data.items[].quality_tier | string | 否 | strict 或 expanded |
data.filter_data.items[].quality_tier | string | 否 | strict 或 expanded |
data.all_data.items[].is_expanded_candidate | boolean | 否 | 是否为扩展候选 |
data.filter_data.items[].is_expanded_candidate | boolean | 否 | 是否为扩展候选 |
meta.methodology_version | string | 否 | 榜单方法版本 |
meta.request_id | string | 否 | 请求追踪 ID |
meta.snapshot_id | string | 否 | 稳定 Snapshot ID |
meta.snapshot_at | string(date-time) | 否 | Snapshot 时间 |
meta.data_status | string | 否 | 数据状态 |
credits.cost | integer | 否 | 本次实际消耗 |
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/rankings/chinese-low-subscriber-long-videos?start_date=2026-07-01&end_date=2026-07-20&quality=strict&limit=20" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"