RTCDeveloper Docs Flyan Cloud
中文

Canvas Video Layout State

Canvas configuration, views, render mode and mirror mode state backing the SDK Canvas capability.

Generated from the public REST API definitions

Version v1.1.0 · Updated 2026-10-26 · revision 1

Group overview

Generated at build time from the public REST API definition: tag canvas, 9 operations (out of 230). For authentication, envelope and pagination conventions see REST API overview.

MethodPathSummary
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

Operation details

GET /v1/canvas/canvases

List canvases

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
channelNamequerystring
statequeryenum(active | destroyed)

Response

Status codesDescription / schema
200OK — object{ canvases }
400Invalid parameter — Error

Example call

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.

Authentication: project credentials (Base64 of customerId:customerSecret)

Request body

FieldTypeRequiredDescription
channelNamestringispattern ^[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"
}

Response

Status codesDescription / schema
201OK — CanvasDetail
400Invalid parameter — Error
409Canvas already exists (canvas_conflict) — Error

Example call

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

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring

Response

Status codesDescription / schema
200OK — CanvasDetail
404Unknown canvas (canvas_not_found) — Error

Example call

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.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring

Response

Status codesDescription / schema
200OK — CanvasRecord
404Unknown canvas (canvas_not_found) — Error
409Canvas already destroyed (canvas_destroyed) — Error

Example call

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.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring

Request body

FieldTypeRequiredDescription
videoRenderModeenum(hidden | fit | adaptive)
videoMirrorModeenum(auto | enabled | disabled)
backgroundColorstring
json
{
  "videoRenderMode": "hidden",
  "videoMirrorMode": "auto",
  "backgroundColor": "string"
}

Response

Status codesDescription / schema
200OK — CanvasDetail
400Invalid parameter — Error
404Unknown canvas (canvas_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

Example call

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

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring

Response

Status codesDescription / schema
200OK — object{ count, views }
404Unknown canvas (canvas_not_found) — Error

Example call

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.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring

Request body

FieldTypeRequiredDescription
uidintegeris1..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"
}

Response

Status codesDescription / schema
201OK — CanvasView
400Invalid parameter — Error
404Unknown canvas (canvas_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

Example call

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:).

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring
uidpathisinteger1..2147483647

Request body

FieldTypeRequiredDescription
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"
}

Response

Status codesDescription / schema
200OK — CanvasView
400Invalid parameter — Error
404Unknown canvas or view (canvas_view_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

Example call

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.

Authentication: project credentials (Base64 of customerId:customerSecret)

Parameters

NameLocationRequiredTypeDescription
canvasIdpathisstring
uidpathisinteger1..2147483647

Response

Status codesDescription / schema
204view removed
404Unknown canvas or view (canvas_view_not_found) — Error
409Canvas is destroyed (canvas_destroyed) — Error

Example call

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

Schemas used by this group

CanvasConfig — object{ videoRenderMode, videoMirrorMode, backgroundColor, renderModeCode, mirrorModeCode }
FieldTypeRequiredDescription
videoRenderModeenum(hidden | fit | adaptive)is
videoMirrorModeenum(auto | enabled | disabled)is
backgroundColorstringis
renderModeCodeintegerisAgora numeric code: hidden=1, fit=2, adaptive=3.
mirrorModeCodeintegerisAgora numeric code: auto=0, enabled=1, disabled=2.
CanvasDetail — object
FieldTypeRequiredDescription
canvasIdstringis
projectIdstring
channelNamestringis
ownerUidinteger | null
stateenum(active | destroyed)is
configobject{ videoRenderMode, videoMirrorMode, backgroundColor, renderModeCode, mirrorModeCode }is
viewCountinteger>= 0
viewsarray<object>is
createdAtstringformat date-time
updatedAtstringformat date-time
destroyedAtstring | nullformat date-time
CanvasPosition — object{ x, y, width, height, zOrder }
FieldTypeRequiredDescription
xnumberis
ynumberis
widthnumberis
heightnumberis
zOrderintegeris
CanvasRecord — object
FieldTypeRequiredDescription
canvasIdstringis
projectIdstringis
channelNamestringis
ownerUidinteger | null
stateenum(active | destroyed)is
configobject{ videoRenderMode, videoMirrorMode, backgroundColor, renderModeCode, mirrorModeCode }is
viewCountintegeris>= 0
createdAtstringformat date-time
updatedAtstringformat date-time
destroyedAtstring | nullformat date-time
CanvasView — object
FieldTypeRequiredDescription
uidintegeris>= 1
subviewUidinteger | null
renderModeenum(hidden | fit | adaptive)is
mirrorModeenum(auto | enabled | disabled)is
renderModeCodeinteger
mirrorModeCodeinteger
sourceTypeenum(video | screen | mediaPlayer)is
mediaPlayerIdinteger | null
positionobject{ x, y, width, height, zOrder }is
backgroundColorstring | null
setupModeenum(add | replace)is
updatedAtstringisformat date-time
Error — object{ code, message, reason, sdkCode, details }
FieldTypeRequiredDescription
codestringisstable machine code, see errors.json
messagestringis
reasonstring
sdkCodeintegerAgora-aligned client error number
detailsobject

Generated by the documentation build pipeline · 2026-11-05 14:43:28 UTC · Documentation center v1.1.0.

Content follows the public API definitions.

ni-meet is a self-hosted RTC PaaS with a LiveKit-based media plane (Apache-2.0) and an Agora-compatible API.