Cloudflare RealtimeKit 完整 API 参考Meeting 对象、REST 端点与 SDK 方法实战指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以 RealtimeKit 官方 API 参考文档为主体系统讲解客户端RealtimeKitClient的 Meeting 对象self/participants/chat/polls/plugins/ai/meta、TypeScript 类型定义、响应式 Store 架构以及从会议管理、参与者、录制、直播到 Webhook 的完整 REST API 与 Session 生命周期。读完本文你将掌握基于cloudflare/realtimekit构建实时音视频应用所需的全部 API 细节并能在 realtimekit 配套文档 与仓库源码的佐证下直接落地编码。RealtimeKit API 总览RealtimeKit 是构建在 Cloudflare Realtime SFU 之上的 SDK 套件抽象了 WebRTC 的底层复杂度为 Web/移动端提供可定制的实时音视频能力。客户端通过cloudflare/realtimekit包中的RealtimeKitClient与云端交互服务端则通过 Cloudflare API v4 的/realtime/kit/{app_id}端点管理会议、参与者与录制。其 API 体系分为三层客户端 Meeting 对象meeting.join()/meeting.leave()以及meeting.self、meeting.participants、meeting.meta、meeting.chat、meeting.polls、meeting.plugins、meeting.ai命名空间TypeScript 类型RealtimeKitClient、Participant、States、UIConfig等REST API会议、参与者、录制、直播、会话分析、Webhook 等管理端点。在阅读 API 细节前建议先明确几个核心概念详见 README 核心概念App工作区聚合 meetings、participants、presets、recordings建议 staging/production 使用独立 AppMeeting可复用的虚拟房间每次加入会创建新的SessionParticipant通过 REST API 添加的用户返回的authToken供客户端 SDK 使用不可复用Peer IDid每次会话唯一重连会变化Participant IDuserId跨会话持久。Meeting 对象 APImeeting是RealtimeKitClient实例化后暴露的入口对象所有状态与操作都挂在它的命名空间上。meeting.self本地参与者meeting.self描述本地参与者即当前用户其属性覆盖身份与媒体状态属性id、userId、name、audioEnabled、videoEnabled、screenShareEnabled、audioTrack、videoTrack、screenShareTracks、roomJoined、roomState。方法一览// 媒体开关启用/禁用音频、视频、屏幕共享 await meeting.self.enableAudio() / disableAudio() / enableVideo() / disableVideo() await meeting.self.enableScreenShare() / disableScreenShare() // 设置昵称——注意只能在 join 之前调用 await meeting.self.setName(Name) // 设备管理设置当前设备或枚举所有可用设备 await meeting.self.setDevice(device) const devices await meeting.self.getAllDevices() / getAudioDevices() / getVideoDevices() / getSpeakerDevices()事件meeting.self.on(roomJoined, () {}) meeting.self.on(audioUpdate, ({ audioEnabled, audioTrack }) {})meeting.self支持的事件还包括videoUpdate、screenShareUpdate、deviceUpdate、deviceListUpdate。设备切换的典型用法是先getAllDevices()拿到设备列表再根据用户选择用setDevice(device)切换见 patterns.md 设备选择示例。meeting.participants远端参与者集合meeting.participants提供四个响应式集合均为 Live Mapjoined已加入、active活跃、waitlisted等待列表中、pinned固定。// 集合操作转数组、计数、按键取值 const participants meeting.participants.joined.toArray() const count meeting.participants.joined.size() const p meeting.participants.joined.get(peer-id)每个 participant 对象属性与self同构id / userId / name、audioEnabled / videoEnabled / screenShareEnabled、audioTrack / videoTrack / screenShareTracks。事件监听meeting.participants.joined.on(participantJoined, (participant) {}) meeting.participants.joined.on(participantLeft, (participant) {})一个常见的坑meeting.participants不包含meeting.self因此参会总人数应为meeting.participants.joined.size() 1见 gotchas.md。meeting.meta会议元数据meeting.meta.meetingId / meetingTitle / meetingStartedTimestamp可用于在roomJoined事件后展示会议信息或埋点统计。meeting.chat聊天meeting.chat.messages // 消息数组 await meeting.chat.sendTextMessage(Hello) / sendImageMessage(file) meeting.chat.on(chatUpdate, ({ message, messages }) {})聊天消息有 4000 字符的长度上限见 gotchas.md 限制表。meeting.polls投票meeting.polls.items // 投票数组 await meeting.polls.create(question, options, anonymous, hideVotes) await meeting.polls.vote(pollId, optionIndex)对应 REST 侧的POST /meetings/{meeting_id}/active-session/poll端点。meeting.plugins协作应用Addonmeeting.plugins.all // 插件数组 await meeting.plugins.activate(pluginId) / deactivate()插件系统允许在会议中激活白板等协作应用监听pluginActivated事件可感知激活状态见 patterns.md Addon 小节。meeting.aiAI 能力meeting.ai.transcripts // 实时转写需在 Preset 中开启核心方法await meeting.join() // 加入会议成功后 meeting.self 触发 roomJoined await meeting.leave() // 离开会议注意时序监听器必须在join()之前注册否则会错过事件见 gotchas.md 事件不触发。TypeScript 类型定义所有类型均可从cloudflare/realtimekit导入import type { RealtimeKitClient, States, UIConfig, Participant } from cloudflare/realtimekit; // 主接口 interface RealtimeKitClient { self: SelfState; // 本地参与者 (id, userId, name, audioEnabled, videoEnabled, roomJoined, roomState) participants: { joined, active, waitlisted, pinned }; // 响应式 Maps chat: ChatNamespace; // messages[], sendTextMessage(), sendImageMessage() polls: PollsNamespace; // items[], create(), vote() plugins: PluginsNamespace; // all[], activate(), deactivate() ai: AINamespace; // transcripts[] meta: MetaState; // meetingId, meetingTitle, meetingStartedTimestamp join(): Promisevoid; leave(): Promisevoid; } // Participantself 与远端参与者共用同一结构 interface Participant { id: string; // Peer ID重连后会变化 userId: string; // 持久化参与者 ID name: string; audioEnabled: boolean; videoEnabled: boolean; screenShareEnabled: boolean; audioTrack: MediaStreamTrack | null; videoTrack: MediaStreamTrack | null; screenShareTracks: MediaStreamTrack[]; }RealtimeKitClient的构造配置可参考 configuration.md 核心 SDK 配置支持authToken、video、audio、autoSwitchAudioDevice以及mediaConfiguration视频分辨率、帧率、回声消除、降噪、屏幕共享参数等。Store 架构响应式状态驱动RealtimeKit 采用响应式 Store 架构核心原则是事件驱动更新 Live Maps// 订阅状态变更 meeting.self.on(audioUpdate, ({ audioEnabled, audioTrack }) {}); meeting.participants.joined.on(participantJoined, (p) {}); // 同步读取当前状态 const isAudioOn meeting.self.audioEnabled; const count meeting.participants.joined.size();关键原则状态变更后先更新再发事件订阅者拿到的永远是最新状态克制使用.toArray()集合是 Live Map频繁转数组会造成不必要的内存与渲染开销仅在需要遍历渲染时才调用优先事件而非轮询事件驱动是官方推荐模式配合 patterns.md 中的 React HooksuseRealtimeKitSelector可以做到自动重渲染、选择器记忆化与类型安全。REST API 参考REST 端点的基础路径为https://api.cloudflare.com/client/v4/accounts/{account_id}/realtime/kit/{app_id}所有 REST 调用必须由服务端发起Workers 或后端严禁在客户端暴露 API Token否则会触发 CORS 问题并带来安全风险见 gotchas.md。会议管理MeetingsGET /meetings # 列出全部会议 GET /meetings/{meeting_id} # 获取会议详情 POST /meetings # 创建会议: {title: ...} PATCH /meetings/{meeting_id} # 更新会议: {title: ..., record_on_start: true}参与者管理ParticipantsGET /meetings/{meeting_id}/participants # 列出全部参与者 GET /meetings/{meeting_id}/participants/{participant_id} # 获取参与者详情 POST /meetings/{meeting_id}/participants # 添加参与者: {name: ..., preset_name: ..., custom_participant_id: ...} PATCH /meetings/{meeting_id}/participants/{participant_id} # 更新参与者: {name: ..., preset_name: ...} DELETE /meetings/{meeting_id}/participants/{participant_id} # 删除参与者 POST /meetings/{meeting_id}/participants/{participant_id}/token # 刷新参与者 tokenPOST /participants是客户端接入的关键返回的authToken需下发给前端用于初始化RealtimeKitClientcustom_participant_id可用于对接自有用户体系实现跨会话追踪。token 默认 24 小时过期会话中过期时使用 refresh 端点续期不要复用旧 token。活跃会话Active SessionGET /meetings/{meeting_id}/active-session # 获取活跃会话 POST /meetings/{meeting_id}/active-session/kick # 踢出指定用户: {user_ids: [id1, id2]} POST /meetings/{meeting_id}/active-session/kick-all # 踢出全部用户 POST /meetings/{meeting_id}/active-session/poll # 创建投票: {question: ..., options: [...], anonymous: false}录制RecordingGET /recordings?meeting_id{meeting_id} # 列出录制 GET /recordings/active-recording/{meeting_id} # 获取进行中的录制 POST /recordings # 开始录制: {meeting_id: ..., type: composite}或 track PUT /recordings/{recording_id} # 控制录制: {action: pause}或 resume、stop POST /recordings/track # 轨道录制: {meeting_id: ..., layers: [...]}录制需要 Preset 具备canRecord与canStartStopRecording权限且要求存在活跃会话至少一名参与者在线录制最长 6 小时见 gotchas.md。直播LivestreamingGET /livestreams?exclude_meetingsfalse # 列出全部直播 GET /livestreams/{livestream_id} # 获取直播详情 POST /meetings/{meeting_id}/livestreams # 为会议开启直播 POST /meetings/{meeting_id}/active-livestream/stop # 停止直播 POST /livestreams # 创建独立直播返回 {ingest_server, stream_key, playback_url}会话与数据分析Sessions AnalyticsGET /sessions # 列出全部会话 GET /sessions/{session_id} # 获取会话详情 GET /sessions/{session_id}/participants # 列出会话参与者 GET /sessions/{session_id}/participants/{participant_id} # 通话统计 GET /sessions/{session_id}/chat # 下载聊天记录 CSV GET /sessions/{session_id}/transcript # 下载转写记录 CSV GET /sessions/{session_id}/summary # 获取摘要 POST /sessions/{session_id}/summary # 生成摘要 GET /analytics/daywise?start_dateYYYY-MM-DDend_dateYYYY-MM-DD # 按天统计 GET /analytics/livestreams/overall # 直播整体统计WebhooksGET /webhooks # 列出全部 Webhook POST /webhooks # 创建: {url: https://..., events: [session.started, session.ended]} PATCH /webhooks/{webhook_id} # 更新 DELETE /webhooks/{webhook_id} # 删除Webhook 事件可用于服务端感知会话生命周期如session.started、session.ended触发对应的业务逻辑计费、通知、数据落库等。Session 生命周期Initialization → Join Intent → [Waitlist?] → Meeting Screen (Stage) → Ended ↓ Approved [Rejected → Ended]UI Kit 会自动处理状态流转。当 Preset 开启候场Waitlist时参与者进入等待队列由服务端通过active-session/waitlist/approve审核通过后客户端自动进入会议房间并触发meeting.self的roomJoined事件见 patterns.md Waitlist 处理。每次加入会议都会创建一个新的 Session最后一个参与者离开后 Session 结束。实战整合从 REST 到客户端的完整调用链将 REST 与客户端 SDK 串联起来的典型模式是Worker 后端生成 token → 前端拿到 token 初始化客户端 → 加入会议并监听状态。服务端Worker侧代码可参考 patterns.md 后端集成示例前端请求/api/join-meetingWorker 用CLOUDFLARE_API_TOKEN调用POST /meetings/{id}/participants将返回的data.result.authToken下发给前端。客户端核心流程import RealtimeKitClient from cloudflare/realtimekit; const meeting new RealtimeKitClient({ authToken: token, video: true, audio: true }); meeting.self.on(roomJoined, () console.log(Joined:, meeting.meta.meetingTitle)); meeting.participants.joined.on(participantJoined, (p) console.log(${p.name} joined)); await meeting.join();调试时可参考 gotchas.md 调试技巧监听deviceListUpdate排查设备问题、监听roomJoined打印会议信息、对全部事件打日志等。小结与扩展阅读RealtimeKit 的 API 设计围绕响应式 Store 事件驱动展开客户端通过meeting对象完成音视频、聊天、投票、插件与 AI 转写的全功能交互服务端通过 REST API 完成资源管理与生命周期控制。两者的边界清晰——媒体与控制走 SDK管理与凭证走服务端 REST。本仓库中与本文配套的参考资料RealtimeKit 概览与快速开始 —— 核心概念、Quick Start、包选型RealtimeKit 配置指南 —— SDK 安装、Preset、wrangler、主题与 i18nRealtimeKit 使用模式 —— UI 组件、React Hooks、后端集成、最佳实践RealtimeKit 常见问题 —— 错误排查、限额表、安全与性能建议。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考