Outlier 视频搜索
按关键词、赛道、地区和爆款指数搜索已存储数据。
POST
https://api.shortsmonkey.com/v1/videos/outliers/search每实际返回 1–20 条扣 2 Credits
Outlier 视频搜索#
按关键词、赛道、地区和爆款指数搜索已存储数据。
鉴权#
发送 Authorization: Bearer sm_live_...。完整 Key 不能放在 URL、Cookie、请求体、日志或 Analytics 中。
数据新鲜度#
榜单只读取 Worker 发布的稳定 Snapshot。公开读取绝不会触发 YouTube 刷新。
接口请求#
| 项目 | 值 | 说明 |
|---|---|---|
| 请求方法 | POST | HTTP 请求方法 |
| 完整 URL | https://api.shortsmonkey.com/v1/videos/outliers/search | 生产环境 API 地址 |
| 鉴权 | Authorization: Bearer sm_live_... | 完整 Key 仅放在 Header 中 |
| 内容类型 | application/json | 请求体使用 JSON |
| 计费 | 每实际返回 1–20 条扣 2 Credits | 错误响应消耗 0 Credits |
请求参数#
| 参数名 | 位置 | 类型 | 必填 | 默认值 | 取值或限制 | 说明 |
|---|---|---|---|---|---|---|
keyword | JSON 请求体 | string | 否 | — | 1–120 个字符 | 匹配标题或赛道文本的关键词 |
niche | JSON 请求体 | string | 否 | — | 1–80 个字符 | 赛道或分类筛选 |
video_type | JSON 请求体 | string | 否 | all | shorts / long / all | 视频类型 |
region | JSON 请求体 | string | 否 | — | 2–16 个字符 | 地区代码 |
max_channel_subscribers | JSON 请求体 | integer | 否 | — | 0–10,000,000 | 频道订阅数上限 |
min_views | JSON 请求体 | integer | 否 | — | 0–1,000,000,000 | 最低播放量 |
min_vs_ratio | JSON 请求体 | number | 否 | 10 | 0–100,000 | 最低播放订阅比 |
time_window | JSON 请求体 | string | 否 | 7d | 24h / 3d / 7d / 30d | 视频发布时间窗口 |
limit | JSON 请求体 | integer | 否 | 20 | 1–50 | 本页最多返回的条数 |
all_cursor | JSON 请求体 | string | 否 | — | data.all_data.next_cursor | 获取未筛选数据的下一页 |
filter_cursor | JSON 请求体 | string | 否 | — | data.filter_data.next_cursor | 获取筛选后数据的下一页；筛选参数保持不变 |
cursor | JSON 请求体 | 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 |
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 POST "https://api.shortsmonkey.com/v1/videos/outliers/search" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"finance","video_type":"all","time_window":"7d","min_vs_ratio":10,"limit":20}'