云端录制

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

由公开 REST 接口定义生成

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

分组概览

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

方法	路径	摘要
`POST`	`/v1/apps/{appid}/cloud_recording/acquire`	Agora: acquire a recording resource
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start`	Agora: start cloud recording
`GET`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query`	Agora: query cloud recording
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop`	Agora: stop cloud recording
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout`	Agora: update layout
`POST`	`/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update`	Update a recording session
`GET`	`/v1/recordings`	List recording tasks
`POST`	`/v1/recordings`	Start a recording task
`GET`	`/v1/recordings/{id}`	Get a recording task
`GET`	`/v1/recordings/{id}/files/{fileIndex}`	Download one recording file
`POST`	`/v1/recordings/{id}/files/{fileIndex}/playback-ticket`	Issue a short-lived playback ticket for one recording file
`POST`	`/v1/recordings/{id}/layout`	Update layout of a running recording
`POST`	`/v1/recordings/{id}/stop`	Stop a recording task

操作详情

POST `/v1/apps/{appid}/cloud_recording/acquire`

Agora: acquire a recording resource

Returns a single-use resourceId valid for 30 seconds; call start next.

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

参数

名称	位置	必填	类型	说明
`appid`	path	是	`string`	pattern ^[a-f0-9]{32}$

请求体

字段	类型	必填
`cname`	`string`	是
`uid`	`string`	是
`clientRequest`	`object`

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "scene": 0
  }
}

响应

状态码	说明 / schema
`200`	`{ resourceId }` — `AgoraRecordingResource`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/acquire" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"scene":0}}'

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start`

Agora: start cloud recording

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

参数

名称	位置	必填	类型	说明
`appid`	path	是	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	是	`string`	长度 0..128
`mode`	path	是	`enum(mix \| individual \| web)`

请求体

字段	类型	必填	说明
`cname`	`string`	是
`uid`	`string`	是
`clientRequest`	`object`		recordingConfig / storageConfig subset

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "recordingConfig": {
      "mixedVideoLayout": 1
    }
  }
}

响应

状态码	说明 / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, state } }` — `AgoraRecordingStart`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/mode/mix/start" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"recordingConfig":{"mixedVideoLayout":1}}}'

GET `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query`

Agora: query cloud recording

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

参数

名称	位置	必填	类型	说明
`appid`	path	是	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	是	`string`	长度 0..128
`sid`	path	是	`string`	长度 0..128
`mode`	path	是	`enum(mix \| individual \| web)`

响应

状态码	说明 / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, status, fileList } }` — `AgoraRecordingQuery`

调用示例

bash

curl -s -X GET "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/sid/$SID/mode/mix/query" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop`

Agora: stop cloud recording

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

参数

名称	位置	必填	类型	说明
`appid`	path	是	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	是	`string`	长度 0..128
`sid`	path	是	`string`	长度 0..128
`mode`	path	是	`enum(mix \| individual \| web)`

请求体

字段	类型	必填	说明
`cname`	`string`
`uid`	`string`
`clientRequest`	`object`

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {}
}

响应

状态码	说明 / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, status, fileList } }` — `AgoraRecordingStop`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/sid/$SID/mode/mix/stop" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{}}'

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout`

Agora: update layout

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

参数

名称	位置	必填	类型	说明
`appid`	path	是	`string`	pattern ^[a-f0-9]{32}$
`resourceId`	path	是	`string`	长度 0..128
`sid`	path	是	`string`	长度 0..128
`mode`	path	是	`enum(mix \| individual \| web)`

请求体

字段	类型	必填	说明
`cname`	`string`
`uid`	`string`
`clientRequest`	`object`

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "mixedVideoLayout": 2
  }
}

响应

状态码	说明 / schema
`200`	`{ resourceId, sid, serverResponse: { taskId, layout } }` — `AgoraRecordingLayout`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/$RESOURCE_ID/sid/$SID/mode/mix/updateLayout" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"mixedVideoLayout":2}}'

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update`

Update a recording session

Changes the subscription list, pauses or resumes a web page recording, or re-points the CDN push of a running session. Only valid while the session is active.

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

参数

名称	位置	必填	类型	说明
`appid`	path	是	`string`	pattern ^[a-f0-9]{32}$
`resourceid`	path	是	`string`	长度 0..128
`sid`	path	是	`string`	长度 0..128
`mode`	path	是	`enum(mix \| individual \| web)`

请求体

字段	类型	必填	说明
`cname`	`string`	是	长度 0..128
`uid`	`string`	是	长度 0..64
`clientRequest`	`object{ streamSubscribe, webRecordingConfig, rtmpPublishConfig, storageConfig }`	是

json

{
  "cname": "weekly-sync",
  "uid": "10001",
  "clientRequest": {
    "streamSubscribe": {
      "audioUidList": {
        "subscribeAudioUids": [
          "string"
        ],
        "unsubscribeAudioUids": [
          "string"
        ]
      },
      "videoUidList": {
        "subscribeVideoUids": [
          "string"
        ],
        "unsubscribeVideoUids": [
          "string"
        ]
      }
    },
    "webRecordingConfig": {
      "onhold": true
    },
    "rtmpPublishConfig": {
      "outputs": [
        {
          "rtmpUrl": "string"
        }
      ]
    }
  }
}

响应

状态码	说明 / schema
`200`	the session was updated — `object{ resourceId, sid, serverResponse }`
`400`	Invalid parameter — `Error`
`401`	Missing/invalid credentials — `Error`
`403`	Banned or service not enabled — `Error`
`404`	Resource not found — `Error`
`415`	Content-Type must be application/json — `Error`
`429`	Quota exceeded — `Error`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/apps/$APP_ID/cloud_recording/resourceid/resourceid/sid/$SID/mode/mix/update" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"cname":"weekly-sync","uid":"10001","clientRequest":{"streamSubscribe":{"audioUidList":{"subscribeAudioUids":["string"],"unsubscribeAudioUids":["string"]},"videoUidList":{"subscribeVideoUids":["string"],"unsubscribeVideoUids":["string"]}},"webRecordingConfig":{"onhold":true},"rtmpPublishConfig":{"outputs":[{"rtmpUrl":"string"}]}}}'

GET `/v1/recordings`

List recording tasks

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

参数

名称	位置	类型	说明
`channelName`	query	`string`
`state`	query	`string`	comma separated
`limit`	query	`integer`	<= 200

响应

状态码	说明 / schema
`200`	`{ total, tasks }` — `RecordingTaskList`

调用示例

bash

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

POST `/v1/recordings`

Start a recording task

Requires the recording service. Composite mode records the mixed room; individual records one file per publisher; web records a page-oriented layout.

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

请求体

字段	类型	必填
`channelName`	`string`	是
`mode`	`enum(composite \| individual \| web)`
`layout`	`object`
`subscribeAudioUids`	`array<integer>`
`subscribeVideoUids`	`array<integer>`
`maxDurationSeconds`	`integer`
`idempotencyKey`	`string`

json

{
  "channelName": "weekly-sync",
  "mode": "composite",
  "layout": {
    "preset": "grid"
  }
}

响应

状态码	说明 / schema
`202`	accepted — `RecordingTaskBody`
`403`	Banned or service not enabled — `Error`
`404`	Resource not found — `Error`
`429`	Quota exceeded — `Error`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"channelName":"weekly-sync","mode":"composite","layout":{"preset":"grid"}}'

GET `/v1/recordings/{id}`

Get a recording task

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

参数

名称	位置	必填	类型	说明
`id`	path	是	`string`	长度 0..128

响应

状态码	说明 / schema
`200`	task — `RecordingTaskBody`
`404`	Resource not found — `Error`

调用示例

bash

curl -s -X GET "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

GET `/v1/recordings/{id}/files/{fileIndex}`

Download one recording file

Streams the stored artifact of a recording task. Tenant-scoped: the task is looked up inside the authenticated project, so another tenant id returns 404. Replaces the deprecated operator-only /internal/objects/{objectKey} surface (no tenant boundary, sunset 2027-01-31).

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

参数

名称	位置	必填	类型	说明
`id`	path	是	`string`	长度 0..128
`fileIndex`	path	是	`integer`	>= 0

响应

状态码	说明 / schema
`200`	recording file bytes
`404`	Resource not found — `Error`

调用示例

bash

curl -s -X GET "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/files/1" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/recordings/{id}/files/{fileIndex}/playback-ticket`

Issue a short-lived playback ticket for one recording file

Browser players cannot attach Basic credentials to a <video> request, so a tenant-authenticated caller exchanges its credentials for a 10-minute HMAC ticket. The returned URL carries ?expires=&ticket= and the file route accepts it without project authentication (the signature covers task id, file index and expiry). Returns 503 when RECORDING_PLAYBACK_SECRET is not configured.

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

参数

名称	位置	必填	类型	说明
`id`	path	是	`string`	长度 0..128
`fileIndex`	path	是	`integer`	>= 0

响应

状态码	说明 / schema
`200`	signed playback URL and its expiry — `object{ url, expiresAt }`
`401`	Missing/invalid credentials — `Error`
`404`	Resource not found — `Error`
`503`	playback signing is not configured on this deployment — `Error`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/files/1/playback-ticket" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

POST `/v1/recordings/{id}/layout`

Update layout of a running recording

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

参数

名称	位置	必填	类型	说明
`id`	path	是	`string`	长度 0..128

请求体

字段	类型	必填	说明
`preset`	`enum(grid \| bestFit \| pip \| single)`
`canvasWidth`	`integer \| null`
`canvasHeight`	`integer \| null`
`backgroundColor`	`string \| null`

json

{
  "preset": "pip"
}

响应

状态码	说明 / schema
`200`	the task after the layout was applied — `RecordingTaskBody`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/layout" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
  -H "Content-Type: application/json" \
  -d '{"preset":"pip"}'

POST `/v1/recordings/{id}/stop`

Stop a recording task

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

参数

名称	位置	必填	类型	说明
`id`	path	是	`string`	长度 0..128

响应

状态码	说明 / schema
`200`	the stopped task (same shape as `GET /v1/recordings/{id}`) — `RecordingTaskBody`
`404`	Resource not found — `Error`

调用示例

bash

curl -s -X POST "$NIMEET_API_BASE/v1/recordings/weekly-sync_1a2b/stop" \
  -H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"

本分组用到的 Schema

AgoraRecordingFile — object{ fileName, duration, size }

字段	类型	必填	说明
`fileName`	`string`	是
`duration`	`number`	是	seconds; 0 while the file is still being written
`size`	`number`	是	bytes; 0 while the file is still being written

AgoraRecordingLayout — object{ resourceId, sid, serverResponse }

字段	类型	必填
`resourceId`	`string`	是
`sid`	`string`	是
`serverResponse`	`object{ taskId, layout }`	是

AgoraRecordingQuery — object{ resourceId, sid, serverResponse }

字段	类型	必填
`resourceId`	`string`	是
`sid`	`string`	是
`serverResponse`	`object{ taskId, status, fileList, error }`	是

AgoraRecordingResource — object{ resourceId }

字段	类型	必填	说明
`resourceId`	`string`	是	single-use marker valid for 30 s; pass it to `start`

AgoraRecordingStart — object{ resourceId, sid, serverResponse }

字段	类型	必填	说明
`resourceId`	`string`	是
`sid`	`string`	是	our recording task id (Agora calls it `sid`)
`serverResponse`	`object{ taskId, state }`	是

AgoraRecordingStop — object{ resourceId, sid, serverResponse }

字段	类型	必填
`resourceId`	`string`	是
`sid`	`string`	是
`serverResponse`	`object{ taskId, status, fileList }`	是

Error — object{ code, message, reason, sdkCode, details }

字段	类型	必填	说明
`code`	`string`	是	stable machine code, see errors.json
`message`	`string`	是
`reason`	`string`
`sdkCode`	`integer`		Agora-aligned client error number
`details`	`object`

RecordingTaskBody — object

字段	类型	必填	说明
`id`	`string`
`channelName`	`string`
`mode`	`enum(composite \| individual \| web)`
`state`	`enum(starting \| running \| stopping \| stopped \| failed \| expired)`
`layout`	`object{ preset, canvasWidth, canvasHeight, backgroundColor }`
`files`	`array<object{ objectKey, url, format, durationSeconds, sizeBytes }>`
`usageSeconds`	`number`
`error`	`string \| null`
`startedAt`	`string \| null`
`endedAt`	`string \| null`

RecordingTaskList — object{ total, tasks }

字段	类型	必填	说明
`total`	`integer`	是
`tasks`	`array<object>`	是

云端录制

分组概览

操作详情

POST /v1/apps/{appid}/cloud_recording/acquire

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start

GET /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout

POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update

GET /v1/recordings

POST /v1/recordings

GET /v1/recordings/{id}

GET /v1/recordings/{id}/files/{fileIndex}

POST /v1/recordings/{id}/files/{fileIndex}/playback-ticket

POST /v1/recordings/{id}/layout

POST /v1/recordings/{id}/stop

本分组用到的 Schema

POST `/v1/apps/{appid}/cloud_recording/acquire`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/mode/{mode}/start`

GET `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/query`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/stop`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceId}/sid/{sid}/mode/{mode}/updateLayout`

POST `/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update`

GET `/v1/recordings`

POST `/v1/recordings`

GET `/v1/recordings/{id}`

GET `/v1/recordings/{id}/files/{fileIndex}`

POST `/v1/recordings/{id}/files/{fileIndex}/playback-ticket`

POST `/v1/recordings/{id}/layout`

POST `/v1/recordings/{id}/stop`