Video

Get a video

GET
https://peertube2.cpy.re/api/v1/videos/{id}

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

x-peertube-video-passwordstringheader

Required on password protected video

Response

200OKVideo & object

successful operation

Response fields application/json
idid

object id for the video

Show child attributes
id>= 1
Example
42
uuidUUIDv4

universal identifier for the video, that can be used across instances

Show child attributes
UUIDv4<uuid>
Example
9c9de5e8-0a1e-484a-b099-e80766180a6d
shortUUIDshortUUID
Show child attributes

translation of a uuid v4 with a bigger alphabet to have a shorter uuid

shortUUID
Example
2y84q2MQUMWPbiEcxNXMgC
isLiveboolean
liveSchedulesArray<LiveSchedule>
Show child attributes
startAtstring<date-time>

Date when the stream is scheduled to air at

createdAtstring<date-time>

time at which the video object was first drafted

Example
2017-10-01T10:52:46.396Z
publishedAtstring<date-time>

time at which the video was marked as ready for playback (with restrictions depending on privacy). Usually set after a state evolution.

Example
2018-10-01T10:52:46.396Z
updatedAtstring<date-time>

last time the video's metadata was modified

Example
2021-05-04T08:01:01.502Z
originallyPublishedAtstring<date-time> | null

used to represent a date of first publication, prior to the practical publication date of publishedAt

Example
2010-10-01T10:52:46.396Z
categoryVideoConstantNumber-Category

category in which the video is classified

Show child attributes
idVideoCategorySet

category id of the video (see /videos/categories)

Example
15
labelstring
Example
Science & Technology
licenceVideoConstantNumber-Licence

licence under which the video is distributed

Show child attributes
idVideoLicenceSet

licence id of the video (see /videos/licences)

Example
2
labelstring
Example
Attribution - Share Alike
languageVideoConstantString-Language

main language used in the video

Show child attributes
idVideoLanguageSet

language id of the video (see /videos/languages)

Example
en
labelstring
Example
English
privacyVideoPrivacyConstant

privacy policy used to distribute the video

Show child attributes
idVideoPrivacySet12345

privacy id of the video (see /videos/privacies)

labelstring
truncatedDescriptionstring | null

truncated description of the video, written in Markdown.

Example
**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
durationinteger<seconds>

duration of the video in seconds

Example
1419
aspectRationumber<float> | null

PeerTube >= 6.1 Aspect ratio of the video stream

Example
1.778
isLocalboolean
namename

title of the video

Example
What is PeerTube?
thumbnailPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

previewPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the video

Show child attributes
fileUrlstring
widthinteger
heightinteger
aspectRatiostring
Example
16:9
embedPathstring
Example
/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
viewsinteger
Example
1337
likesinteger
Example
42
dislikesinteger
Example
7
commentsinteger

PeerTube >= 7.2 Number of comments on the video

nsfwboolean
nsfwFlagsNSFWFlag
Show child attributes

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
NSFWFlag0124
nsfwSummarystring

PeerTube >= 7.2 More information about the sensitive content of the video

aiUsageVideoAIUsageConstant
Show child attributes
idVideoAIUsageSet1234

PeerTube >= 9.0 Use of AI in the video, declared by the video creator:

  • 1 Not specified
  • 2 No AI-generated content: nothing seen or heard in the video has been generated by AI
  • 3 Contains AI-generated content: some parts of the video have been generated by AI
  • 4 AI-generated: the whole video, or most of it, has been generated by AI
labelstring
commercialContentVideoCommercialContentConstant
Show child attributes
idVideoCommercialContentSet123

PeerTube >= 9.0 Commercial content in the video, declared by the video creator:

  • 1 None
  • 2 Promotional content: the creator promotes their own products, services or business
  • 3 Paid partnership: a third party paid, or provided goods or services, in exchange for the promotion
labelstring
recommendationScopeVideoRecommendationScopeConstant
Show child attributes
idVideoRecommendationScopeSet1234

Videos that can be recommended next to a video:

  • 1 All videos
  • 2 Only videos of the platform that owns the reference video (or of the current platform if no video is given)
  • 3 Only videos of the account that owns the reference video
  • 4 Only videos of the channel of the reference video

This is a preference of the video owner: applications displaying recommendations may not apply it

labelstring
waitTranscodingboolean | null
stateVideoStateConstant

represents the internal state of the video processing within the PeerTube instance

Show child attributes
idid123456789101112131415

The video state:

  • 1: Published
  • 2: To transcode
  • 3: To import
  • 4: Waiting for live stream
  • 5: Live ended
  • 6: To move to an external storage (object storage...)
  • 7: Transcoding failed
  • 8: Moving to an external storage failed
  • 9: To edit using studio edition feature
  • 10: To move to the file system
  • 11: Moving to the file system failed
  • 12: Import failed
  • 13: To duplicate, the files of another video are being copied
  • 14: Duplication failed, the files of the other video could not be copied
  • 15: The studio edition of a video saved as a new video failed

Same fields as id

labelstring
scheduledUpdateVideoScheduledUpdate | null
Show child attributes
privacyVideoPrivacySet12345

privacy id of the video (see /videos/privacies)

updateAtstring<date-time>required

When to update the video

blacklistedboolean | null
blacklistedReasonstring | null
accountAccountSummary
Show child attributes
idinteger
namestring
displayNamestring
urlstring<url>
hoststring<hostname>
avatarsArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
channelVideoChannelSummary
Show child attributes
idid>= 1
Example
42

Same fields as id

namestring
displayNamestring
urlstring<url>
hoststring<hostname>
avatarsArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
userHistoryobject | null
Show child attributes
currentTimeinteger
captionLanguagesArray<string>

PeerTube >= 9.0 Languages of the video captions. Only returned by video lists

viewersinteger

If the video is a live, you have the amount of current viewers

descriptionstring | null

full description of the video, written in Markdown.

Example
"**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network,
based on free/libre software!*\r\n\r\n**Animation Produced by:** [LILA](https://libreart.info) - [ZeMarmot Team](https://film.zemarmot.net)\r\n
*Directed by* Aryeom\r\n*Assistant* Jehan\r\n**Licence**: [CC-By-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\r\n\r\n
**Sponsored by** [Framasoft](https://framasoft.org)\r\n\r\n**Music**: [Red Step Forward](http://play.dogmazic.net/song.php?song_id=52491) - CC-By Ken Bushima\r\n\r\n
**Movie Clip**: [Caminades 3: Llamigos](http://www.caminandes.com/) CC-By Blender Institute\r\n\r\n**Video sources**: https://gitlab.gnome.org/Jehan/what-is-peertube/"
supportstring | null

A text tell the audience how to support the video creator

Example
Please support our work on https://soutenir.framasoft.org/en/ <3
channelActor & object
Show child attributes
idid>= 1
Example
42

Same fields as id

urlstring<url>
nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username
Example
chocobozzz
avatarsArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>
updatedAtstring<date-time>
displayNamestring

editable name of the channel, displayed in its representations

Example
Videos of Framasoft
descriptionstring | null
Example
Videos made with <3 by Framasoft
supportstring | null

text shown by default on all videos of this channel, to tell the audience how to support it

Example
Please support our work on https://soutenir.framasoft.org/en/ <3
publicEmailstring<email> | null

Public email visible in podcast RSS feeds

isLocalboolean
updatedAtstring<date-time>
bannersArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
ownerAccountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as id

urlstring<url>
nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username
Example
chocobozzz
avatarsArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>
updatedAtstring<date-time>
userIdid | null

object id for the user tied to this account

Show child attributes
id>= 1
Example
42
displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

videosCountinteger

only included when withStats is true

viewsPerDayArray<object>

only included when withStats is true. Chronologically ordered, spans the whole statsDays range. Each point aggregates viewsGroupInterval worth of views, starting at date

Show child attributes
datestring<date-time>
viewsinteger
viewsGroupIntervalstringdayweekmonth

bucket size of viewsPerDay, only included when withStats is true

totalViewsinteger

lifetime views of all the channel videos, only included when withStats is true

accountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as id

urlstring<url>
nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username
Example
chocobozzz
avatarsArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>
updatedAtstring<date-time>
userIdid | null

object id for the user tied to this account

Show child attributes
id>= 1
Example
42
displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

tagsArray<string>
Example
[
  "flowers",
  "gardening"
]
commentsPolicyVideoCommentsPolicyConstant
Show child attributes
idVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

labelstring
downloadEnabledboolean
inputFileUpdatedAtstring<date-time> | null

Latest input file update. Null if the file has never been replaced since the original upload

trackerUrlsArray<string>

WebTorrent (ws:// or wss://) and BitTorrent (http:// or https://) trackers of the video

Example
[
  "https://peertube2.cpy.re/tracker/announce",
  "wss://peertube2.cpy.re/tracker/socket"
]
filesArray<VideoFile>

Web compatible video files. If Web Video is disabled on the server:

  • field will be empty
  • video files will be found in streamingPlaylists[].files field
Show child attributes
idid>= 1
Example
42

Same fields as id

magnetUristring<uri>

magnet URI allowing to resolve the video via BitTorrent without a metainfo file

resolutionVideoResolutionConstant

resolutions and their labels for the video

Show child attributes
idVideoResolutionSet

Video resolution (0, 240, 360, 720, 1080, 1440 or 2160)

0 is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.

Example
240
labelstring
Example
240p
sizeinteger

Video file size in bytes

torrentUrlstring<url>

Direct URL of the torrent file

torrentDownloadUrlstring<url>

URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)

fileUrlstring<url>

Direct URL of the video

playlistUrlstring<url>

Playlist URL of the file if it is owned by a playlist

fileDownloadUrlstring<url>

URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)

fpsnumber

Frames per second of the video file

widthnumber

PeerTube >= 6.1 Video stream width

heightnumber

PeerTube >= 6.1 Video stream height

metadataUrlstring<url>

URL dereferencing the output of ffprobe on the file

hasAudioboolean

PeerTube >= 6.2 The file container has an audio stream

hasVideoboolean

PeerTube >= 6.2 The file container has a video stream

storageFileStorage01

The file storage type:

  • 0 File system
  • 1 Object storage
streamingPlaylistsArray<VideoStreamingPlaylists>

HLS playlists/manifest files. If HLS is disabled on the server:

  • field will be empty
  • video files will be found in files field
Show child attributes
idid>= 1
Example
42

Same fields as id

typeinteger1

Playlist type:

  • 1: HLS
playlistUrlstring<url>
segmentsSha256Urlstring<url>
filesArray<VideoFile>

Video files associated to this playlist.

The difference with the root files property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)

Show child attributes
idid>= 1
Example
42

Same fields as id

magnetUristring<uri>

magnet URI allowing to resolve the video via BitTorrent without a metainfo file

resolutionVideoResolutionConstant

resolutions and their labels for the video

Show child attributes
idVideoResolutionSet

Video resolution (0, 240, 360, 720, 1080, 1440 or 2160)

0 is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.

Example
240
labelstring
Example
240p
sizeinteger

Video file size in bytes

torrentUrlstring<url>

Direct URL of the torrent file

torrentDownloadUrlstring<url>

URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)

fileUrlstring<url>

Direct URL of the video

playlistUrlstring<url>

Playlist URL of the file if it is owned by a playlist

fileDownloadUrlstring<url>

URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)

fpsnumber

Frames per second of the video file

widthnumber

PeerTube >= 6.1 Video stream width

heightnumber

PeerTube >= 6.1 Video stream height

metadataUrlstring<url>

URL dereferencing the output of ffprobe on the file

hasAudioboolean

PeerTube >= 6.2 The file container has an audio stream

hasVideoboolean

PeerTube >= 6.2 The file container has a video stream

storageFileStorage01

The file storage type:

  • 0 File system
  • 1 Object storage
redundanciesArray<object>
Show child attributes
baseUrlstring<url>
401UnauthorizedServerError

Requires authentication or the video requires a password

Response fields application/json
typestring<uri-reference>

URI identifying the error type. about:blank when the error has no specific type. Otherwise it links to the corresponding section of the Errors documentation; the type name itself is also available in code.

Example
/api-rest-reference.html#section/Errors/video_requires_password
detailstring
Example
Please provide a password to access this password protected video
statusinteger
Example
403
codestring
Example
video_requires_password
403ForbiddenServerError

Invalid authentication or the video requires a password

Response fields application/json
typestring<uri-reference>

URI identifying the error type. about:blank when the error has no specific type. Otherwise it links to the corresponding section of the Errors documentation; the type name itself is also available in code.

Example
/api-rest-reference.html#section/Errors/video_requires_password
detailstring
Example
Please provide a password to access this password protected video
statusinteger
Example
403
codestring
Example
video_requires_password
Docs by Sourcey
↑↓ navigate↵ selectesc close