快速开始

准备可登录的 ShortsMonkey 账户和可访问 HTTPS 的服务端终端。cURL 示例需要 cURL；JavaScript 示例需要支持 fetch 的 Node.js；Python 示例需要 requests。所有 Key 均为占位符，请使用自己账户的 Key。

登录后打开 API 控制台，在仅显示一次的弹窗中复制完整 Key。REST 请求需要 api:read；MCP 工具需要 mcp:read。两者都使用时选择两项权限，仅使用一种时按最小权限选择。

export SHORTSMONKEY_API_KEY="sm_live_..."

GET /v1/auth/verify、GET /v1/credits、GET /v1/credits/costs、健康检查和 Key 管理不占用每天 10 次数据调用额度。Key 仍保留身份认证和归属校验。

在终端执行 curl -i https://api.shortsmonkey.com/v1/auth/verify -H "Authorization: Bearer $SHORTSMONKEY_API_KEY"。此 REST 校验同样需要 api:read。应先得到 HTTP 200，再确认 data.authenticated 为 true、data.scopes 包含 api:read；只验证成功还不表示榜单一定有结果。

复制下方一种语言的示例即可，不必把三份都执行。请求读取已存储的中文长视频稳定快照，不触发 YouTube 实时采集。先检查 HTTP 状态；非 200 时读取 error.code，而不是把错误 JSON 当作榜单。

data.all_data.items 是当前页未应用请求筛选的视频，data.filter_data.items 是应用默认条件和请求筛选后的当前页视频。两组都可能为空，数量也可能不同；空数组不表示鉴权失败。比较 meta.snapshot_at 判断这份数据的时间，保存 meta.request_id 便于排错。

需要下一页时，将 all_data.next_cursor 传给 all_cursor，将 filter_data.next_cursor 传给 filter_cursor，保留原筛选参数。null 表示该组已结束，不要交换两个 Cursor。每次成功的新 REST 数据请求都占用每日次数；credits.unlimited 为 true 不代表数据请求不限量，可查看 daily_usage.remaining。

401 INVALID_API_KEY：检查完整 sm_live_ Key、Bearer 后的空格、环境变量是否已设置，以及 Key 是否过期、撤销或超过轮换宽限期。403 INSUFFICIENT_SCOPE：检查 api:read；403 ACCOUNT_DISABLED：检查账户状态并联系支持。不要通过循环重试修复身份或权限问题。

429 必须按 error.code 区分：API_DAILY_LIMIT_REACHED 等待 Asia/Shanghai 00:00；RATE_LIMITED 减少请求频率和同时执行数量，若返回 Retry-After 则遵循它。503 DATA_STALE 表示存储快照过旧，SERVICE_UNAVAILABLE 表示暂不可用；有限次数退避重试，并保留请求 ID。

Key 只放在服务端环境变量或密钥库，并通过 Authorization Header 发送。不要放入浏览器代码、URL、Git、截图、日志或 Analytics。分享排错信息时只保留请求 ID、操作、时间、状态和错误码；若 Key 泄露，在控制台轮换或撤销后更新服务端配置。