中國訂閱人數較少的長視頻
預設會傳回嚴格項目的專用機會排名。
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=200 Credits
中國訂閱人數較少的長視頻#
預設會傳回嚴格項目的專用機會排名。
驗證#
發送 Authorization: Bearer sm_live_...。切勿將完整金鑰放入 URL、cookie、內文、日誌或分析中。
數據新鮮度#
排名讀取工作人員發布的穩定快照。公共讀取永遠不會觸發 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 URL |
| 驗證 | Authorization: Bearer sm_live_... | 僅在標頭中發送完整密鑰 |
| 內容類型 | 無請求內文 | GET 請求沒有請求正文 |
| 製作人員 | 0 Credits | 所有操作均消耗 0 Credits，不再按月發放或扣減商業積分。 |
請求參數#
| 姓名 | 地點 | 類型 | 必需的 | 預設 | 值或限制 | 描述 |
|---|---|---|---|---|---|---|
period | 詢問 | string | 不 | today | today / 7d / all_time | 預設發布視窗；使用自訂日期時省略 |
start_date | 詢問 | string(date) | 有條件的 | — | YYYY-MM-DD | 包括 UTC 開始日期；必須與 end_date 配對 |
end_date | 詢問 | string(date) | 有條件的 | — | YYYY-MM-DD | 包括 UTC 結束日期；不能早於開始日期 |
track | 詢問 | string | 不 | all | 1–80 個字符 | 按曲目標識符過濾； all 包括每首曲目 |
quality | 詢問 | string | 不 | strict | strict / all | 僅返回嚴格數據或包含擴展候選數據 |
limit | 詢問 | integer | 不 | 20 | 1–50 | 此頁面上的最大項目數 |
all_cursor | 詢問 | string | 不 | — | all_data.next_cursor，24小時內有效 | 取得下一個未過濾的頁面 |
filter_cursor | 詢問 | string | 不 | — | filter_data.next_cursor，24小時內有效 | 取得下一個過濾頁面而不更改過濾器 |
cursor | 詢問 | string | 不 | — | 已棄用的兼容性參數 | filter_cursor 的別名；請勿同時傳送 |
成功響應字段#
all_data 是穩定快照中未經過濾的頁面； filter_data 是來自端點預設值和請求過濾器之後的相同快照的頁面。每個結果獨立分頁。
所有操作均消耗 0 Credits，不再按月發放或扣減商業積分。
| 田野路徑 | 類型 | 可空 | 描述 |
|---|---|---|---|
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 視訊 URL |
data.all_data.items[].channel.id | string | 是的 | 頻道號碼 |
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 視訊 URL |
data.filter_data.items[].channel.id | string | 是的 | 頻道號碼 |
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 | 不 | 穩定的快照ID |
meta.snapshot_at | string(date-time) | 不 | 快照時間戳 |
meta.data_status | string | 不 | 資料集狀態 |
credits.cost | integer | 不 | 所有操作均消耗 0 Credits，不再按月發放或扣減商業積分。 |
credits.remaining | integer | null | 是 | null |
credits.period_ends_at | string(date-time) | null | 是 | null |
credits.unlimited | boolean | 不 | true |
分頁和 cursor#
將 all_data.next_cursor 傳送為 all_cursor，將 filter_data.next_cursor 傳送為 filter_cursor。 cursor是獨立的、不透明的、經過簽名的、24小時內有效；舊版 cursor 只是 filter_cursor 的別名。
電子標籤#
排名支援If-None-Match。命中返回 HTTP 304 和 X-Credits-Cost: 0。
錯誤和速率限制#
每個錯誤都包含 code、穩定英文 message、request_id 和 details。所有 4xx/5xx 回應的成本為零。
| HTTP 狀態 | 程式碼 | 原因 | 建議採取的行動 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 參數格式、組合或範圍無效 | 使用 details.issues 修正參數 |
| 401 | INVALID_API_KEY | 密鑰無效或無效 | 檢查承載頭和金鑰狀態 |
| 429 | API_DAILY_LIMIT_REACHED | 同一帳戶的所有 API Key 共用每天 10 次 REST 資料呼叫額度，依 Asia/Shanghai 時區每天 00:00 重設。網站每天另有獨立的 10 次搜尋額度，MCP 不占用這兩項額度。 | 達到 10 次 REST 資料呼叫後回傳 HTTP 429 和 API_DAILY_LIMIT_REACHED。請等到 Asia/Shanghai 時區次日 00:00；建立或輪換 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"