快速入門

準備一個 ShortsMonkey 帳戶和一個具有 HTTPS 存取權限的伺服器端終端。 cURL 範例需要 cURL； JavaScript 需要帶有 fetch 的 Node.js； Python 需要請求。顯示的所有金鑰均為佔位符：使用您自己帳戶中的金鑰。

登錄，開啟 API 控制台，然後從一次性顯示複製完整金鑰。 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_ 密鑰、Bearer 後面的空格、環境變數以及密鑰是否過期、被撤銷或超過其輪換寬限期。對於403 INSUFFICIENT_SCOPE，檢查api：read；對於 403 ACCOUNT_DISABLED，請檢查帳戶狀態並聯絡支援人員。重複重試不會修復身份驗證或權限。

透過error.code區分429：API_DAILY_LIMIT_REACHED需要等到00:00亞洲/上海；RATE_LIMITED 要求減少頻率和並發請求，並在提供時遵守 Retry-After。 503 DATA_STALE 表示儲存的快照太舊； SERVICE_UNAVAILABLE 表示暫時無法使用。使用帶回退的有界重試並保留請求 ID。

將金鑰保存在伺服器端環境變數或秘密儲存體中，並在授權標頭中傳送。請勿將其放入瀏覽器代碼、URL、Git、螢幕截圖、日誌或分析中。僅共用請求 ID、操作、時間、狀態和錯誤代碼以進行診斷。如果暴露，請在控制台中輪換或撤銷金鑰並更新伺服器配置。