RTC开发者文档中心 飞雁云
English

Canvas 视频布局状态

构建时从公开 REST 接口定义的 `canvas` 标签生成：方法、路径、参数、请求体、响应与 curl。

由公开 REST 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

分组概览

本页由公开 REST 接口定义在构建时生成：标签 canvas，共 9 个操作（全量 230 个）。鉴权、信封与分页约定见 REST API 总览.

方法路径摘要
GET/v1/canvas/canvasesList canvases
POST/v1/canvas/canvasesCreate a canvas
GET/v1/canvas/canvases/{canvasId}Read a canvas with its views
DELETE/v1/canvas/canvases/{canvasId}Destroy a canvas
PATCH/v1/canvas/canvases/{canvasId}/configSet canvas configs
GET/v1/canvas/canvases/{canvasId}/viewsList canvas views
POST/v1/canvas/canvases/{canvasId}/viewsAdd a view
PATCH/v1/canvas/canvases/{canvasId}/views/{uid}Update one view
DELETE/v1/canvas/canvases/{canvasId}/views/{uid}Remove a view

操作详情

GET /v1/canvas/canvases

List canvases

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
channelNamequerystring
statequeryenum(active | destroyed)

响应

状态码说明 / schema
200OK — object{ canvases }
400Invalid parameter — Error

调用示例

bash
curl -s -X GET "$NIMEET_API_BASE/v1/canvas/canvases?channelName=weekly-sync&state=running" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST /v1/canvas/canvases

Create a canvas

One active canvas per (project, channel, ownerUid); a duplicate answers canvas_conflict with the existing canvasId. Owner null (or omitted) means a channel-wide shared layout.

鉴权：项目凭证（customerId:customerSecret 的 Base64）

请求体

字段类型必填说明
channelNamestring是pattern ^[A-Za-z0-9_-]{1,128}$
ownerUidinteger | null1..2147483647
videoRenderModeenum(hidden | fit | adaptive)
videoMirrorModeenum(auto | enabled | disabled)
backgroundColorstring
json
{
  "channelName": "weekly-sync",
  "ownerUid": 1,
  "videoRenderMode": "hidden"
}

响应

状态码说明 / schema
201OK — CanvasDetail
400Invalid parameter — Error
409Canvas already exists (canvas_conflict) — Error

调用示例

bash
curl -s -X POST "$NIMEET_API_BASE/v1/canvas/canvases" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"channelName":"weekly-sync","ownerUid":1,"videoRenderMode":"hidden"}'

GET /v1/canvas/canvases/{canvasId}

Read a canvas with its views

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string

响应

状态码说明 / schema
200OK — CanvasDetail
404Unknown canvas (canvas_not_found) — Error

调用示例

bash
curl -s -X GET "$NIMEET_API_BASE/v1/canvas/canvases/canvasId" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

DELETE /v1/canvas/canvases/{canvasId}

Destroy a canvas

Moves the canvas to destroyed. The layout stays readable for forensics, but every write afterwards answers canvas_destroyed.

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string

响应

状态码说明 / schema
200OK — CanvasRecord
404Unknown canvas (canvas_not_found) — Error
409Canvas already destroyed (canvas_destroyed) — Error

调用示例

bash
curl -s -X DELETE "$NIMEET_API_BASE/v1/canvas/canvases/canvasId" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

PATCH /v1/canvas/canvases/{canvasId}/config

Set canvas configs

Agora setConfigs / setVideoRenderMode / setVideoMirrorMode. At least one field is required.

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string

请求体

字段类型必填说明
videoRenderModeenum(hidden | fit | adaptive)
videoMirrorModeenum(auto | enabled | disabled)
backgroundColorstring
json
{
  "videoRenderMode": "hidden",
  "videoMirrorMode": "auto",
  "backgroundColor": "string"
}

响应

状态码说明 / schema
200OK — CanvasDetail
400Invalid parameter — Error
404Unknown canvas (canvas_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

调用示例

bash
curl -s -X PATCH "$NIMEET_API_BASE/v1/canvas/canvases/canvasId/config" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"videoRenderMode":"hidden","videoMirrorMode":"auto","backgroundColor":"string"}'

GET /v1/canvas/canvases/{canvasId}/views

List canvas views

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string

响应

状态码说明 / schema
200OK — object{ count, views }
404Unknown canvas (canvas_not_found) — Error

调用示例

bash
curl -s -X GET "$NIMEET_API_BASE/v1/canvas/canvases/canvasId/views" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST /v1/canvas/canvases/{canvasId}/views

Add a view

Agora addView(ViewInfo). Re-adding the same uid replaces the existing view (setupMode=replace), matching the SDK ViewInfo set semantics.

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string

请求体

字段类型必填说明
uidinteger是1..2147483647
subviewUidinteger | null1..2147483647
videoRenderModeenum(hidden | fit | adaptive)
videoMirrorModeenum(auto | enabled | disabled)
sourceTypeenum(video | screen | mediaPlayer)
mediaPlayerIdinteger | null0..9999
positionobject{ x, y, width, height, zOrder }
backgroundColorstring
json
{
  "uid": 1,
  "subviewUid": 1,
  "videoRenderMode": "hidden"
}

响应

状态码说明 / schema
201OK — CanvasView
400Invalid parameter — Error
404Unknown canvas (canvas_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

调用示例

bash
curl -s -X POST "$NIMEET_API_BASE/v1/canvas/canvases/canvasId/views" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"uid":1,"subviewUid":1,"videoRenderMode":"hidden"}'

PATCH /v1/canvas/canvases/{canvasId}/views/{uid}

Update one view

Agora setViewConfig (the replace branch of addView:config:).

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string
uidpath是integer1..2147483647

请求体

字段类型必填说明
subviewUidinteger | null1..2147483647
videoRenderModeenum(hidden | fit | adaptive)
videoMirrorModeenum(auto | enabled | disabled)
sourceTypeenum(video | screen | mediaPlayer)
mediaPlayerIdinteger | null0..9999
positionobject{ x, y, width, height, zOrder }
backgroundColorstring
json
{
  "subviewUid": 1,
  "videoRenderMode": "hidden",
  "videoMirrorMode": "auto"
}

响应

状态码说明 / schema
200OK — CanvasView
400Invalid parameter — Error
404Unknown canvas or view (canvas_view_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

调用示例

bash
curl -s -X PATCH "$NIMEET_API_BASE/v1/canvas/canvases/canvasId/views/10001" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"subviewUid":1,"videoRenderMode":"hidden","videoMirrorMode":"auto"}'

DELETE /v1/canvas/canvases/{canvasId}/views/{uid}

Remove a view

Agora removeView(ViewInfo). Removing an absent view is a 404, not a silent success.

鉴权：项目凭证（customerId:customerSecret 的 Base64）

参数

名称位置必填类型说明
canvasIdpath是string
uidpath是integer1..2147483647

响应

状态码说明 / schema
204view removed
404Unknown canvas or view (canvas_view_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

调用示例

bash
curl -s -X DELETE "$NIMEET_API_BASE/v1/canvas/canvases/canvasId/views/10001" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

本分组用到的 Schema

CanvasConfig — object{ videoRenderMode, videoMirrorMode, backgroundColor, renderModeCode, mirrorModeCode }
字段类型必填说明
videoRenderModeenum(hidden | fit | adaptive)是
videoMirrorModeenum(auto | enabled | disabled)是
backgroundColorstring是
renderModeCodeinteger是Agora numeric code: hidden=1, fit=2, adaptive=3.
mirrorModeCodeinteger是Agora numeric code: auto=0, enabled=1, disabled=2.
CanvasDetail — object
字段类型必填说明
canvasIdstring是
projectIdstring
channelNamestring是
ownerUidinteger | null
stateenum(active | destroyed)是
configobject{ videoRenderMode, videoMirrorMode, backgroundColor, renderModeCode, mirrorModeCode }是
viewCountinteger>= 0
viewsarray<object>是
createdAtstringformat date-time
updatedAtstringformat date-time
destroyedAtstring | nullformat date-time
CanvasPosition — object{ x, y, width, height, zOrder }
字段类型必填说明
xnumber是
ynumber是
widthnumber是
heightnumber是
zOrderinteger是
CanvasRecord — object
字段类型必填说明
canvasIdstring是
projectIdstring是
channelNamestring是
ownerUidinteger | null
stateenum(active | destroyed)是
configobject{ videoRenderMode, videoMirrorMode, backgroundColor, renderModeCode, mirrorModeCode }是
viewCountinteger是>= 0
createdAtstringformat date-time
updatedAtstringformat date-time
destroyedAtstring | nullformat date-time
CanvasView — object
字段类型必填说明
uidinteger是>= 1
subviewUidinteger | null
renderModeenum(hidden | fit | adaptive)是
mirrorModeenum(auto | enabled | disabled)是
renderModeCodeinteger
mirrorModeCodeinteger
sourceTypeenum(video | screen | mediaPlayer)是
mediaPlayerIdinteger | null
positionobject{ x, y, width, height, zOrder }是
backgroundColorstring | null
setupModeenum(add | replace)是
updatedAtstring是format date-time
Error — object{ code, message, reason, sdkCode, details }
字段类型必填说明
codestring是stable machine code, see errors.json
messagestring是
reasonstring
sdkCodeintegerAgora-aligned client error number
detailsobject

本页由文档构建流水线生成 · 2026-11-05 14:43:28 UTC · 文档中心 v1.1.0.

内容依据公开 API 定义.

ni-meet 是自建 RTC PaaS，媒体面基于 LiveKit（Apache-2.0），并与声网 API 兼容。