Video

List recommended videos

GET

https://peertube2.cpy.re/api/v1/recommendations/videos

Return videos recommended next to a reference video (or general recommendations if no reference video is given).

PeerTube decides the recommendation algorithm: it currently lists videos sharing tags with the reference video (excluding videos already watched by the authenticated user), then the latest videos. All returned videos are restricted to the scope, which defaults to the recommendationScope of the reference video.

curl -X GET 'https://peertube2.cpy.re/api/v1/recommendations/videos?count=10'

const response = await fetch('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "isLive": true,
      "liveSchedules": [
        {
          "startAt": "2024-01-15T09:30:00Z"
        }
      ],
      "createdAt": "2017-10-01T10:52:46.396Z",
      "publishedAt": "2018-10-01T10:52:46.396Z",
      "updatedAt": "2021-05-04T08:01:01.502Z",
      "originallyPublishedAt": "2010-10-01T10:52:46.396Z",
      "category": {
        "id": 15,
        "label": "Science & Technology"
      },
      "licence": {
        "id": 2,
        "label": "Attribution - Share Alike"
      },
      "language": {
        "id": "en",
        "label": "English"
      },
      "privacy": {
        "id": 1,
        "label": "string"
      },
      "truncatedDescription": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\r\\n\\r\\n\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\r\\n*A decentralized video hosting network, based on fr...\n",
      "duration": 1419,
      "aspectRatio": 1.778,
      "isLocal": true,
      "name": "What is PeerTube?",
      "thumbnailPath": "string",
      "previewPath": "string",
      "thumbnails": [
        {
          "fileUrl": "string",
          "width": 0,
          "height": 0,
          "aspectRatio": "16:9"
        }
      ],
      "embedPath": "/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee",
      "views": 1337,
      "likes": 42,
      "dislikes": 7,
      "comments": 0,
      "nsfw": true,
      "nsfwSummary": "string",
      "aiUsage": {
        "id": 1,
        "label": "string"
      },
      "commercialContent": {
        "id": 1,
        "label": "string"
      },
      "recommendationScope": {
        "id": 1,
        "label": "string"
      },
      "waitTranscoding": true,
      "state": {
        "id": 1,
        "label": "string"
      },
      "scheduledUpdate": {
        "privacy": 1,
        "updateAt": "2024-01-15T09:30:00Z"
      },
      "blacklisted": true,
      "blacklistedReason": "string",
      "account": {
        "id": 0,
        "name": "string",
        "displayName": "string",
        "url": "https://example.com",
        "host": "example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ]
      },
      "channel": {
        "id": 42,
        "name": "string",
        "displayName": "string",
        "url": "https://example.com",
        "host": "example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ]
      },
      "userHistory": {
        "currentTime": 0
      },
      "captionLanguages": [
        "fr"
      ]
    }
  ]
}

Parameters

scopeVideoRecommendationScopeSet1234query

Restrict recommended videos. Defaults to the recommendationScope of the reference video, or to 1 (all videos) if no reference video is given

videoIdid | UUIDv4 | shortUUIDquery

Reference video. Required if scope is 3 or 4

countinteger[1, 30]10query

Number of videos to return

excludeVideoIdsArray<id>query

Videos that must not be recommended (the reference video is always excluded)

nsfwstringtruefalsequery

whether to include nsfw videos, if any

nsfwFlagsIncludedNSFWFlag0124query

nsfwFlagsExcludedNSFWFlag0124query

aiUsageOneOfVideoAIUsageSet | Array<VideoAIUsageSet>query

PeerTube >= 9.0 Only list videos with one of these AI usages, declared by video creators. If not provided, the preference of the authenticated user (aiUsagesHidden) is used

Response

200OKVideoListResponse

successful operation

Response fields application/json

totalinteger

Example

dataArray<Video>

Show child attributes

idid

object id for the video

Show child attributes

id>= 1

Example

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

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

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

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

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

likesinteger

Example

dislikesinteger

Example

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 data.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

Same fields as data.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

400Bad Request

invalid parameters or missing videoId

401Unauthorized

reference video requires authentication or a password

403Forbidden

reference video is not visible by the user or the password is invalid

404Not Found

reference video not found

Docs by Sourcey