Create a template via API

This endpoint is used to create a template. A recommended way is to provide a list of roles with empty objects to get default values for various options corresponding to those roles, then update those roles by modifying them using create/update role API.

| Deprecation Notice: The settings.enabled field which was used to enable custom composite recording, has been deprecated. Please use the new recordings API to configure composite recordings. | Deprecation Notice: The destinations.browserRecordings field which was used to provide configuration for browser based recording, has been deprecated. Please use the new recordings API to configure browser recording.

Understand sub-objects hierarchy

Template sub-objects hierarchy

POSThttps://api.100ms.live/v2/templates
curl --location --request POST 'https://api.100ms.live/v2/templates' \ --header 'Authorization: Bearer <management_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "new-template-{{$timestamp}}", "roles": { "guest": { "name": "guest", "publishParams": { "allowed": ["audio", "video", "screen"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 300, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 }, "simulcast": { "video": { "layers": [ { "rid": "f", "scaleResolutionDownBy": 1, "maxBitrate": 700, "maxFramerate": 25 }, { "rid": "h", "scaleResolutionDownBy": 2, "maxBitrate": 350, "maxFramerate": 25 }, { "rid": "q", "scaleResolutionDownBy": 4, "maxBitrate": 100, "maxFramerate": 25 } ] }, "screen": {} } }, "subscribeParams": { "subscribeToRoles": ["host", "guest"], "maxSubsBitRate": 3200, "subscribeDegradation": { "packetLossThreshold": 25, "degradeGracePeriodSeconds": 1, "recoverGracePeriodSeconds": 4 } }, "permissions": { "sendRoomState": false, "pollRead": true, "pollWrite": true }, "priority": 1, "maxPeerCount": 0 }, "host": { "name": "host", "publishParams": { "allowed": ["audio", "video", "screen"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 300, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 }, "simulcast": { "video": { "layers": [ { "rid": "f", "scaleResolutionDownBy": 1, "maxBitrate": 700, "maxFramerate": 25 }, { "rid": "h", "scaleResolutionDownBy": 2, "maxBitrate": 350, "maxFramerate": 25 }, { "rid": "q", "scaleResolutionDownBy": 4, "maxBitrate": 100, "maxFramerate": 25 } ] }, "screen": {} } }, "subscribeParams": { "subscribeToRoles": ["guest", "host"], "maxSubsBitRate": 3200, "subscribeDegradation": { "packetLossThreshold": 25, "degradeGracePeriodSeconds": 1, "recoverGracePeriodSeconds": 4 } }, "permissions": { "endRoom": true, "removeOthers": true, "mute": true, "unmute": true, "changeRole": true, "sendRoomState": false, "pollRead": true, "pollWrite": true }, "priority": 1, "maxPeerCount": 0 } }, "settings": { "region": "in", "recording": { "upload": { "type": "<upload type: supported are s3, gs, oss>", "location": "<Name of the storage bucket>", "prefix": "<Upload prefix path>", "options": { "region": "<region of the storage bucket>" }, "credentials": { "key": "<access key ID for accessing the storage bucket>", "secretKey": "<secret access key for accessing the storage bucket>" } } }, "roomState": { "messageInterval": 5, "sendPeerList": false, "stopRoomStateOnJoin": true, "enabled": false } }, "destinations": { "rtmpDestinations": { "<rtmp destination name>": { "name": "<rtmp destination name>", "width": 1080, "height": 1920, "maxDuration": 1800, "rtmpUrls": ["<rtmp URL>", "<rtmp URL>"], "recordingEnabled": true } }, "hlsDestinations": { "<hlsdestination name>": { "name": "<hls destination name>", "maxDuration": 28800, "layers": [ { "width": 1080, "height": 720, "videoBitrate": 1100, "audioBitrate": 32 }, { "width": 720, "height": 720, "videoBitrate": 600 } ], "playlistType": "event", "numPlaylistSegments": 12, "videoFrameRate": 25, "enableMetadataInsertion": true, "enableStaticUrl": true, "recording": { "hlsVod": true, "singleFilePerLayer": true, "enableZipUpload": false, "layers": [ { "width": 720, "height": 1920, "videoBitrate": 2000, "audioBitrate": 64 } ], "thumbnails": { "enabled": true, "width": 720, "height": 1920, "offsets": [2], "fps": 60 }, "presignDuration": 604800 } } }, "transcriptions": { "<transcription destination name>": { "name": "<destination name>", "role": "host", "modes": ["recorded", "live"], "outputModes": [ "txt", "srt", "json" ], "customVocabulary": ["100ms", "WebSDK", "Flutter", "Sundar", "Pichai", "DALL-E"], "summary": { "enabled": true, "context": "this is a meeting between 100ms SDK team and a user representative", "temperature": 0.5, "sections": [ { "title": "Agenda", "format": "bullets" }, { "title": "Key Points", "format": "bullets" }, { "title": "Action Items", "format": "bullets" }, { "title": "Short Summary", "format": "paragraph" } ] } } } } }'
RESPONSE
Status: 200 OK
{ "id": "6324661c4da877930beaecaa", "name": "new-template-1663329820", "customerId": "627cda54ff688c037a39291b", "roles": { "guest": { "name": "guest", "publishParams": { "allowed": ["audio", "video", "screen"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 300, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 }, "simulcast": { "video": { "layers": [ { "rid": "f", "scaleResolutionDownBy": 1, "maxBitrate": 700, "maxFramerate": 25 }, { "rid": "h", "scaleResolutionDownBy": 2, "maxBitrate": 350, "maxFramerate": 25 }, { "rid": "q", "scaleResolutionDownBy": 4, "maxBitrate": 100, "maxFramerate": 25 } ] }, "screen": {} } }, "subscribeParams": { "subscribeToRoles": ["host", "guest"], "maxSubsBitRate": 3200, "subscribeDegradation": { "packetLossThreshold": 25, "degradeGracePeriodSeconds": 1, "recoverGracePeriodSeconds": 4 } }, "permissions": { "rtmpStreaming": true, "hlsStreaming": true, "browserRecording": true, "sendRoomState": false, "pollRead": true, "pollWrite": true }, "priority": 1, "maxPeerCount": 0 }, "host": { "name": "host", "publishParams": { "allowed": ["audio", "video", "screen"], "audio": { "bitRate": 32, "codec": "opus" }, "video": { "bitRate": 300, "codec": "vp8", "frameRate": 30, "width": 480, "height": 360 }, "screen": { "codec": "vp8", "frameRate": 10, "width": 1920, "height": 1080 }, "simulcast": { "video": { "layers": [ { "rid": "f", "scaleResolutionDownBy": 1, "maxBitrate": 700, "maxFramerate": 25 }, { "rid": "h", "scaleResolutionDownBy": 2, "maxBitrate": 350, "maxFramerate": 25 }, { "rid": "q", "scaleResolutionDownBy": 4, "maxBitrate": 100, "maxFramerate": 25 } ] }, "screen": {} } }, "subscribeParams": { "subscribeToRoles": ["guest", "host"], "maxSubsBitRate": 3200, "subscribeDegradation": { "packetLossThreshold": 25, "degradeGracePeriodSeconds": 1, "recoverGracePeriodSeconds": 4 } }, "permissions": { "endRoom": true, "removeOthers": true, "mute": true, "unmute": true, "changeRole": true, "rtmpStreaming": true, "hlsStreaming": true, "browserRecording": true, "sendRoomState": false, "pollRead": true, "pollWrite": true }, "priority": 1, "maxPeerCount": 0 } }, "settings": { "region": "in", "recording": { "upload": { "location": "<Name of the storage bucket>", "type": "<upload type: Supported are s3, gs, oss>", "prefix": "<Upload prefix path>", "credentials": { "key": "<access key ID for accessing the storage bucket>", "secretKey": "<secret access key for accessing the storage bucket>" }, "options": { "region": "<region of the storage bucket>" } } }, "roomState": { "messageInterval": 5, "sendPeerList": false, "stopRoomStateOnJoin": true, "enabled": false }, "retry": {} }, "destinations": { "rtmpDestinations": { "<destination name>": { "name": "<destination name>", "width": 1080, "height": 1920, "maxDuration": 1800, "rtmpUrls": ["url", "ashdas", "ddsfsdf"], "recordingEnabled": true } }, "hlsDestinations": { "<destination name>": { "name": "<destination name>", "maxDuration": 28800, "layers": [ { "width": 1080, "height": 720, "videoBitrate": 1100, "audioBitrate": 32 }, { "width": 720, "height": 720, "videoBitrate": 600 } ], "playlistType": "event", "numPlaylistSegments": 12, "videoFrameRate": 25, "enableMetadataInsertion": true, "enableStaticUrl": true, "recording": { "hlsVod": true, "singleFilePerLayer": true, "enableZipUpload": false, "layers": [ { "width": 720, "height": 1920, "videoBitrate": 2000, "audioBitrate": 64 } ], "thumbnails": { "enabled": true, "width": 720, "height": 1920, "offsets": [2], "fps": 60 }, "presignDuration": 604800 } } }, "transcriptions": { "<destination name>": { "name": "<destination name>", "role": "host", "modes": ["recorded", "live"], "outputModes": ["txt", "srt", "json"], "customVocabulary": ["100ms", "WebSDK", "Flutter", "Sundar", "Pichai", "DALL-E"], "summary": { "enabled": true, "context": "this is a meeting between 100ms SDK team and a user representative", "temperature": 0.5, "sections": [ { "title": "Agenda", "format": "bullets" }, { "title": "Key Points", "format": "bullets" }, { "title": "Action Items", "format": "bullets" }, { "title": "Short Summary", "format": "paragraph" } ] } } } }, "createdAt": "2022-09-16T12:03:40.068Z", "updatedAt": "2022-09-16T12:03:40.068Z", "_id": "6324661c4da877930beaecaa", "customer": "627cda54ff688c037a39291b" }

Main arguments

NameTypeDescriptionRequired
name
stringA unique name you can assign to 100ms templates. Accepted characters are a-z, A-Z, 0-9, space, hyphen -, dot ., underscore _ and colon :. If not provided, this is generated automatically.

Notes:
If create template is called with an existing template name, then that template will be overwritten.
No
roles
objectMap of {roleName:roleObject}. Some sane defaults are set for values that are not provided in the roles object.No
settings
objectGlobal settings for this template.No
destinations
objectObject of type destinations. This object contains information for enabling/configuring features like rtmpDestinations, hlsDestinations, & transcriptionsNo

roles object

NameTypeDescriptionRequired
namestringAlias for the role associated with a particular template.No
publishParamsobjectPublish parameters for this role.

Object of type publishParams with the collection of objects such as allowed, audio, video, screen, etc
No
subscribeParamsobjectSubscribe parameters for this role.

Object of type subscribeParams with a mix of arguments and objects like subscribeToRoles, maxSubsBitRate, & subscribeDegradation
No
permissionsobjectPermissions for this role.

Object of type permission with collection of objects like browserRecordings, rtmpDestinations, & hlsDestinations.
No
priorityintPriority of the role for subscribing/publishing.

Priority will determine the order in which the roles will be degraded.

Allowed values: 1 to 5.

  • 1: highest priority.
  • 5: lowest priority.

No
maxPeerCountintThe number of peers allowed for a particular role in a session.

  • 0: unlimited (default)
  • n: "n" number of peers are allowed to join with that role.
  • -1: no peer will be allowed to join with that role.
No

publishParams object

NameTypeDescriptionRequired
allowedarrayAllowed tracks. Subarray of [audio, video, screen, simulcast].No
audioobjectAudio publish parameters.No
videoobjectVideo publish parameters.No
screenobjectScreenshare publish parameters.No

audio object

NameTypeDescriptionDefaultRequired
bitRateintAudio Max bitrate of audio track in kbps.
Range: 16-128
32No
codecstringCodec for the audio track.
Options: [opus]
opusNo

video object

NameTypeDescriptionDefaultRequired
bitRateintMax bitrate of video track in kbps.
Range: 30-2000
256No
codecstringCodec for the video track.
Options: [vp8]
vp8No
frameRateintMax number of video frames per second.
Range: 1-30
25No
heightintHeight of the video track.
Range: 50-1080
180No
widthintWidth of the video track.
Range: 50-1920
320No

screen object

NameTypeDescriptionDefaultRequired
bitRateintMax bitrate of screen track in kbps.
Range: >=500
1024No
codecstringCodec for the screen track.
Options: [vp8]
vp8No
frameRateintMax number of screen frames per second
Range: 1-30
10No
heightintHeight of the screen track.
Range: 270-1080
720No
widthintWidth of the screen track.
Range: 480-1920
1280No

simulcast object

NameTypeDescriptionRequired
layersobjectObject of type layers. Use this to configure various dimensions to be supported for simulcast.
The max length of this array can be 3.
Yes
simulcast - layer object
NameTypeDescriptionRequired
maxBitrateintSpecifies the maximum number of kilobits per second to allow for encoding.
It should be in the range [0, 2e3] (max is 2 Mbps)—defaults to 0.
No
maxFramerateintSpecifies the maximum number of frames per second to allow for encoding.
It should be in the range [1, 30].
Yes
scaleResolutionDownBylong integerSpecifies a factor to reduce the size of a video track during encoding.
It should be in the range [1.0, 12.0].

The value should always be strictly greater than the previous value (if it exists) in the layers array.
Yes
ridstringSpecifies an "RTP stream ID" to be sent using the RID header extension.
Can be one of f, h, q.

The value should always be strictly smaller than the value of the previous (if it exists) in the layers array (ordered using rule f > h > q ).
No value duplicates can exist in any two items in the layers array.

The first rid should always be f with scaleDownByResolution=1.0.
Yes

subscribeParams object

NameTypeDescriptionRequired
maxSubsBitRateintMaximum bitrate (in kbps) that can subscribed.No
subscribeToRolesarrayList of roles which can be subscribed to.No
subscribeDegradationobjectSubscribe degradation parameters (adding this enables screen simulcast).No

subscribeDegradation object

NameTypeDescriptionDefaultRequired
packetLossThresholdintThreshold for packet loss.
Range: 1-100
50No
degradeGracePeriodSecondsintDegrade grace period (in seconds).
Range: 1-10
1No
recoverGracePeriodSecondsintRecover grace period (in seconds).
Range: 1-10
4No

permissions object

NameTypeDescriptionRequiredDefault
endRoombooleanPermission to end room for all.Nofalse
removeOthersbooleanPermission to remove others from the room.Nofalse
mutebooleanPermission to request others to mute them.Nofalse
unmutebooleanPermission to request others to unmute them.Nofalse
changeRolebooleanPermission to request others to change their role.Nofalse
sendRoomStatebooleanPermission to receive room state like peer-count and peer-listNofalse
pollReadbooleanPermission whether poll/quiz information can be read and responses can be made to a poll/quizNofalse
pollWritebooleanPermission whether poll/quiz information can be modified. PollWrite is a superset of pollRead and enables all pollRead functionalities.Nofalse
browserRecordingbooleanPermission to start/stop browser (beam) recording.

This is also required to start/stop RTMP + browser recording in conjunction with rtmpStreaming permissions.
Notrue
rtmpStreamingbooleanPermission to start/stop RTMP streaming.

This is also required to start/stop RTMP + browser recording in conjunction with browserRecording permissions.
Notrue
hlsStreamingbooleanPermission to start/stop HLS streaming (with or without recording).

This is also required to - pause/unpause HLS recording or insert metadata in HLS stream.
Notrue

settings object

NameTypeDescriptionRequired
regionstringRegion in which the room will be hosted by default. Possible values could be in, us, eu or auto (automatic region selection).No
recordingobjectObject of type recording. This object contains information for enabling recording/setting storage location for recordings.No
roomStateobjectObject of type roomState. This object will help you to define strategy of sending state updates to client SDKs.

Also, enables you to build a "preview" screen which shows the state of the room before joining by providing the list of peers
No

recording object

NameTypeDescriptionRequired
enabled (deprecated)booleanEnable the SFU recording for its rooms. Disabled by default. This field is deprecated, please use new recordings API to configure the composite recordings.No
uploadobjectObject of type upload. This object contains information on recordings storage location. If you want to store recording with 100ms, and not use your own storage (s3/gs/oss), don't add this to the objectNo

upload object

NameTypeDescriptionRequired
typestringUpload destination type. Currently, s3 (AWS), gs (Google Cloud Storage), oss (Alibaba Cloud) are supported.Yes
locationstringName of the storage bucket in which you want to store all recordingsYes
prefixstringUpload prefix pathYes
optionsobjectAdditional configurations of type Options to be used for uploadingNo
credentialsobjectObject of type credentials. This is used to share the credentials to access the storage bucket specified.No

options object

NameTypeDescriptionRequired
regionstringRegion of the account hosting the storage bucket for storing recordings.No

credentials object

NameTypeDescriptionRequired
keystringAccess Key for the account hosting your storage bucket for storing recordingsYes
secretKeystringSecret for the account hosting the storage bucket for storing recordingsYes

roomState object

NameTypeDescriptionRequired
messageIntervalintRoom-state data will be sent over a regular interval of these many seconds.

Consequently, the room state displayed on the preview screen will refresh accordingly.

This value must be a multiple of 5, between 5 and 3600 seconds, both inclusive.
No
sendPeerListbooleanEnabling this will send peer-list info of the room. If disabled, only the peer count is sent.No
enabledbooleanThis is the list of all the roles which will get the room-state data. You can also individually toggle these settings in the Roles tab under the Permissions section.No

destinations object

NameTypeDescriptionRequired
browserRecordings (deprecated)objectObject of type browserRecordings. This can be used to record your sessions to a file, for subsequent access.No
rtmpDestinationsobjectObject of type rtmpDestinations. This can be used to live stream your video conferencing apps to platforms like YouTube, Twitch, Facebook, MUX, etc.No
hlsDestinationsobjectObject of type hlsDestinations. This can be used to configure arguments for your HLS live streaming.No
transcriptionsobjectObject of type transcriptions. This can be used to configure transcriptions.No

browserRecordings object (Deprecated)

NameTypeDescriptionRequired
namestringThe name you can assign to identify the browser recordingYes
widthintIndicates the width of the screen to be recorded in pixels. For example, 1280 pixelsNo
heightintIndicates the height of the screen to be recorded in pixels. For example, 720 pixelsNo
maxDurationintSets the maximum duration, in seconds, of the recording. For example, 1800 seconds(30 minutes)No
thumbnailsobjectObject of type thumbnails. This can be used to configure thumbnail's dimensionNo
presignDurationintIndicates the expiry of the pre-signed URLs—the duration for which the pre-signed URL should be signedNo
rolestringIndicates the role use to start browser recordingYes
autoStartbooleanIndicates whether recordings should automatically start on room join for this destinationNo
autoStopTimeoutintMaximum duration to wait before automatically stopping recording after all peers leaveNo

rtmpDestinations object

NameTypeDescriptionRequired
namestringThe name you can assign to identify the RTMP destinationYes
widthintIndicates the width of the screen to be recorded in pixels. For example, 1280 pixelsNo
heightintIndicates the height of the screen to be recorded in pixels. For example, 720 pixelsNo
maxDurationintSet maximum duration for RTMP stream, in seconds. For example, 1800 seconds(30 minutes)No
rtmpUrlsobjectObject of type rtmpUrls. This can be used to configure the RTMP URLs(max 3) you wish to broadcast the stream to.No
recordingEnabledbooleanIf recording is required this can be set as true. This value has no effect on streaming.No
autoStopTimeoutintMaximum duration to wait before automatically stopping RTMP after all peers leaveNo

hlsDestinations object

NameTypeDescriptionRequired
namestringThe name you can assign to identify the HLS destinationYes
maxDurationintSets maximum duration for the live stream, in seconds. For example, 1800 seconds(30 minutes)No
layersobjectObject of type layers. This can be used to configure the various dimensions to be supported for HLS streaming. The layers are expected to be in descending order of resolution and video bitrateNo
playlistTypestringIndicates the type of playlist. Can be of type event or live.No
numPlaylistSegmentsintIndicates the number of media segments in the playlist. Applicable only for live playlistType. Each segment is 2 seconds. Min/max/default = 3/150/5.No
videoFrameRateintSet this argument to configure the frames per second (or FPS) for your stream. For example, 25No
enableMetadataInsertionbooleanSet this to true to enable metadata insertion along with the stream.No
enableStaticUrlbooleanIf recording is required this can be set as true. This value has no effect on streaming.No
recordingobjectObject of type recording. This can be used to enable HLS recording and configure the layers, thumbnails, etc.No
autoStopTimeoutintMaximum duration to wait before automatically stopping HLS after all peers leaveNo

HLS - recording object

NameTypeDescriptionRequired
hlsVodbooleanSet this to true to enabled Video on Demand. Output will be a HLS VOD asset file of m3u8 format with all the chunks.No
singleFilePerLayerbooleanSet this to true if HLS recording should be available as separate files for various dimensions supported. Output will be Individual mp4 file per HLS layer.No
enableZipUploadbooleanBy default, the value is 'false'. You can set this to 'true' to enable zipped upload of the HLS VOD asset if the recording storage is your personal storage bucket and upload object is configured. Setting it to 'true' with the configured storage as 100ms will give an error.No
layersobjectObject of type layers. This can be used to configure the various dimensions to be supported for HLS recording - both hlsVod and singleFilePerLayer. recording.layers should be subset of hlsDestinations.layers and has the same validations as hlsDestinations.layers. When not specified, recordings will be generated for all hlsDestinations.layersNo
thumbnailsobjectObject of type thumbnails. This can be used to configure thumbnail's dimension.No
presignDurationintIndicates the expiry of the pre-signed URLs—the duration for which the pre-signed URL should be signed.No

HLS/ HLS Recording - Layers

Minimum between width and height should be in range [144, 1080] and Maximum between width and height should be in range [192, 1920].

NameTypeDescriptionRequired
widthintIndicates the width of the screen to be recorded in pixels (Must be an even number). For example, 1280No
heightintIndicates the height of the screen to be recorded in pixels (Must be an even number). For example, 720No
videoBitrateintBitrate of video track in kbps.No
audioBitrateintBitrate of audio track in kbps.No

transcriptions object

NameTypeDescriptionRequired
namestringThe name you can assign to identify transcription destination.Yes
modesarrayArray of modes for transcription. Valid values: [ recorded, live ]
(recorded: Transcribe recording post call completion, live: Closed caption for live stream viewers)
No
rolestringIndicates the role used to transcribe. Roles which are subscribed by the given role will be transcribed.Yes
outputModesarrayArray of transcript output modes, valid for recorded mode. Valid values: [ txt, srt, json ] (txt: Plain text, srt: SubRip text, json: Granular timestamped words and sentences)No
customVocabularyarrayArray of words that might be spoken during the call. This can consist of non-dictionary words like names, slang, abbreviations and domain specific words.No
summaryobjectObject of type summary. This can be used to enable and configure summary, valid for recorded mode.No

transcriptions - summary object

NameTypeDescriptionRequired
enablebooleanSet this to true to enable summary.No
contextstringProvide context of the meetings to help AI get a holistic understanding about the call to generate a better summary. (limit: 300 characters)No
temperaturefloatTemperature determines creativity. Higher values makes AI be more creative, lower values makes it more deterministic and predictable. (default: 0.5, accepted range : 0.1 - 1.0)No
sectionsarraySections has list of objects. This refers to sections in summary like Agenda, Short Summary, Questions raised by participants. (max count: 6)No

transcriptions - summary - sections object

NameTypeDescriptionRequired
titlestringTitle of the section Agenda, Short Summary, Follow Up Action Items, Short Summary. (limit: 100 characters)Yes
formatstringFormat of the section. Valid values: [bullets, paragraph]Yes

Have a suggestion? Recommend changes ->

Run in postman

Was this helpful?

1234