使用 API 與 SDK 開發
7:50 操作示範
影片旁白為英文。
Toktik Developer API 是計量式 REST API，另有官方 SDK——JavaScript/TypeScript 使用 @toktikhq/sdk-js，Python 使用 toktik。從快速入門、驗證與點數開始，再複製現成的 cURL、JavaScript 與 Python 範例。
你會學到什麼
- 建立金鑰並送出第一個已驗證的請求
- 了解 scope、速率限制與點數模型
- 使用 JavaScript 與 Python SDK
- 閱讀文件：快速入門、端點與 scope
運作方式
在 Settings 中建立金鑰
在應用程式中開啟 Settings，再進入 Developer keys，並只選擇所需的 scope 來建立金鑰，例如排行榜使用 rank:read。密鑰以 ttk_live_ 開頭且只會顯示一次，請存放在環境變數中。金鑰只能存取資料路由，建立金鑰仍須在登入狀態下進行。
送出第一個請求
將金鑰以 Authorization: Bearer 搭配你的 ttk_live_ 密鑰傳送。文件中的快速入門會以 board=hourly 與 region=VN 呼叫位於 api.toktikhq.com/v1/rankings/official 的官方排行榜。收到 403 代表該金鑰缺少該路由所需的 scope。
在限制與點數內運作
每支金鑰依方案有每秒請求上限，從 Free 的 1 到 Agency 的 150。超過上限會收到 429，此時請等待 Retry-After 後再重試。點數用完會回傳 402，重試無法解決，而 GET /v1/usage 會顯示你的花費。
加入官方 SDK
JavaScript 與 TypeScript 請安裝 npm i @toktikhq/sdk-js，Python 請使用 pip install toktik；兩者都以相同的金鑰與相同的點數錢包呼叫同一個 v1 REST API。Docs 中的 Quickstart 與 API Reference 頁面列出每個端點、參數與 scope。
常見問題
Toktik API 的費用是多少？
沒有另外的 API 價目表。網頁應用程式與 API 在同一個方案下花費同一個點數錢包。從 Toktik 資料庫提供的一次讀取為 1 點，一次匯出為 2,500 點，隨選蒐集的呼叫則花費更多。
Toktik API 的速率限制是多少？
每支金鑰每秒：Free 1、Starter 5、Pro 20、Scale 60、Agency 150。另有每日配額，從 Free 的 5,000 次請求到 Agency 的 1,200,000 次。超過上限會回傳 429，並以標頭顯示時間窗的狀態。
Toktik 有官方 SDK 嗎？
有。@toktikhq/sdk-js 涵蓋 JavaScript 與 TypeScript，toktik 套件涵蓋 Python。兩者都使用相同的金鑰呼叫同一個 v1 REST API。
Toktik API 回傳 402 和 403 有什麼差別？
402 表示工作區點數已用完，應該加購而不是重試。403 表示金鑰有效但缺少所需的 scope，請授予該 scope 或改用登入工作階段。429 是速率限制，退避一段時間後可安全重試。