快速开始

从注册到在浏览器里听到声音,按下面五步操作。全部在网页上完成,不需要写代码。

一、五步跑通

注册。打开注册页:填邮箱,收 6 位验证码,阅读并勾选协议,设置口令(至少 12 个字符),把密钥添加到身份验证器 App 并输入 6 位动态码。完成后页面会显示账号 ID、命名空间(ns)和一把 API key。账号 ID 和 API key 都只显示一次,请先保存。
登录控制台。打开控制台,输入账号 ID(不是邮箱)、口令和身份验证器上当前的 6 位动态码。
建房。在「房间管理」里选择命名空间,填房间号(1–128 位,字母、数字、. _ -,首字符须是字母或数字),档位可留空用服务端默认,点「建房」。
分麦位。在房间列表点「进入」,打开房间页。在第 ③ 块「麦位」里选一个麦位号(0–19),输入要授权的 uid 后缀,点「分配麦位」。
收听与发言。第 ① 块点「点击开始收听」;第 ② 块点「点击开始发言」并允许浏览器使用麦克风。必须先分麦位,再开始发言,否则状态显示 mic=none(已连接但还没有麦位),你的声音不会被房间听到。

同一个 uid 在同一房间不要同时收听和发言。房间页给收听和发言默认了不同的后缀(listener1 与 speaker1),保持不同即可。发言需要 https 页面和麦克风权限。

登录用的是注册时显示的账号 ID,不是邮箱。账号 ID 丢失后,目前没有自助找回入口。

二、概念

名称	含义
租户	一次注册对应一个租户。租户拥有自己的命名空间、账号和 API key,租户之间的数据互相不可见。
命名空间(ns)	租户名下用来隔离房间的空间,房间都建在某个 ns 里。控制台只列出当前账号被授权的 ns。无权限、不存在、格式不合法的 ns,接口返回同一个 403,无法区分。
房间	在某个 ns 里用房间号创建。状态有开放(open)、已锁定(locked)、已关闭(closed)。关闭不可撤销,已关闭的房间号不能复用。
通行证(pass)	加入房间用的一次性短期凭证,绑定本次浏览器连接的指纹,过期或用过一次后需要重新签发。通行证是秘密,不要写日志、不要放进网址。房间页自动完成签发,不需要手动操作。
麦位(slot)	每个房间 20 个麦位,编号 0–19。给某个 uid 分配麦位后,它的声音才进入房间。同一 uid 分到新麦位时,旧麦位自动腾出;释放麦位只认麦位号。
uid	格式为 `账号ID.后缀`,后缀为 1–48 位字母、数字、下划线或连字符。前缀必须是当前登录账号的 ID,用别人的前缀会被拒绝。

三、控制台接口概述

下面是控制台网页实际调用的接口,均在控制台站点自己的域名下(与控制台网页同源)。鉴权方式:登录后服务端写入 __Host-tytalk_sid 会话 cookie(HttpOnly);写操作还需要请求头 X-CSRF-Token(来自登录或 GET /api/v1/session 的响应)和 Content-Type: application/json。这些接口目前只为控制台网页设计,面向服务端程序的公开调用方式尚未提供。

请求	说明	成功
`POST /api/v1/login`	体 `{account, password, totp}`	200,返回 `{account, csrf_token, expires_at}`
`POST /api/v1/logout`	体 `{}`,需 CSRF	204
`GET /api/v1/session`	恢复会话并取新的 CSRF 令牌	200
`GET /api/v1/ns`	我被授权的命名空间	200,`{ns: [{ns, role}]}`
`GET /api/v1/ns/{ns}/rooms?limit&cursor`	房间列表,游标分页	200,`{rooms, next_cursor}`,`next_cursor` 为空串即最后一页
`POST /api/v1/ns/{ns}/rooms`	建房,体 `{room_id[, profile]}`	201
`POST /api/v1/ns/{ns}/rooms/{room}/close`	关房,体 `{}`	200
`POST /api/v1/ns/{ns}/rooms/{room}/pass`	签通行证,体 `{role, uid, fp}`,`role` 为 `listen` 或 `speak`,`fp` 为 64 位十六进制的连接指纹	200,`{pass, expires_at, region}`
`POST /api/v1/ns/{ns}/rooms/{room}/slots/{n}/assign`	分麦位,体 `{uid}`,`n` 为 0–19	200,`{slot: {slot, uid, epoch, not_after}}`
`POST /api/v1/ns/{ns}/rooms/{room}/slots/{n}/release`	释放麦位,体 `{}`	200

错误响应统一为 {"error": {"code": "...", "message": "..."}},请按 code 判断。epoch 可能超过 2⁵³,请按字符串处理。

四、常见错误码

HTTP	`code`	含义
401	`login_failed`	账号、口令或动态码不正确(三者失败返回同一个错误)
401	`unauthenticated`	未登录或会话已过期
403	`forbidden`	没有该命名空间的权限,或它不存在
403	`csrf_failed`	安全校验未通过,重新取 `/session` 后再试
400	`invalid_room` / `invalid_uid` / `invalid_slot` / `invalid_fp` / `invalid_role`	对应字段格式不合法
404	`not_found`	房间不存在
409	`conflict`	房间号已存在(已关闭的房间号也不能复用),或房间被锁定
410	`room_closed`	房间已关闭,不能再收听或发言
429	`rate_limited`	操作过于频繁,按响应头 `Retry-After`(秒)等待
501	`speak_unsupported`	当前环境尚未开通发言
503	`audit_unavailable`	审计暂不可用,本次操作未执行,可稍后重试
500	`audit_incomplete`	操作可能已执行但结果未记录,请刷新列表核对,不要重复提交

五、限制与说明

只做语音,不含视频与录音。
目前没有读取麦位列表的接口,房间页的麦位面板只显示本页本次操作的返回结果,不代表麦位的实时状态。
释放麦位只认麦位号,不校验当前持有者;同一命名空间内的操作者可以释放该命名空间内任一麦位。
试用期限与档位额度目前后端尚未执行,本页不代表任何期限、额度、价格或服务等级(SLA)承诺。
浏览器端已在 Chrome 上设计;手机麦克风与跨网络的实际效果还没有充分验证。
协议与隐私政策当前为草稿版本,全文在注册第 3 步展示。