Videos

Video Upload

Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.

Upload

legacy, where the video file is sent in a single request
resumable, where the video file is sent in chunks

You can upload videos more reliably by using the resumable variant. Its protocol lets you resume an upload operation after a network interruption or other transmission failure, saving time and bandwidth in the event of network failures.

Favor using resumable uploads in any of the following cases:

You are transferring large files
The likelihood of a network interruption is high
Uploads are originating from a device with a low-bandwidth or unstable Internet connection, such as a mobile device

Import

URL-based: where the URL points to any service supported by youtube-dl
magnet-based: where the URI resolves to a BitTorrent resource containing a single supported video file
torrent-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file

The import function is practical when the desired video/audio is available online. It makes PeerTube download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.

Import a video

POST

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

Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)

Import a video

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/imports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'targetUrl=https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d' \
  --form-string 'name=What is PeerTube?' \
  --form-string 'channelId=3' \
  --form-string 'privacy=1' \
  --form-string 'category=15' \
  --form-string 'licence=2' \
  --form-string 'language=en' \
  --form-string 'description=**[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)**
' \
  --form-string 'waitTranscoding=true' \
  --form-string 'generateTranscription=true' \
  --form-string 'support=Please support our work on https://soutenir.framasoft.org/en/ <3' \
  --form-string 'nsfw=true' \
  --form-string 'nsfwFlags=0' \
  --form-string 'tags=framasoft' \
  --form-string 'tags=peertube' \
  --form-string 'commentsPolicy=1' \
  --form-string 'recommendationScope=1' \
  --form-string 'aiUsage=1' \
  --form-string 'commercialContent=1' \
  --form-string 'downloadEnabled=true' \
  --form-string 'originallyPublishedAt=2024-01-15T09:30:00Z' \
  --form-string 'scheduleUpdate={"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}' \
  --form-string 'videoPasswords=string'

const form = new FormData();
form.append('targetUrl', 'https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d');
form.append('name', 'What is PeerTube?');
form.append('channelId', '3');
form.append('privacy', '1');
form.append('category', '15');
form.append('licence', '2');
form.append('language', 'en');
form.append('description', '**[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)**\n');
form.append('waitTranscoding', 'true');
form.append('generateTranscription', 'true');
form.append('support', 'Please support our work on https://soutenir.framasoft.org/en/ <3');
form.append('nsfw', 'true');
form.append('nsfwFlags', '0');
form.append('tags', 'framasoft');
form.append('tags', 'peertube');
form.append('commentsPolicy', '1');
form.append('recommendationScope', '1');
form.append('aiUsage', '1');
form.append('commercialContent', '1');
form.append('downloadEnabled', 'true');
form.append('originallyPublishedAt', '2024-01-15T09:30:00Z');
form.append('scheduleUpdate', '{"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}');
form.append('videoPasswords', 'string');
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/imports', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('targetUrl', (None, 'https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d')),
        ('name', (None, 'What is PeerTube?')),
        ('channelId', (None, '3')),
        ('privacy', (None, '1')),
        ('category', (None, '15')),
        ('licence', (None, '2')),
        ('language', (None, 'en')),
        ('description', (None, '**[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)**\n')),
        ('waitTranscoding', (None, 'true')),
        ('generateTranscription', (None, 'true')),
        ('support', (None, 'Please support our work on https://soutenir.framasoft.org/en/ <3')),
        ('nsfw', (None, 'true')),
        ('nsfwFlags', (None, '0')),
        ('tags', (None, 'framasoft')),
        ('tags', (None, 'peertube')),
        ('commentsPolicy', (None, '1')),
        ('recommendationScope', (None, '1')),
        ('aiUsage', (None, '1')),
        ('commercialContent', (None, '1')),
        ('downloadEnabled', (None, 'true')),
        ('originallyPublishedAt', (None, '2024-01-15T09:30:00Z')),
        ('scheduleUpdate', (None, '{"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}')),
        ('videoPasswords', (None, 'string')),
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/videos/imports', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "targetUrl": "https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d",
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[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)**\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ]
}

200

{
  "video": {}
}

Body

multipart/form-data

multipart/form-dataany & VideoUploadRequestCommon

Encoding

torrentfileapplication/x-bittorrent

thumbnailfileimage/jpeg

previewfileimage/jpeg

namestringrequired

Video name

Example

What is PeerTube?

channelIdinteger>= 1required

Channel id that will contain this video

Example

privacyVideoPrivacySet12345

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

categoryVideoCategorySet

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

Example

licenceVideoLicenceSet

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

Example

languageVideoLanguageSet

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

Example

en

descriptionstring

Video description

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)**

waitTranscodingboolean

Whether or not we wait transcoding before publish the video

generateTranscriptionboolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the video

supportstring

A text tell the audience how to support the video creator

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

nsfwboolean

Whether or not this video contains sensitive content

nsfwSummaryany

More information about the sensitive content of the video

nsfwFlagsNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

tagsArray<string>

Video tags (maximum 5 tags each between 2 and 30 characters)

Example

[
  "framasoft",
  "peertube"
]

commentsPolicyVideoCommentsPolicySet123

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

recommendationScopeVideoRecommendationScopeSet1234

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

aiUsageVideoAIUsageSet1234

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

commercialContentVideoCommercialContentSet123

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

downloadEnabledboolean

Enable or disable downloading for this video

originallyPublishedAtstring<date-time>

Date when the content was originally published

scheduleUpdateVideoScheduledUpdate

Show child attributes

privacyVideoPrivacySet12345

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

updateAtstring<date-time>required

When to update the video

thumbnailfilestring<binary>

Video thumbnail file

previewfilestring<binary>deprecated

Deprecated in PeerTube v8.1, use thumbnailfile instead

videoPasswordsArray<password>

One of

targetUrltargetUrl<url>required

remote URL where to find the import's source video

Example

https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d

magnetUrimagnetUri<uri>required

magnet URI allowing to resolve the import's source video

torrentfiletorrentfile<binary>required

Torrent file containing only the video file

Response

200OKVideoUploadResponse

successful operation

Response fields application/json

videoobject

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

400Bad Request

magnetUri or targetUrl or a torrent file missing

403Forbidden

video didn't pass pre-import filter

409Conflict

HTTP or Torrent/magnetURI import not enabled

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Docs by Sourcey