最後更新
LIVE
已錄製的 LIVE 場次、各創作者表現、LIVE 影片來源與近期 LIVE 聊天。
所有操作都以 API 金鑰進行身分驗證 (Authorization: Bearer <key>) ;錯誤一律使用共通的錯誤格式,說明請見 錯誤. 本頁由 API 的 OpenAPI 文件產生。
列出送禮者
/v1/gifters過去 7 天或 30 天內,在 RoomScope 記錄的 LIVE 直播間送禮的送禮者,依鑽石數排序:禮物數、場次、受贈創作者數、最後一個直播間的創作者,以及前一個區間的鑽石數。每位送禮者都屬於一個分群:whale(7 天內至少 10,000 鑽石,或 30 天內至少 30,000)、rising(至少 1,000 鑽石且達前一個區間的兩倍)、regular(3 場以上)、one_time(1 場)或 occasional。region 只保留送給該地區創作者的禮物。覆蓋率一律為 partial。需要 Pro 方案以上。
查詢參數
| Name | Type | Description |
|---|---|---|
windowOptional | "7d" | "30d" | 7d 或 30d。Default: 7d |
segmentOptional | "whale" | "rising" | "regular" | "one_time" | "occasional" | 只包含一個分群。 |
regionOptional | string | 受贈創作者的地區(例如 VN)。 |
limitOptional | integer | 最多列數。 範圍 …–500. Default: 50 |
請求
curl "https://api.next.toktokdata.live/v1/gifters" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "data": { "window": "7d", "region": "VN", "segment": null, "counts": { "whale": 1, "rising": 0, "regular": 0, "one_time": 0, "occasional": 0, "total": 1 }, "gifters": [ { "gifterUserId": "6987001122334455667", "gifterUniqueId": "minh.fan", "gifterNickname": "Minh", "avatarUrl": null, "diamondTotal": 18450, "previousDiamondTotal": 9200, "giftCount": 312, "sessions": 4, "creatorsGifted": 2, "lastGiftAt": "2026-11-02T15:41:07.512Z", "lastRoomCreator": "linh.live", "segment": "whale" } ] }, "provenance": { "observedAt": "2026-11-02T15:41:07.512Z", "freshness": "historical", "source": "platform_observed_gifter_events", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "gifters-observed-v1", "window": { "from": "2026-10-27T04:00:00.000Z", "to": "2026-11-03T04:00:00.000Z", "label": "7d" } }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
列出禮物
/v1/gifts在 RoomScope 記錄的 LIVE 直播間中出現過的 TikTok 禮物,附上單一禮物的金幣數、送出該禮物的地區,以及首次與最後一次出現的時間。禮物在至少 3 個地區出現過時,isGlobal 為 true。不包含圖片,也不包含尚未有人送出的禮物,因此覆蓋率為 partial。每日同步。
查詢參數
| Name | Type | Description |
|---|---|---|
qOptional | string | 禮物名稱的一部分。 |
minCoinsOptional | integer | 單一禮物的最低金幣數。 |
maxCoinsOptional | integer | 單一禮物的最高金幣數。 |
regionOptional | string | 只包含在此地區出現過的禮物(例如 VN)。 |
sortOptional | "coins" | "name" | "recent" | coins(由多到少)、name 或 recent。Default: coins |
limitOptional | integer | 最多列數。 範圍 …–500. Default: 100 |
請求
curl "https://api.next.toktokdata.live/v1/gifts" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "data": { "gifts": [ { "giftId": "5655", "name": "Rose", "coins": 1, "imageUrl": null, "isGlobal": false, "regions": [ "VN" ], "firstSeenAt": "2026-11-01T02:14:09.000Z", "lastSeenAt": "2026-11-07T08:41:52.000Z" } ], "total": 1 }, "provenance": { "observedAt": "2026-11-07T03:10:00.000Z", "freshness": "near_realtime", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "gift-catalog-observed-v1", "window": null }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
取得創作者近期的 LIVE 聊天
/v1/live/creators/{uid}/comments創作者 LIVE 房間的最新聊天留言(由舊到新),供播放器旁的聊天面板使用。每隔幾秒呼叫一次,並把上一次回應的 cursor 作為 after 傳入,即可只取得較新的留言(每次回應最多 100 則;若超過則為最新的 100 則)。只有 RoomScope 追蹤且你的工作區也追蹤(watchlist 或房間訂閱)的房間才有留言:status: tracked 並附 roomId,否則為不含項目的 status: not_tracked(followed 表示工作區是否追蹤該創作者)。RoomScope 會在最後一則留言後保留房間最近 200 則留言 10 分鐘。免費(不扣點數),每位使用者每分鐘限 60 次請求(超過時回傳 429 並附 Retry-After)。
路徑參數
| Name | Type | Description |
|---|---|---|
uidRequired | string | 創作者帳號名稱(linh.live);開頭的 @ 會被忽略。 |
查詢參數
| Name | Type | Description |
|---|---|---|
afterOptional | string | 上一次回應的 cursor:只取較新的留言。 |
請求
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/comments" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "status": "tracked", "followed": true, "roomId": "7665709659185105682", "items": [ { "id": "7568123456789012345", "createdAt": "2026-11-06T13:05:41.512Z", "comment": "hello from Hanoi!", "user": { "uniqueId": "minh.fan", "nickname": "Minh", "avatarUrl": "https://p16-sign-sg.tiktokcdn.com/avatar-minh.jpeg" } }, { "id": "7568123456789012399", "createdAt": "2026-11-06T13:05:43.208Z", "comment": "sing the last song again please", "user": { "uniqueId": "an.nguyen", "nickname": "An", "avatarUrl": null } } ], "cursor": "1793970343251-0", "provenance": { "observedAt": "2026-11-06T13:05:43.251Z", "freshness": "near_realtime", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "live-history-v1", "window": null }}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。503暫時無法使用;當retryable為 true 時,請在Retry-After後重試。
取得創作者的 LIVE 表現
/v1/live/creators/{uid}/performance每場已記錄的直播一列:時長、峰值觀眾、禮物、鑽石與不重複送禮者數。只適用於工作區追蹤清單中的創作者或成員追蹤的直播間;否則 items 為空且 followed 為 false。
路徑參數
| Name | Type | Description |
|---|---|---|
uidRequired | string | 不含 @ 的創作者帳號名稱(linh.live)或數字形式的 TikTok 使用者 ID。 |
查詢參數
| Name | Type | Description |
|---|---|---|
cursorOptional | string | 來自上一頁 nextCursor 的不透明游標。 |
limitOptional | integer | 每頁列數。 範圍 1–100. Default: 50 |
請求
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/performance" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "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, "followed": true }, "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會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
取得創作者的 LIVE 影像來源
/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。
路徑參數
| Name | Type | Description |
|---|---|---|
uidRequired | string | 創作者帳號名稱(linh.live);開頭的 @ 會被忽略。 |
請求
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/playback" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "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}錯誤
401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。503暫時無法使用;當retryable為 true 時,請在Retry-After後重試。
排入 LIVE 狀態更新
/v1/live/creators/{uid}/refresh要求工作程序立即檢查該創作者是否正在直播。以更新費率計費。
路徑參數
| Name | Type | Description |
|---|---|---|
uidRequired | string | 不含 @ 的創作者帳號名稱(linh.live)或數字形式的 TikTok 使用者 ID。 |
請求
curl -X POST "https://api.next.toktokdata.live/v1/live/creators/linh.live/refresh" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "queued": true, "jobId": "1761994604935-0"}錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
列出已記錄的 LIVE 場次
/v1/live/sessionsRoomScope 為工作區追蹤清單中的創作者及成員追蹤的直播間所記錄的直播場次,由新到舊;其他工作區的場次絕不會出現。仍在進行中的場次 endedAt: null。
查詢參數
| Name | Type | Description |
|---|---|---|
creatorUniqueIdOptional | string | 只包含此創作者的場次(不含 @ 的帳號名稱)。 |
cursorOptional | string | 來自上一頁 nextCursor 的不透明游標。 |
limitOptional | integer | 每頁場次數。 範圍 1–100. Default: 50 |
請求
curl "https://api.next.toktokdata.live/v1/live/sessions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "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會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
取得 LIVE 場次
/v1/live/sessions/{session_id}一場直播及其禮物與送禮者彙總。工作區未追蹤的創作者或直播間的場次會回傳 404。
路徑參數
| Name | Type | Description |
|---|---|---|
session_idRequired | string | 清單中的場次 ID。 |
請求
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "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會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
逐分鐘取得 LIVE 場次
/v1/live/sessions/{session_id}/timeline場次自開始起的每分鐘序列:每分鐘最高觀看數、事件、聊天、按讚、禮物、鑽石、新送禮者與寶箱,並附自開始起的 offsetMinutes。僅限已錄製的房間;在此序列存在前錄製的場次沒有分鐘資料(coverageStatus: not-covered)。可見範圍與場次本身相同。
路徑參數
| Name | Type | Description |
|---|---|---|
session_idRequired | string | 清單中的場次 ID。 |
請求
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9/timeline" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "data": { "sessionId": "5b9f0c2e-7a51-5d3c-9b0e-1f2a3c4d5e6f", "creatorUniqueId": "linh.live", "startedAt": "2026-11-06T12:00:04.211Z", "endedAt": "2026-11-06T14:00:12.903Z", "durationSeconds": 7208, "peakViewerCount": 1240, "totalGiftDiamonds": 18450, "minutes": [ { "minuteAt": "2026-11-06T12:00:00.000Z", "offsetMinutes": 0, "viewersMax": 800, "events": 120, "chats": 60, "likes": 300, "gifts": 4, "diamonds": 40, "newGifters": 1, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:01:00.000Z", "offsetMinutes": 1, "viewersMax": 840, "events": 130, "chats": 65, "likes": 320, "gifts": 5, "diamonds": 55, "newGifters": 2, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:02:00.000Z", "offsetMinutes": 2, "viewersMax": 880, "events": 140, "chats": 70, "likes": 340, "gifts": 6, "diamonds": 70, "newGifters": 1, "envelopes": 1 } ] }, "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會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
比較 LIVE 場次
/v1/live/sessions/compare並列兩到四個場次,各自附總計及依其自身開始起 offsetMinutes 對齊的分鐘資料。工作區未追蹤的任何場次都回傳 404。
查詢參數
| Name | Type | Description |
|---|---|---|
idsRequired | string | 以逗號分隔的場次 ID,2 到 4 個。 |
請求
curl "https://api.next.toktokdata.live/v1/live/sessions/compare?ids=value" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
{ "data": { "sessions": [ { "sessionId": "5b9f0c2e-7a51-5d3c-9b0e-1f2a3c4d5e6f", "creatorUniqueId": "linh.live", "startedAt": "2026-11-06T12:00:04.211Z", "endedAt": "2026-11-06T14:00:12.903Z", "durationSeconds": 7208, "peakViewerCount": 1240, "totalGiftDiamonds": 18450, "minutes": [ { "minuteAt": "2026-11-06T12:00:00.000Z", "offsetMinutes": 0, "viewersMax": 800, "events": 120, "chats": 60, "likes": 300, "gifts": 4, "diamonds": 40, "newGifters": 1, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:01:00.000Z", "offsetMinutes": 1, "viewersMax": 840, "events": 130, "chats": 65, "likes": 320, "gifts": 5, "diamonds": 55, "newGifters": 2, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:02:00.000Z", "offsetMinutes": 2, "viewersMax": 880, "events": 140, "chats": 70, "likes": 340, "gifts": 6, "diamonds": 70, "newGifters": 1, "envelopes": 1 } ] }, { "sessionId": "8c1d2e3f-4a5b-5c6d-8e7f-9a0b1c2d3e4f", "creatorUniqueId": "linh.live", "startedAt": "2026-11-05T12:01:10.000Z", "endedAt": "2026-11-05T13:30:40.000Z", "durationSeconds": 5370, "peakViewerCount": 980, "totalGiftDiamonds": 9200, "minutes": [ { "minuteAt": "2026-11-06T12:00:00.000Z", "offsetMinutes": 0, "viewersMax": 800, "events": 120, "chats": 60, "likes": 300, "gifts": 4, "diamonds": 80, "newGifters": 1, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:01:00.000Z", "offsetMinutes": 1, "viewersMax": 880, "events": 130, "chats": 65, "likes": 320, "gifts": 5, "diamonds": 110, "newGifters": 2, "envelopes": 0 } ] } ] }, "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會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。