# GXRTC服务器API文档 ## 接口标准定义： ### 标准返回JSON 模版： | Key | Value | 说明 | | ---- | ----- | ---- | | meta | {"code": 400, "message": "params face_img is required"} | | code | 参考HTTP status code规范：https://developer.mozilla.org/en-US/docs/Web/HTTP/Status | | message | 用于客户端将提示给用户显示| | data | {} | map KV结构，key 一定为string,Value可为任意对象，可理解为Golang中的map[string]interface{} | 异常返回示例： ```bash {"meta": {"code": 400, "message": "params face_img is required"}} ``` 正常返回结构体参考： ```bash { "meta": { "code": 200 }, "data": { "imgs": [ "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0........" ] } } ``` ### 服务定义： - 服务器API根路径：https://meeting.cnsdt.com/api/v1 - 服务API返回值说明： - 服务端所有API Respose返回格式默认为json - json结构： - 异常返回示例： ```json { "meta": { "code": 403, "error": "user unauthorized", "message": "用户没有登录，不能使用" } } ``` - 正常返回示例： ```json { "meta": { "code": 200 }, "data": { "rooms": [ { "sid": "RM_44AJticWDN3t", "name": "thehome", "empty_timeout": 300, "departure_timeout": 20, "creation_time": 1731684825, "turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA", "enabled_codecs": [ { "mime": "audio/opus" }, { "mime": "audio/red" }, { "mime": "video/VP8" }, { "mime": "video/H264" }, { "mime": "video/VP9" }, { "mime": "video/AV1" } ] } ] } } ``` ## API: 获取access_token ### Request: - API Path: `/room/token` - Method: `POST` - Content Type: `form` - Params: - uid: `string` 用户ID - room: `string` 房间ID - Example: ```bash curl -XPOST https://{{API_ROOT}}/api/v1/room/token -d "uid=xtqxk&room=thehome" ``` ### Response: - Example: ```json { "meta": { "code": 200 }, "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzE2ODg3OTgsImlzcyI6IkFQSTdaOUNQamhtdVo4eCIsIm5iZiI6MTczMTY4NTE5OCwic3ViIjoieHRxeGsiLCJ2aWRlbyI6eyJyb29tIjoidGhlaG9tZSIsInJvb21Kb2luIjp0cnVlfX0.GfNtz3u7kXQRJ3Rkg4usQOF2uDdJSrXfJmD3aewB-4M" } } ``` ## API: 创建房间 ### Request: - API Path: `/room/` - Method: `POST` - Content Type: `form` - Params: - room: `string` 房间ID，目前与名称重叠，未来房间ID会由服务器指定，客户端仅支持传递房间名称 - Example: ```bash curl -XPOST https://{{API_ROOT}}/api/v1/room/ -d "room=thehome" ``` ### Response: - Example: ```json { "meta": { "code": 200 }, "data": { "sid": "RM_44AJticWDN3t", "name": "thehome", "empty_timeout": 300, "departure_timeout": 20, "creation_time": 1731684825, "turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA", "enabled_codecs": [ { "mime": "audio/opus" }, { "mime": "audio/red" }, { "mime": "video/VP8" }, { "mime": "video/H264" }, { "mime": "video/VP9" }, { "mime": "video/AV1" } ] } } ``` ## API: 获取所有房间列表 ### Request: - API Path: `/room/` - Method: `GET` - Example: ```bash curl -XGET https://{{API_ROOT}}/api/v1/room/ ``` ### Response: ```json { "meta": { "code": 200 }, "data": { "rooms": [ { "sid": "RM_44AJticWDN3t", "name": "thehome", "empty_timeout": 300, "departure_timeout": 20, "creation_time": 1731684825, "turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA", "enabled_codecs": [ { "mime": "audio/opus" }, { "mime": "audio/red" }, { "mime": "video/VP8" }, { "mime": "video/H264" }, { "mime": "video/VP9" }, { "mime": "video/AV1" } ] } ] } } ``` ## API: 解散房间 ### Request: - API Path: `/room/{{room}}` - Method: `DELETE` - Params: - room: `string` 房间ID，目前与名称重叠，未来房间ID会由服务器指定，客户端仅支持传递房间名称 - Example: ```bash curl -XDELETE https://{{API_ROOT}}/api/v1/room/thehome ``` ### Response: - Example: 成功返回被删除的房音详情 ```json { "meta": { "code": 200 }, "data": { "sid": "RM_44AJticWDN3t", "name": "thehome", "empty_timeout": 300, "departure_timeout": 20, "creation_time": 1731684825, "turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA", "enabled_codecs": [ { "mime": "audio/opus" }, { "mime": "audio/red" }, { "mime": "video/VP8" }, { "mime": "video/H264" }, { "mime": "video/VP9" }, { "mime": "video/AV1" } ] } } ``` 失败返回错误信息，如房间不存在，或没有权限等 ## API: 获取房间参与者列表 ### Request: - API Path: `/room/{{room}}/participants` - Method: `GET` - Params: - room: `string` 房间ID - Example: ```bash curl -XGET https://{{API_ROOT}}/api/v1/room/{{room}}/participants ``` ### Response: - Example: ```json { "meta": { "code": 200 }, "data": { "participants": [ { "sid": "user1", "name": "Alice", "joined_at": 1731684825, "...":"..." }, { "sid": "user2", "name": "Bob", "joined_at": 1731684830, "...":"..." } ] } } ``` - participants: `[]ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo)列表 ## API: 从房间中移除参与者 ### Request: - API Path: `/room/{{room}}/participant/{{uid}}` - Method: `DELETE` - Params: - room: `string` 房间ID - uid: `string` 用户ID - Example: ```bash curl -XDELETE https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}} ``` ### Response: - Example: 当成功时，失败时code不为200 ```json { "meta": { "code": 200 } } ``` ## API: 获取房间中指定用户的详情 ### Request: - API Path: `/room/{{room}}/participant/{{uid}}` - Method: `GET` - Params: - room: `string` 房间ID - uid: `string` 用户ID - Example: ```bash curl -XGET https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}} ``` ### Response: - Example: ```json { "meta": { "code": 200 }, "data": { // ParticipantInfo "sid": "user1", "name": "Alice", "joined_at": 1731684825, "...":"..." } } ``` - data : `ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo) ## API: 将房间中的用户禁音/解禁 ### Request: - API Path: `/room/{{room}}/participant/{{uid}}/mute` - Method: `POST/DELETE`, POST:禁音，DELETE解禁 - Params: - room: `string` 房间ID - uid: `string` 用户ID - Example: ```bash curl -XPOST https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}/mute ``` ### Response: - Example: 当成功时，失败时code不为200 ```json { "meta": { "code": 200 } } ``` ## API: 更新房间中的用户信息 ### Request: - API Path: `/room/{{room}}/participant/{{uid}}/info` - Method: `POST` - Params: - room: `string` 房间ID - uid: `string` 用户ID - Form: - attrs: `string`, json 格式的key,value结构，如：{"nickname":"rick","gender":"male"} - metadata: `string`, 任意格式的字符串 - Example: ```bash curl -XPOST https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}/info -d "metadata=metadata_string&attrs=%7B%22nickname%22%3A%22rick%22%2C%22gender%22%3A%22male%22%7D" ``` ### Response: - Example: ```json { "meta": { "code": 200 }, "data": { // ParticipantInfo "sid": "user1", "name": "Alice", "joined_at": 1731684825, "...":"..." } } ``` - data : `ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo) ## API: 更新房间中的用户权限 ### Request: - API Path: `/room/{{room}}/participant/{{uid}}/permissions` - Method: `POST` - Params: - room: `string` 房间ID - uid: `string` 用户ID - Form: - permission: `string`, json 格式的key,value结构，permission结构体参考：[permission](structs.md#participantpermission) - Example: ```bash curl -XPOST https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}/info -d "permission="%7B%22can_subscribe%22%3Atrue%2C%22can_publish%22%3Afalse%7D"" ``` ### Response: - Example: ```json { "meta": { "code": 200 }, "data": { // ParticipantInfo "sid": "user1", "name": "Alice", "joined_at": 1731684825, "...":"..." } } ``` - data : `ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo)