RoomScope

最後更新

LIVE

已記錄的 LIVE 場次、各創作者的表現，以及 LIVE 影像來源。

所有操作都以 API 金鑰進行身分驗證 (Authorization: Bearer <key>) ；錯誤一律使用共通的錯誤格式，說明請見 錯誤. 本頁由 API 的 OpenAPI 文件產生。

取得創作者的 LIVE 表現

GET/v1/live/creators/{uid}/performance

每個已記錄的場次一列：時長、最高觀看人數、禮物、鑽石與不重複送禮者數。

權限範圍live:read點數快取讀取

路徑參數

路徑參數 · GET /v1/live/creators/{uid}/performance
NameTypeDescription
uidRequired
string不含 @ 的創作者帳號名稱（linh.live）或數字形式的 TikTok 使用者 ID。

查詢參數

查詢參數 · GET /v1/live/creators/{uid}/performance
NameTypeDescription
cursorOptional
string來自上一頁 nextCursor 的不透明游標。
limitOptional
integer每頁列數。 範圍 1–100.
Default: 50

請求

curl "https://api.toktokdata.live/v1/live/creators/linh.live/performance" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "data": {    "items": [      {        "sessionId": "f18eaa3e-a762-543d-9ea5-178271dc43f9",        "sessionStartedAt": "2026-11-01T07:51:44.935Z",        "creatorUniqueId": "linh.live",        "roomKey": "room:linh.live",        "durationSeconds": 7200,        "peakViewerCount": 2000,        "eventCount": 1000,        "chatCount": 600,        "giftCount": 80,        "totalGiftDiamonds": 5000,        "distinctGifterCount": 2      },      {        "sessionId": "278f3a86-af07-5768-85d2-6dfff8efee7d",        "sessionStartedAt": "2026-10-31T07:51:44.935Z",        "creatorUniqueId": "linh.live",        "roomKey": "room:linh.live",        "durationSeconds": 7200,        "peakViewerCount": 1000,        "eventCount": 500,        "chatCount": 300,        "giftCount": 40,        "totalGiftDiamonds": 2500,        "distinctGifterCount": 2      }    ],    "nextCursor": null,    "historyWindowDays": 365,    "historyTruncated": false  },  "provenance": {    "observedAt": "2026-11-01T07:51:44.935Z",    "freshness": "historical",    "source": "platform_observed_live_stream",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "live-history-v1",    "window": null  }}

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫；resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。

取得創作者的 LIVE 影像來源

GET/v1/live/creators/{uid}/playback

創作者目前 LIVE 直播間經簽署、會過期的影像網址。你的播放器會直接從 TikTok 的 CDN 載入（source: tiktok-cdn）；RoomScope 絕不代理影像。優先使用 hlsUrl；flvUrl 是僅提供 FLV 之直播間的來源（請以 mpegts.js 等 MSE 引擎播放）；在 status: live 時至少會有其中一個，expiresAt 為該網址失效的時間。renditions 經常為空。avatarUrl、followerCount 與 region 不明時為 null。其他回應：status: offline（未在直播）、status: no_playback（正在直播，但 TikTok 未提供可播放的來源）、202 status: resolving（請在 Retry-After 後輪詢同一網址）、503 collection_saturated 或 live_playback_upstream_unavailable（請重試），以及此部署環境關閉該功能時的 503 live_playback_not_configured（請勿重試）。需要 live:stream 權限範圍，而非 live:read。

權限範圍live:stream點數快取讀取

路徑參數

路徑參數 · GET /v1/live/creators/{uid}/playback
NameTypeDescription
uidRequired
string創作者帳號名稱（linh.live）；開頭的 @ 會被忽略。

請求

curl "https://api.toktokdata.live/v1/live/creators/linh.live/playback" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "status": "live",  "roomId": "7665709659185105682",  "title": "Friday night karaoke",  "nickname": "Linh",  "hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7665709727191485202_hd/index.m3u8?expire=1786024940&sign=ea92cabbf90993d50a0e3d50ee9ed526",  "flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7665709727191485202_hd.flv?expire=1786024940&sign=ea92cabbf90993d50a0e3d50ee9ed526",  "expiresAt": "2026-08-06T14:02:20.000Z",  "startedAt": "2026-07-23T09:46:40.000Z",  "renditions": [],  "avatarUrl": "https://p16-sign-sg.tiktokcdn.com/avatar.jpeg",  "verified": true,  "followerCount": 894314,  "region": "VN",  "source": "tiktok-cdn",  "cached": false}

錯誤

  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫；resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。
  • 503 暫時無法使用；當 retryable 為 true 時，請在 Retry-After 後重試。

排入 LIVE 狀態更新

POST/v1/live/creators/{uid}/refresh

要求工作程序立即檢查該創作者是否正在直播。以更新費率計費。

權限範圍live:read點數LIVE 狀態更新

路徑參數

路徑參數 · POST /v1/live/creators/{uid}/refresh
NameTypeDescription
uidRequired
string不含 @ 的創作者帳號名稱（linh.live）或數字形式的 TikTok 使用者 ID。

請求

curl -X POST "https://api.toktokdata.live/v1/live/creators/linh.live/refresh" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

202 Accepted
{  "queued": true,  "jobId": "1761994604935-0"}

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫；resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。

列出已記錄的 LIVE 場次

GET/v1/live/sessions

RoomScope 為工作區的創作者記錄的場次，由新到舊排列。仍在進行中的場次 endedAt: null。

權限範圍live:read點數快取讀取

查詢參數

查詢參數 · GET /v1/live/sessions
NameTypeDescription
creatorUniqueIdOptional
string只包含此創作者的場次（不含 @ 的帳號名稱）。
cursorOptional
string來自上一頁 nextCursor 的不透明游標。
limitOptional
integer每頁場次數。 範圍 1–100.
Default: 50

請求

curl "https://api.toktokdata.live/v1/live/sessions" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "data": {    "items": [      {        "id": "f18eaa3e-a762-543d-9ea5-178271dc43f9",        "roomKey": "room:linh.live",        "roomId": "7990000000000000001",        "creatorUniqueId": "linh.live",        "creatorAvatarUrl": null,        "startedAt": "2026-11-01T07:51:44.935Z",        "endedAt": "2026-11-01T09:51:44.935Z",        "peakViewerCount": 2000,        "eventCount": 1000,        "chatCount": 600,        "giftCount": 80,        "totalGiftDiamonds": 5000,        "durationSeconds": 7200      },      {        "id": "278f3a86-af07-5768-85d2-6dfff8efee7d",        "roomKey": "room:linh.live",        "roomId": "7990000000000000001",        "creatorUniqueId": "linh.live",        "creatorAvatarUrl": null,        "startedAt": "2026-10-31T07:51:44.935Z",        "endedAt": "2026-10-31T09:51:44.935Z",        "peakViewerCount": 1000,        "eventCount": 500,        "chatCount": 300,        "giftCount": 40,        "totalGiftDiamonds": 2500,        "durationSeconds": 7200      }    ],    "nextCursor": null,    "historyWindowDays": 365,    "historyTruncated": false  },  "provenance": {    "observedAt": "2026-11-01T09:51:44.935Z",    "freshness": "historical",    "source": "platform_observed_live_stream",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "live-history-v1",    "window": null  }}

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫；resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。

取得 LIVE 場次

GET/v1/live/sessions/{session_id}

單一場次，附禮物與送禮者彙總。

權限範圍live:read點數快取讀取

路徑參數

路徑參數 · GET /v1/live/sessions/{session_id}
NameTypeDescription
session_idRequired
string清單中的場次 ID。

請求

curl "https://api.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "data": {    "id": "278f3a86-af07-5768-85d2-6dfff8efee7d",    "roomKey": "room:linh.live",    "roomId": "7990000000000000001",    "creatorUniqueId": "linh.live",    "creatorAvatarUrl": null,    "startedAt": "2026-10-31T07:51:44.935Z",    "endedAt": "2026-10-31T09:51:44.935Z",    "peakViewerCount": 1000,    "eventCount": 500,    "chatCount": 300,    "giftCount": 40,    "totalGiftDiamonds": 2500,    "durationSeconds": 7200,    "giftRollups": [      {        "giftId": "5269",        "giftName": "TikTok",        "giftType": 1,        "giftCount": 10,        "diamondTotal": 2470,        "senderCount": 2      },      {        "giftId": "5655",        "giftName": "Rose",        "giftType": 1,        "giftCount": 30,        "diamondTotal": 30,        "senderCount": 2      }    ],    "gifterRollups": [      {        "gifterUserId": "991000000000000001",        "gifterUniqueId": "gifter.1",        "gifterNickname": "Gifter 1",        "giftCount": 20,        "diamondTotal": 1500      },      {        "gifterUserId": "991000000000000002",        "gifterUniqueId": "gifter.2",        "gifterNickname": "Gifter 2",        "giftCount": 20,        "diamondTotal": 1000      }    ]  },  "provenance": {    "observedAt": "2026-10-31T09:51:44.935Z",    "freshness": "stale",    "source": "platform_observed_live_stream",    "sourceKind": "derived",    "coverageStatus": "stale",    "methodologyVersion": "live-history-v1",    "window": null  }}

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫；resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。
這個頁面對你有幫助嗎？