RoomScope

آخر تحديث

LIVE

جلسات LIVE المسجّلة، وأداء كل صانع محتوى، ومصدر فيديو LIVE.

تُصادَق كل عملية بمفتاح API (Authorization: Bearer <key>) وتستخدم الأخطاء الغلاف المشترك الموضّح في الأخطاء. مولَّد من مستند OpenAPI الخاص بواجهة API.

جلب أداء LIVE لصانع محتوى

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

صف واحد لكل جلسة مسجّلة: المدة، وذروة المشاهدين، والهدايا، والماسات، وعدد الداعمين دون تكرار.

النطاقlive:readوحدات الرصيدقراءة مخزنة مؤقتًا

معاملات المسار

معاملات المسار · GET /v1/live/creators/{uid}/performance
NameTypeDescription
uidRequired
stringاسم مستخدم صانع المحتوى دون @ (linh.live) أو معرّف مستخدم TikTok الرقمي.

معاملات الاستعلام

معاملات الاستعلام · 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 الحالية لصانع المحتوى. يحمّله المشغّل لديك مباشرة من شبكة CDN التابعة لـ TikTok (source: tiktok-cdn)؛ ولا يمرّر RoomScope الفيديو عبر خوادمه أبدًا. يُفضَّل hlsUrl؛ أما flvUrl فهو مصدر الغرف التي لا تدعم إلا FLV (شغّله بمحرك MSE مثل mpegts.js)؛ ويُضبط واحد منهما على الأقل عندما تكون 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 غير متاح مؤقتًا؛ أعد المحاولة بعد Retry-After عندما تكون قيمة retryable هي true.

جدولة تحديث لحالة البث

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

يطلب من العمّال التحقق الآن مما إذا كان صانع المحتوى يبث مباشرة. يُحتسب بتعرفة التحديث.

النطاقlive:readوحدات الرصيدتحديث حالة البث

معاملات المسار

معاملات المسار · POST /v1/live/creators/{uid}/refresh
NameTypeDescription
uidRequired
stringاسم مستخدم صانع المحتوى دون @ (linh.live) أو معرّف مستخدم TikTok الرقمي.

الطلب

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معرّف الجلسة من القائمة.

الطلب

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.
هل كانت هذه الصفحة مفيدة؟