Videos

Video Captions

Operations dealing with listing, adding and removing closed captions of a video.

List captions of a video

GET

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

List captions of a video

curl -X GET 'https://peertube2.cpy.re/api/v1/videos/42/captions'

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

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos/42/captions')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "language": {
        "id": "en",
        "label": "English"
      },
      "automaticallyGenerated": true,
      "captionPath": "string",
      "fileUrl": "string",
      "m3u8Url": "string",
      "updatedAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<VideoCaption>

Show child attributes

languageVideoConstantString-Language

Show child attributes

idVideoLanguageSet

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

Example

en

labelstring

Example

English

automaticallyGeneratedboolean

captionPathstring | 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

m3u8Urlstring

updatedAtstring<date-time>

Generate a video caption

POST

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

PeerTube >= 6.2 This feature has to be enabled by the administrator

Generate a video caption

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/captions/generate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "forceTranscription": false
}'

const body = `{
  "forceTranscription": false
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/captions/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "forceTranscription": false
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/videos/42/captions/generate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "forceTranscription": false
}

Body

application/json

forceTranscriptionbooleanfalse

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

204No Content

successful operation

404Not Found

video not found

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.

Scopes: user

Add or replace a video caption

PUT

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

Add or replace a video caption

curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/42/captions/en' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const form = new FormData();
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/captions/en', {
  method: 'PUT',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
    ]
    response = requests.request('PUT', 'https://peertube2.cpy.re/api/v1/videos/42/captions/en', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "captionfile": "<binary>"
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

captionfiletext/vtt, application/x-subrip, text/plain

captionfilestring<binary>

The file to upload.

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

captionLanguageVideoLanguageSetrequiredpath

The caption language

Response

204No Content

successful operation

404Not Found

video or language not found

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.

Scopes: user

Delete a video caption

DELETE

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

Delete a video caption

curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/42/captions/en' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/captions/en', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/videos/42/captions/en',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

captionLanguageVideoLanguageSetrequiredpath

The caption language

Response

204No Content

successful operation

404Not Found

video or language or caption for that language not found

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.

Scopes: user

Docs by Sourcey