Twilio Video API is a powerful tool that enables developers to integrate high-quality video calling and conferencing capabilities into their applications. With this API, users can easily create and manage video chat sessions, enabling real-time communication among multiple participants. The API provides a range of features, including video and audio streaming, screen sharing, and recording capabilities, all of which can be customized to suit specific use cases.
components:
schemas:
video.v1.composition:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Composition resource.
status:
type: string
$ref: '#/components/schemas/composition_enum_status'
nullable: true
description: >-
The status of the composition. Can be: `enqueued`, `processing`,
`completed`, `deleted` or `failed`. `enqueued` is the initial state
and indicates that the composition request has been received and is
scheduled for processing; `processing` indicates the composition is
being processed; `completed` indicates the composition has been
completed and is available for download; `deleted` means the
composition media has been deleted from the system, but its metadata
is still available for 30 days; `failed` indicates the composition
failed to execute the media processing task.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_completed:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the composition's media processing
task finished, specified in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_deleted:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the composition generated media was
deleted, specified in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601) format.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CJ[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the Composition
resource.
room_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RM[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the Group Room that generated the audio and video tracks
used in the composition. All media sources included in a composition
must belong to the same Group Room.
audio_sources:
type: array
items:
type: string
nullable: true
description: >-
The array of track names to include in the composition. The
composition includes all audio sources specified in `audio_sources`
except those specified in `audio_sources_excluded`. The track names
in this property can include an asterisk as a wild card character,
which matches zero or more characters in a track name. For example,
`student*` includes tracks named `student` as well as `studentTeam`.
x-twilio:
pii:
handling: standard
deleteSla: 30
audio_sources_excluded:
type: array
items:
type: string
nullable: true
description: >-
The array of track names to exclude from the composition. The
composition includes all audio sources specified in `audio_sources`
except for those specified in `audio_sources_excluded`. The track
names in this property can include an asterisk as a wild card
character, which matches zero or more characters in a track name.
For example, `student*` excludes `student` as well as `studentTeam`.
This parameter can also be empty.
x-twilio:
pii:
handling: standard
deleteSla: 30
video_layout:
nullable: true
description: >-
An object that describes the video layout of the composition in
terms of regions. See [Specifying Video
Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts)
for more info.
x-twilio:
pii:
handling: standard
deleteSla: 30
resolution:
type: string
nullable: true
description: >-
The dimensions of the video image in pixels expressed as columns
(width) and rows (height). The string's format is
`{width}x{height}`, such as `640x480`.
trim:
type: boolean
nullable: true
description: >-
Whether to remove intervals with no media, as specified in the POST
request that created the composition. Compositions with `trim`
enabled are shorter when the Room is created and no Participant
joins for a while as well as if all the Participants leave the room
and join later, because those gaps will be removed. See [Specifying
Video
Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts)
for more info.
format:
type: string
$ref: '#/components/schemas/composition_enum_format'
nullable: true
description: >-
The container format of the composition's media files as specified
in the POST request that created the Composition resource. See [POST
Parameters](https://www.twilio.com/docs/video/api/compositions-resource#http-post-parameters)
for more information.
bitrate:
type: integer
nullable: true
description: The average bit rate of the composition's media.
size:
type: integer
format: int64
nullable: true
description: The size of the composed media file in bytes.
duration:
type: integer
nullable: true
description: The duration of the composition's media file in seconds.
media_external_location:
type: string
format: uri
nullable: true
description: >-
The URL of the media file associated with the composition when
stored externally. See [External S3
Compositions](/docs/video/api/external-s3-compositions) for more
details.
status_callback:
type: string
format: uri
nullable: true
description: >-
The URL called using the `status_callback_method` to send status
information on every composition event.
status_callback_method:
type: string
format: http-method
enum:
- HEAD
- GET
- POST
- PATCH
- PUT
- DELETE
nullable: true
description: >-
The HTTP method used to call `status_callback`. Can be: `POST` or
`GET`, defaults to `POST`.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
links:
type: object
format: uri-map
nullable: true
description: The URL of the media file associated with the composition.
composition_enum_status:
type: string
enum:
- enqueued
- processing
- completed
- deleted
- failed
composition_enum_format:
type: string
enum:
- mp4
- webm
video.v1.composition_hook:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the CompositionHook resource.
friendly_name:
type: string
nullable: true
description: >-
The string that you assigned to describe the resource. Can be up to
100 characters long and must be unique within the account.
enabled:
type: boolean
nullable: true
description: >-
Whether the CompositionHook is active. When `true`, the
CompositionHook is triggered for every completed Group Room on the
account. When `false`, the CompositionHook is never triggered.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
format.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^HK[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the CompositionHook
resource.
audio_sources:
type: array
items:
type: string
nullable: true
description: >-
The array of track names to include in the compositions created by
the composition hook. A composition triggered by the composition
hook includes all audio sources specified in `audio_sources` except
those specified in `audio_sources_excluded`. The track names in this
property can include an asterisk as a wild card character, which
matches zero or more characters in a track name. For example,
`student*` includes tracks named `student` as well as `studentTeam`.
Please, be aware that either video_layout or audio_sources have to
be provided to get a valid creation request
x-twilio:
pii:
handling: standard
deleteSla: 30
audio_sources_excluded:
type: array
items:
type: string
nullable: true
description: >-
The array of track names to exclude from the compositions created by
the composition hook. A composition triggered by the composition
hook includes all audio sources specified in `audio_sources` except
for those specified in `audio_sources_excluded`. The track names in
this property can include an asterisk as a wild card character,
which matches zero or more characters in a track name. For example,
`student*` excludes `student` as well as `studentTeam`. This
parameter can also be empty.
x-twilio:
pii:
handling: standard
deleteSla: 30
video_layout:
nullable: true
description: >-
A JSON object that describes the video layout of the composition in
terms of regions as specified in the HTTP POST request that created
the CompositionHook resource. See [POST
Parameters](https://www.twilio.com/docs/video/api/compositions-resource#http-post-parameters)
for more information. Please, be aware that either video_layout or
audio_sources have to be provided to get a valid creation request
x-twilio:
pii:
handling: standard
deleteSla: 30
resolution:
type: string
nullable: true
description: >-
The dimensions of the video image in pixels expressed as columns
(width) and rows (height). The string's format is
`{width}x{height}`, such as `640x480`.
trim:
type: boolean
nullable: true
description: >-
Whether intervals with no media are clipped, as specified in the
POST request that created the CompositionHook resource. Compositions
with `trim` enabled are shorter when the Room is created and no
Participant joins for a while as well as if all the Participants
leave the room and join later, because those gaps will be removed.
See [Specifying Video
Layouts](https://www.twilio.com/docs/video/api/compositions-resource#specifying-video-layouts)
for more info.
format:
type: string
$ref: '#/components/schemas/composition_hook_enum_format'
nullable: true
description: >-
The container format of the media files used by the compositions
created by the composition hook. If `mp4` or `webm`, `audio_sources`
must have one or more tracks and/or a `video_layout` element must
contain a valid `video_sources` list, otherwise an error occurs.
status_callback:
type: string
format: uri
nullable: true
description: >-
The URL we call using the `status_callback_method` to send status
information to your application.
status_callback_method:
type: string
format: http-method
enum:
- HEAD
- GET
- POST
- PATCH
- PUT
- DELETE
nullable: true
description: >-
The HTTP method we should use to call `status_callback`. Can be
`POST` or `GET` and defaults to `POST`.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
composition_hook_enum_format:
type: string
enum:
- mp4
- webm
video.v1.composition_settings:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the CompositionSettings resource.
friendly_name:
type: string
nullable: true
description: >-
The string that you assigned to describe the resource and that will
be shown in the console
aws_credentials_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: The SID of the stored Credential resource.
aws_s3_url:
type: string
format: uri
nullable: true
description: >-
The URL of the AWS S3 bucket where the compositions are stored. We
only support DNS-compliant URLs like
`https://documentation-example-twilio-bucket/compositions`, where
`compositions` is the path in which you want the compositions to be
stored. This URL accepts only URI-valid characters, as described in
the <a href='https://tools.ietf.org/html/rfc3986#section-2'>RFC
3986</a>.
aws_storage_enabled:
type: boolean
nullable: true
description: >-
Whether all compositions are written to the `aws_s3_url`. When
`false`, all compositions are stored in our cloud.
encryption_key_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: The SID of the Public Key resource used for encryption.
encryption_enabled:
type: boolean
nullable: true
description: >-
Whether all compositions are stored in an encrypted form. The
default is `false`.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
video.v1.recording:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Recording resource.
status:
type: string
$ref: '#/components/schemas/recording_enum_status'
nullable: true
description: >-
The status of the recording. Can be: `processing`, `completed`, or
`deleted`. `processing` indicates the recording is still being
captured; `completed` indicates the recording has been captured and
is now available for download. `deleted` means the recording media
has been deleted from the system, but its metadata is still
available.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RT[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the Recording
resource.
source_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^[a-zA-Z]{2}[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the recording source. For a Room Recording, this value is
a `track_sid`.
size:
type: integer
format: int64
nullable: true
description: The size of the recorded track, in bytes.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
type:
type: string
$ref: '#/components/schemas/recording_enum_type'
nullable: true
description: 'The recording''s media type. Can be: `audio` or `video`.'
duration:
type: integer
nullable: true
description: >-
The duration of the recording in seconds rounded to the nearest
second. Sub-second tracks have a `Duration` property of 1 second
container_format:
type: string
$ref: '#/components/schemas/recording_enum_format'
nullable: true
description: >-
The file format for the recording. Can be: `mka` or `mkv`. Video
Room recordings are captured in [Matroska container
format](https://matroska.org/), `mka` is for audio files and `mkv`
for video files.
codec:
type: string
$ref: '#/components/schemas/recording_enum_codec'
nullable: true
description: >-
The codec used to encode the track. Can be: `VP8`, `H264`, `OPUS`,
and `PCMU`.
grouping_sids:
nullable: true
description: >-
A list of SIDs related to the recording. Includes the `room_sid` and
`participant_sid`.
track_name:
type: string
nullable: true
description: >-
The name that was given to the source track of the recording. If no
name is given, the `source_sid` is used.
x-twilio:
pii:
handling: standard
deleteSla: 30
offset:
type: integer
format: int64
nullable: true
description: >-
The time in milliseconds elapsed between an arbitrary point in time,
common to all group rooms, and the moment when the source room of
this track started. This information provides a synchronization
mechanism for recordings belonging to the same room.
media_external_location:
type: string
format: uri
nullable: true
description: >-
The URL of the media file associated with the recording when stored
externally. See [External S3
Recordings](/docs/video/api/external-s3-recordings) for more
details.
status_callback:
type: string
format: uri
nullable: true
description: >-
The URL called using the `status_callback_method` to send status
information on every recording event.
status_callback_method:
type: string
format: http-method
enum:
- HEAD
- GET
- POST
- PATCH
- PUT
- DELETE
nullable: true
description: >-
The HTTP method used to call `status_callback`. Can be: `POST` or
`GET`, defaults to `POST`.
links:
type: object
format: uri-map
nullable: true
description: The URLs of related resources.
recording_enum_status:
type: string
enum:
- processing
- completed
- deleted
- failed
recording_enum_type:
type: string
enum:
- audio
- video
- data
recording_enum_format:
type: string
enum:
- mka
- mkv
recording_enum_codec:
type: string
enum:
- VP8
- H264
- OPUS
- PCMU
video.v1.recording_settings:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the RecordingSettings resource.
friendly_name:
type: string
nullable: true
description: >-
The string that you assigned to describe the resource and show the
user in the console
aws_credentials_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: The SID of the stored Credential resource.
aws_s3_url:
type: string
format: uri
nullable: true
description: >-
The URL of the AWS S3 bucket where the recordings are stored. We
only support DNS-compliant URLs like
`https://documentation-example-twilio-bucket/recordings`, where
`recordings` is the path in which you want the recordings to be
stored. This URL accepts only URI-valid characters, as described in
the <a href='https://tools.ietf.org/html/rfc3986#section-2'>RFC
3986</a>.
aws_storage_enabled:
type: boolean
nullable: true
description: >-
Whether all recordings are written to the `aws_s3_url`. When
`false`, all recordings are stored in our cloud.
encryption_key_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: The SID of the Public Key resource used for encryption.
encryption_enabled:
type: boolean
nullable: true
description: >-
Whether all recordings are stored in an encrypted form. The default
is `false`.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
video.v1.room:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RM[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Room resource.
status:
type: string
$ref: '#/components/schemas/room_enum_room_status'
nullable: true
description: >-
The status of the room. Can be: `in-progress`, `failed`, or
`completed`.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
format.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Room resource.
enable_turn:
type: boolean
nullable: true
description: Deprecated, now always considered to be true.
unique_name:
type: string
nullable: true
description: >-
An application-defined string that uniquely identifies the resource.
It can be used as a `room_sid` in place of the resource's `sid` in
the URL to address the resource, assuming it does not contain any
[reserved
characters](https://tools.ietf.org/html/rfc3986#section-2.2) that
would need to be URL encoded. This value is unique for `in-progress`
rooms. SDK clients can use this name to connect to the room. REST
API clients can use this name in place of the Room SID to interact
with the room as long as the room is `in-progress`.
status_callback:
type: string
format: uri
nullable: true
description: >-
The URL we call using the `status_callback_method` to send status
information to your application on every room event. See [Status
Callbacks](https://www.twilio.com/docs/video/api/status-callbacks)
for more info.
status_callback_method:
type: string
format: http-method
enum:
- HEAD
- GET
- POST
- PATCH
- PUT
- DELETE
nullable: true
description: >-
The HTTP method we use to call `status_callback`. Can be `POST` or
`GET` and defaults to `POST`.
end_time:
type: string
format: date-time
nullable: true
description: >-
The UTC end time of the room in [ISO
8601](https://en.wikipedia.org/wiki/ISO_8601#UTC) format.
duration:
type: integer
nullable: true
description: The duration of the room in seconds.
type:
type: string
$ref: '#/components/schemas/room_enum_room_type'
nullable: true
description: >-
The type of room. Can be: `go`, `peer-to-peer`, `group-small`, or
`group`. The default value is `group`.
max_participants:
type: integer
nullable: true
description: 'The maximum number of concurrent Participants allowed in the room. '
max_participant_duration:
type: integer
nullable: true
description: >-
The maximum number of seconds a Participant can be connected to the
room. The maximum possible value is 86400 seconds (24 hours). The
default is 14400 seconds (4 hours).
max_concurrent_published_tracks:
type: integer
nullable: true
description: >-
The maximum number of published audio, video, and data tracks all
participants combined are allowed to publish in the room at the same
time. Check [Programmable Video
Limits](https://www.twilio.com/docs/video/programmable-video-limits)
for more details. If it is set to 0 it means unconstrained.
record_participants_on_connect:
type: boolean
nullable: true
description: >-
Whether to start recording when Participants connect. ***This
feature is not available in `peer-to-peer` rooms.***
video_codecs:
type: array
items:
type: string
$ref: '#/components/schemas/room_enum_video_codec'
nullable: true
description: >-
An array of the video codecs that are supported when publishing a
track in the room. Can be: `VP8` and `H264`. ***This feature is
not available in `peer-to-peer` rooms***
media_region:
type: string
nullable: true
description: >-
The region for the media server in Group Rooms. Can be: one of the
[available Media
Regions](https://www.twilio.com/docs/video/ip-addresses#media-servers).
***This feature is not available in `peer-to-peer` rooms.***
audio_only:
type: boolean
nullable: true
description: >-
When set to true, indicates that the participants in the room will
only publish audio. No video tracks will be allowed. Group rooms
only.
empty_room_timeout:
type: integer
nullable: true
description: >-
Specifies how long (in minutes) a room will remain active after last
participant leaves. Can be configured when creating a room via REST
API. For Ad-Hoc rooms this value cannot be changed.
unused_room_timeout:
type: integer
nullable: true
description: >-
Specifies how long (in minutes) a room will remain active if no one
joins. Can be configured when creating a room via REST API. For
Ad-Hoc rooms this value cannot be changed.
large_room:
type: boolean
nullable: true
description: Indicates if this is a large room.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
links:
type: object
format: uri-map
nullable: true
description: The URLs of related resources.
room_enum_room_status:
type: string
enum:
- in-progress
- completed
- failed
room_enum_room_type:
type: string
enum:
- go
- peer-to-peer
- group
- group-small
room_enum_video_codec:
type: string
enum:
- VP8
- H264
video.v1.room.room_participant:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^PA[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the RoomParticipant
resource.
room_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^RM[0-9a-fA-F]{32}$
nullable: true
description: The SID of the participant's room.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
# --- truncated at 32 KB (127 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/video-openapi-original.yml