# coding: utf-8 """ PeerTube The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) which generates a client SDK in the language of your choice - we generate some client SDKs automatically: - [Python](https://framagit.org/framasoft/peertube/clients/python) - [Go](https://framagit.org/framasoft/peertube/clients/go) - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) See the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few examples of using the PeerTube API. # Authentication When you sign up for an account on a PeerTube instance, you are given the possibility to generate sessions on it, and authenticate there using an access token. Only __one access token can currently be used at a time__. ## Roles Accounts are given permissions based on their role. There are three roles on PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin/managing-users#roles) for a detail of their permissions. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body. ``` HTTP 1.1 404 Not Found Content-Type: application/problem+json; charset=utf-8 { \"detail\": \"Video not found\", \"docs\": \"https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo\", \"status\": 404, \"title\": \"Not Found\", \"type\": \"about:blank\" } ``` We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/packages/models/src/server/core-error-code.enum.ts), but it is still optional. Types are used to disambiguate errors that bear the same status code and are non-obvious: ``` HTTP 1.1 403 Forbidden Content-Type: application/problem+json; charset=utf-8 { \"detail\": \"Cannot get this video regarding follow constraints\", \"docs\": \"https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo\", \"status\": 403, \"title\": \"Forbidden\", \"type\": \"https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints\" } ``` Here a 403 error could otherwise mean that the video is private or blocklisted. ### Validation errors Each parameter is evaluated on its own against a set of rules before the route validator proceeds with potential testing involving parameter combinations. Errors coming from validation errors appear earlier and benefit from a more detailed error description: ``` HTTP 1.1 400 Bad Request Content-Type: application/problem+json; charset=utf-8 { \"detail\": \"Incorrect request parameters: id\", \"docs\": \"https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo\", \"instance\": \"/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180\", \"invalid-params\": { \"id\": { \"location\": \"params\", \"msg\": \"Invalid value\", \"param\": \"id\", \"value\": \"9c9de5e8-0a1e-484a-b099-e80766180\" } }, \"status\": 400, \"title\": \"Bad Request\", \"type\": \"about:blank\" } ``` Where `id` is the name of the field concerned by the error, within the route definition. `invalid-params..location` can be either 'params', 'body', 'header', 'query' or 'cookies', and `invalid-params..value` reports the value that didn't pass validation whose `invalid-params..msg` is about. ### Deprecated error fields Some fields could be included with previous versions. They are still included but their use is deprecated: - `error`: superseded by `detail` - `code`: superseded by `type` (which is now an URI) # Rate limits We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: | Endpoint (prefix: `/api/v1`) | Calls | Time frame | |------------------------------|---------------|--------------| | `/*` | 50 | 10 seconds | | `POST /users/token` | 15 | 5 minutes | | `POST /users/register` | 2* | 5 minutes | | `POST /users/ask-send-verify-email` | 3 | 5 minutes | Depending on the endpoint, *failed requests are not taken into account. A service limit is announced by a `429 Too Many Requests` status code. You can get details about the current state of your rate limit by reading the following headers: | Header | Description | |-------------------------|------------------------------------------------------------| | `X-RateLimit-Limit` | Number of max requests allowed in the current time period | | `X-RateLimit-Remaining` | Number of remaining requests in the current time period | | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp | | `Retry-After` | Seconds to delay after the first `429` is received | # CORS This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/), allowing cross-domain communication from the browser for some routes: | Endpoint | |------------------------- ---| | `/api/*` | | `/download/*` | | `/lazy-static/*` | | `/.well-known/webfinger` | In addition, all routes serving ActivityPub are CORS-enabled for all origins. The version of the OpenAPI document: 5.2.0 Generated by OpenAPI Generator (https://openapi-generator.tech) Do not edit the class manually. """ # noqa: E501 from __future__ import annotations import pprint import re # noqa: F401 import json from datetime import datetime from pydantic import BaseModel, Field, StrictBool, StrictInt, StrictStr, field_validator from typing import Any, ClassVar, Dict, List, Optional from typing_extensions import Annotated from peertube.models.account import Account from peertube.models.video_channel import VideoChannel from peertube.models.video_constant_number_category import VideoConstantNumberCategory from peertube.models.video_constant_number_licence import VideoConstantNumberLicence from peertube.models.video_constant_string_language import VideoConstantStringLanguage from peertube.models.video_file import VideoFile from peertube.models.video_privacy_constant import VideoPrivacyConstant from peertube.models.video_scheduled_update import VideoScheduledUpdate from peertube.models.video_state_constant import VideoStateConstant from peertube.models.video_streaming_playlists import VideoStreamingPlaylists from peertube.models.video_user_history import VideoUserHistory from typing import Optional, Set from typing_extensions import Self class VideoDetails(BaseModel): """ VideoDetails """ # noqa: E501 id: Optional[Annotated[int, Field(strict=True, ge=1)]] = Field(default=None, description="object id for the video") uuid: Optional[Annotated[str, Field(min_length=36, strict=True, max_length=36)]] = Field(default=None, description="universal identifier for the video, that can be used across instances") short_uuid: Optional[StrictStr] = Field(default=None, description="translation of a uuid v4 with a bigger alphabet to have a shorter uuid", alias="shortUUID") is_live: Optional[StrictBool] = Field(default=None, alias="isLive") created_at: Optional[datetime] = Field(default=None, description="time at which the video object was first drafted", alias="createdAt") published_at: Optional[datetime] = Field(default=None, description="time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.", alias="publishedAt") updated_at: Optional[datetime] = Field(default=None, description="last time the video's metadata was modified", alias="updatedAt") originally_published_at: Optional[datetime] = Field(default=None, description="used to represent a date of first publication, prior to the practical publication date of `publishedAt`", alias="originallyPublishedAt") category: Optional[VideoConstantNumberCategory] = Field(default=None, description="category in which the video is classified") licence: Optional[VideoConstantNumberLicence] = Field(default=None, description="licence under which the video is distributed") language: Optional[VideoConstantStringLanguage] = Field(default=None, description="main language used in the video") privacy: Optional[VideoPrivacyConstant] = Field(default=None, description="privacy policy used to distribute the video") description: Optional[Annotated[str, Field(min_length=3, strict=True, max_length=250)]] = Field(default=None, description="truncated description of the video, written in Markdown. Resolve `descriptionPath` to get the full description of maximum `10000` characters. ") duration: Optional[StrictInt] = Field(default=None, description="duration of the video in seconds") is_local: Optional[StrictBool] = Field(default=None, alias="isLocal") name: Optional[Annotated[str, Field(min_length=3, strict=True, max_length=120)]] = Field(default=None, description="title of the video") thumbnail_path: Optional[StrictStr] = Field(default=None, alias="thumbnailPath") preview_path: Optional[StrictStr] = Field(default=None, alias="previewPath") embed_path: Optional[StrictStr] = Field(default=None, alias="embedPath") views: Optional[StrictInt] = None likes: Optional[StrictInt] = None dislikes: Optional[StrictInt] = None nsfw: Optional[StrictBool] = None wait_transcoding: Optional[StrictBool] = Field(default=None, alias="waitTranscoding") state: Optional[VideoStateConstant] = Field(default=None, description="represents the internal state of the video processing within the PeerTube instance") scheduled_update: Optional[VideoScheduledUpdate] = Field(default=None, alias="scheduledUpdate") blacklisted: Optional[StrictBool] = None blacklisted_reason: Optional[StrictStr] = Field(default=None, alias="blacklistedReason") account: Optional[Account] = None channel: Optional[VideoChannel] = None user_history: Optional[VideoUserHistory] = Field(default=None, alias="userHistory") viewers: Optional[StrictInt] = Field(default=None, description="If the video is a live, you have the amount of current viewers") description_path: Optional[StrictStr] = Field(default=None, description="path at which to get the full description of maximum `10000` characters", alias="descriptionPath") support: Optional[Annotated[str, Field(min_length=3, strict=True, max_length=1000)]] = Field(default=None, description="A text tell the audience how to support the video creator") tags: Optional[Annotated[List[Annotated[str, Field(min_length=2, strict=True, max_length=30)]], Field(min_length=1, max_length=5)]] = None comments_enabled: Optional[StrictBool] = Field(default=None, alias="commentsEnabled") download_enabled: Optional[StrictBool] = Field(default=None, alias="downloadEnabled") input_file_updated_at: Optional[datetime] = Field(default=None, description="Latest input file update. Null if the file has never been replaced since the original upload", alias="inputFileUpdatedAt") tracker_urls: Optional[List[StrictStr]] = Field(default=None, alias="trackerUrls") files: Optional[List[VideoFile]] = Field(default=None, description="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 ") streaming_playlists: Optional[List[VideoStreamingPlaylists]] = Field(default=None, description="HLS playlists/manifest files. If HLS is disabled on the server: - field will be empty - video files will be found in `files` field ", alias="streamingPlaylists") __properties: ClassVar[List[str]] = ["id", "uuid", "shortUUID", "isLive", "createdAt", "publishedAt", "updatedAt", "originallyPublishedAt", "category", "licence", "language", "privacy", "description", "duration", "isLocal", "name", "thumbnailPath", "previewPath", "embedPath", "views", "likes", "dislikes", "nsfw", "waitTranscoding", "state", "scheduledUpdate", "blacklisted", "blacklistedReason", "account", "channel", "userHistory", "viewers", "descriptionPath", "support", "tags", "commentsEnabled", "downloadEnabled", "inputFileUpdatedAt", "trackerUrls", "files", "streamingPlaylists"] @field_validator('uuid') def uuid_validate_regular_expression(cls, value): """Validates the regular expression""" if value is None: return value if not re.match(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", value): raise ValueError(r"must validate the regular expression /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/") return value model_config = { "populate_by_name": True, "validate_assignment": True, "protected_namespaces": (), } def to_str(self) -> str: """Returns the string representation of the model using alias""" return pprint.pformat(self.model_dump(by_alias=True)) def to_json(self) -> str: """Returns the JSON representation of the model using alias""" # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead return json.dumps(self.to_dict()) @classmethod def from_json(cls, json_str: str) -> Optional[Self]: """Create an instance of VideoDetails from a JSON string""" return cls.from_dict(json.loads(json_str)) def to_dict(self) -> Dict[str, Any]: """Return the dictionary representation of the model using alias. This has the following differences from calling pydantic's `self.model_dump(by_alias=True)`: * `None` is only added to the output dict for nullable fields that were set at model initialization. Other fields with value `None` are ignored. """ excluded_fields: Set[str] = set([ ]) _dict = self.model_dump( by_alias=True, exclude=excluded_fields, exclude_none=True, ) # override the default output from pydantic by calling `to_dict()` of category if self.category: _dict['category'] = self.category.to_dict() # override the default output from pydantic by calling `to_dict()` of licence if self.licence: _dict['licence'] = self.licence.to_dict() # override the default output from pydantic by calling `to_dict()` of language if self.language: _dict['language'] = self.language.to_dict() # override the default output from pydantic by calling `to_dict()` of privacy if self.privacy: _dict['privacy'] = self.privacy.to_dict() # override the default output from pydantic by calling `to_dict()` of state if self.state: _dict['state'] = self.state.to_dict() # override the default output from pydantic by calling `to_dict()` of scheduled_update if self.scheduled_update: _dict['scheduledUpdate'] = self.scheduled_update.to_dict() # override the default output from pydantic by calling `to_dict()` of account if self.account: _dict['account'] = self.account.to_dict() # override the default output from pydantic by calling `to_dict()` of channel if self.channel: _dict['channel'] = self.channel.to_dict() # override the default output from pydantic by calling `to_dict()` of user_history if self.user_history: _dict['userHistory'] = self.user_history.to_dict() # override the default output from pydantic by calling `to_dict()` of each item in files (list) _items = [] if self.files: for _item in self.files: if _item: _items.append(_item.to_dict()) _dict['files'] = _items # override the default output from pydantic by calling `to_dict()` of each item in streaming_playlists (list) _items = [] if self.streaming_playlists: for _item in self.streaming_playlists: if _item: _items.append(_item.to_dict()) _dict['streamingPlaylists'] = _items # set to None if wait_transcoding (nullable) is None # and model_fields_set contains the field if self.wait_transcoding is None and "wait_transcoding" in self.model_fields_set: _dict['waitTranscoding'] = None # set to None if scheduled_update (nullable) is None # and model_fields_set contains the field if self.scheduled_update is None and "scheduled_update" in self.model_fields_set: _dict['scheduledUpdate'] = None # set to None if blacklisted (nullable) is None # and model_fields_set contains the field if self.blacklisted is None and "blacklisted" in self.model_fields_set: _dict['blacklisted'] = None # set to None if blacklisted_reason (nullable) is None # and model_fields_set contains the field if self.blacklisted_reason is None and "blacklisted_reason" in self.model_fields_set: _dict['blacklistedReason'] = None # set to None if user_history (nullable) is None # and model_fields_set contains the field if self.user_history is None and "user_history" in self.model_fields_set: _dict['userHistory'] = None # set to None if input_file_updated_at (nullable) is None # and model_fields_set contains the field if self.input_file_updated_at is None and "input_file_updated_at" in self.model_fields_set: _dict['inputFileUpdatedAt'] = None return _dict @classmethod def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: """Create an instance of VideoDetails from a dict""" if obj is None: return None if not isinstance(obj, dict): return cls.model_validate(obj) _obj = cls.model_validate({ "id": obj.get("id"), "uuid": obj.get("uuid"), "shortUUID": obj.get("shortUUID"), "isLive": obj.get("isLive"), "createdAt": obj.get("createdAt"), "publishedAt": obj.get("publishedAt"), "updatedAt": obj.get("updatedAt"), "originallyPublishedAt": obj.get("originallyPublishedAt"), "category": VideoConstantNumberCategory.from_dict(obj["category"]) if obj.get("category") is not None else None, "licence": VideoConstantNumberLicence.from_dict(obj["licence"]) if obj.get("licence") is not None else None, "language": VideoConstantStringLanguage.from_dict(obj["language"]) if obj.get("language") is not None else None, "privacy": VideoPrivacyConstant.from_dict(obj["privacy"]) if obj.get("privacy") is not None else None, "description": obj.get("description"), "duration": obj.get("duration"), "isLocal": obj.get("isLocal"), "name": obj.get("name"), "thumbnailPath": obj.get("thumbnailPath"), "previewPath": obj.get("previewPath"), "embedPath": obj.get("embedPath"), "views": obj.get("views"), "likes": obj.get("likes"), "dislikes": obj.get("dislikes"), "nsfw": obj.get("nsfw"), "waitTranscoding": obj.get("waitTranscoding"), "state": VideoStateConstant.from_dict(obj["state"]) if obj.get("state") is not None else None, "scheduledUpdate": VideoScheduledUpdate.from_dict(obj["scheduledUpdate"]) if obj.get("scheduledUpdate") is not None else None, "blacklisted": obj.get("blacklisted"), "blacklistedReason": obj.get("blacklistedReason"), "account": Account.from_dict(obj["account"]) if obj.get("account") is not None else None, "channel": VideoChannel.from_dict(obj["channel"]) if obj.get("channel") is not None else None, "userHistory": VideoUserHistory.from_dict(obj["userHistory"]) if obj.get("userHistory") is not None else None, "viewers": obj.get("viewers"), "descriptionPath": obj.get("descriptionPath"), "support": obj.get("support"), "tags": obj.get("tags"), "commentsEnabled": obj.get("commentsEnabled"), "downloadEnabled": obj.get("downloadEnabled"), "inputFileUpdatedAt": obj.get("inputFileUpdatedAt"), "trackerUrls": obj.get("trackerUrls"), "files": [VideoFile.from_dict(_item) for _item in obj["files"]] if obj.get("files") is not None else None, "streamingPlaylists": [VideoStreamingPlaylists.from_dict(_item) for _item in obj["streamingPlaylists"]] if obj.get("streamingPlaylists") is not None else None }) return _obj