The API is split across 3 services: accounts, videos and media.
Root path: https://staging-api.pixop.com/accounts
Required Header | Value |
---|---|
Authorization | Bearer [JWT-TOKEN] or HTTP Basic authentication (email/password) |
Accept | application/json |
Content-Type | application/json |
/v1/token
Request Parameter | Mandatory | Purpose |
---|---|---|
team-id | No | Optionally select a team that this user belongs to which will apply to all subsequent requests that use this generated auth token |
Response:
/v1/token
Response (Success):
{
"user": {
"id": ".... user id ....",
"name": " .... name ....",
"email": ".... email address ....",
"emailConfirmed": [boolean, true if email has been confirmed],
"authSignatureMethod": ".... JWT signature algorithm ....",
"authSignaturePublicKey": ".... public key used for signing JWT ....",
"authSignaturePublicKeyId": ".... public key id used for signing JWT ....",
"banned": [boolean, true if user has been banned],
"bannedReason": ".... reason ....",
"bannedDate": "YYYY-MM-DD hh:mm:ss",
"apiRequestSignatureSecret": ".... shared secret used for signing API requests ....",
"apiRequestSignatureSethod": ".... signing algorithm for signing API requests ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
"team": {
"id": ".... team id ....",
"name": ".... team name ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
"otherTeams": [
{
"id": ".... team id ....",
"name": ".... team name ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
{
"id": ".... team id ....",
"name": ".... team name ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
.....
]
}
Response (Failure):
Exception | Meaning |
---|---|
InvalidJWTTokenFoundException | The JWT Token supplied could not be interpreted for some reason (e.g. corrupt) |
NoJWTTokenFoundException | No JWT Token was supplied in the Authorization header for this request |
ExpiredJWTTokenException | The JWT Token supplied is no longer valid, the expiration time has passed |
PrematureJWTTokenException | The JWT Token supplied is not valid yet, i.e. it is not yet the ‘not before’ time in the token |
UserBannedException | The User account referenced by this JWT Token has been suspended and may not use the API |
EternalJWTTokenException | The JWT Token does not have a TTL which is a security vulnerability. Such tokens are not permitted by this API |
InconsistentJWTClaimsException | The claims inside this JWT token are not suitable for use by this API |
AuthException | There was a general service failure whilst trying to authenticate this JWT token |
/v1/account
Response:
{
"user": {
"id": ".... user id ....",
"name": " .... name ...",
"email": ".... email address ....",
"emailConfirmed": [boolean, true if email has been confirmed],
"authSignatureMethod": ".... JWT signature algorithm ....",
"authSignaturePublicKey": ".... public key used for signing JWT ....",
"authSignaturePublicKeyId": ".... public key id used for signing JWT ....",
"banned": [boolean, true if user has been banned],
"bannedReason": ".... reason why this account is banned ....",
"bannedDate": "YYYY-MM-DD hh:mm:ss",
"apiRequestSignatureSecret": ".... shared secret used for signing API requests ....",
"apiRequestSignatureMethod": ".... signing algorithm for signing API requests ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
"team": {
"id": ".... team id ....",
"name": ".... team name ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
}
}
/v1/generate-auth-secret
Response:
{
"user": {
"id": ".... user id ....",
"authSignatureMethod": ".... JWT signature algorithm ....",
"authSignaturePublicKey": ".... public key used for signing JWT ....",
"authSignaturePublicKeyId": ".... public key id used for signing JWT ....",
.....
}
}
/v1/generate-signature-secret
Response:
{
"user": {
"id": ".... user id ....",
.....
"apiRequestSignatureSecret": ".... shared secret used for signing API requests ....",
"apiRequestSignatureMethod": ".... signing algorithm for signing API requests ...."
.....
}
}
/v1/update-password
Request Body:
Response:
Root path: https://staging-api.pixop.com/videos
Required Header | Value |
---|---|
Authorization | Bearer [JWT-TOKEN] |
Accept | application/json |
Content-Type | application/json |
/v1/project/[project-id]
Response:
{
"project": {
"id": ".... project id ....",
"name": ".... project name ....",
"teamId": ".... id of team that owns this project ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
}
}
/v1/projects
Request Parameter | Mandatory | Purpose |
---|---|---|
page | No | Navigate to a given page within the paginated results |
page-size | No | How many results to return per page |
Response:
{
"pageSize": ".... page size ....",
"page": .... page number ....",
"_links": {
"self": { "href": ".... API endpoint to this page ...." },
"next": { "href": ".... API endpoint to next page ...." },
"previous": { "href": ".... API endpoint to previous page ...." },
"first": { "href": ".... API endpoint to the first page ...." },
"last": { "href": ".... API endpoint to the last page ...." }
},
"_embedded": {
"projects": [
{
"_links": {
"self": { "href": ".... API endpoint to call to access project ...." }
},
"id": ".... project id ....",
"name": ".... project name ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
.....
]
}
}
/v1/project
Request Body:
Response:
/v1/project/[project-id]
Request Body:
Response:
/v1/project/[project-id]
Note: This request will fail if there are videos currently associated with the project, they must be deleted first.
/v1/video/[video-id]
Response:
{
"video" : {
"id" : ".... video id ....",
"name" : ".... video name ....",
"description" : ".... video description ....",
"projectId" : ".... project id that this video is associated with ....",
"userId" : ".... user id that uploaded or processed this video ....",
"teamId" : ".... team id that this video belongs to ....",
"upload" : {
"uploadState" : {
"updatedAt" : "YYYY-MM-DD hh:mm:ss",
"uploadStatus" : ".... upload status ...."
},
"hasFinishedUploading" : [boolean, true if video has finished uploading],
"fileName" : ".... filename of media file ....",
"fileSize" : ".... size in bytes of media file ....",
"fileType" : ".... MIME type of media file ....",
"fileContainerName" : ".... description of container format of media file ...."
},
"ingestion" : {
"ingestionState" : {
"updatedAt" : "YYYY-MM-DD hh:mm:ss",
"ingestionStatus" : ".... ingestion status ....",
"videoMetadataAvailable": [boolean, true if initial metadata is available],
"videoMetadataCommitted": [boolean, true when all metadata updates have been fully committed],
"processingProgressPercent": [float, completion percentage (0.0-100.0)]
},
"metadata" : {
"containerName" : ".... short video container name ....",
"longContainerName" : ".... long video container name ....",
"codecName" : ".... short codec name ....",
"longCodecName" : ".... long codec name ....",
"pixelFormat" : {
"name" : ".... FFmpeg pixel format name (e.g. 'yuv420p') ....",
"chromaSubsampling" : {
"yuv" : ".... YUV chroma subsampling triplet string separated by colons (e.g. '4:2:0') ....",
"bits" : [integer, number of bits per pixel]
}
},
"frameWidth" : [integer, frame width],
"frameHeight" : [integer, frame height],
"scanning" : {
"metadata" : {
"scanningType" : ".... scanning type detected from metadata ....",
"interlacedFieldOrder" : ".... interlaced field order detected from metadata ...."
},
"heuristics" : {
"scanningType" : ".... scanning type detected from deep heuristics analysis ....",
"interlacedFieldOrder" : ".... interlaced field order detected from deep heuristics analysis ...."
},
},
"averageFramerate" : [float, average number of frames per second],
"durationInMillis" : [integer, video duration in milliseconds],
"totalFrames" : [integer, total number of video frames],
"size" : [integer, file size],
"videoStreamSize" : [integer, size of video stream]
},
"qualityAssessment" : {
"metrics": [
{
"name": ".... metric name ....",
"sampleMean": [float, measurement computed as mean of all sampled frames],
"subjectiveLabel": ".... human subjective score label (e.g. 'excellent') ....",
"subjectiveScore": [float, human subjective score (0-5)]
},
.....
],
"overallSubjectiveScore": [float, mean subjective score of all metrics (0-5)]
}
},
"processing": {
"processingState": {
"updatedAt": "YYYY-MM-DD hh:mm:ss",
"processingStatus": ".... processing status ....",
"processingProgressPercent": [float, completion percentage (0.0-100.0)]
},
"processingParameters": {
"sourceVideo": {
"startPositionMilliseconds": [integer, start time of clip in milliseconds (optional)],
"endPositionMilliseconds": [integer, end time of clip in milliseconds (optional)]
},
"targetVideo": {
"preset": {
"name": .... preset name used to process video ...."
},
"container": {
"name": ".... target container ....",
"properties": [object, container configuration properties]
},
"codec": {
"name": ".... target codec ....",
"properties": [object, codec configuration properties]
},
"pixelFormat": {
"name" : ".... target FFmpeg pixel format name (e.g. 'yuv420p') ....",
"chromaSubsampling" : {
"yuv" : ".... target YUV chroma subsampling triplet string separated by colons (e.g. '4:2:0') ....",
"bits" : [integer, number of bits per pixel]
}
},
"bitrate": [integer, target bitrate],
"frameWidth": [integer, target frame width],
"frameHeight": [integer, target frame height],
"videoFilters": [
{
"name": ".... video filter id ....",
"properties": [object, filter configuration properties]
},
.....
]
}
}
},
"attributes" : [object, video metadata],
"dateCreated" : "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated" : "YYYY-MM-DD hh:mm:ss"
}
}
/v1/videos
Parameter | Mandatory | Purpose |
---|---|---|
project-id | No | Filter results to only videos associated with this project |
parent-id | No | Filter results to only videos associated with this parent original video |
page | No | Navigate to a given page within the paginated results |
page-size | No | How many results to return per page |
Response:
{
"pageSize": ".... page size ....",
"page": ".... page number ....",
"_links": {
"self": { "href": ".... API endpoint to this page ...." },
"next": { "href": ".... API endpoint to next page ...." },
"previous": { "href": ".... API endpoint to previous page ...." },
"first": { "href": ".... API endpoint to the first page ...." },
"last": { "href": ".... API endpoint to the last page ...." }
},
"_embedded": {
"videos": [
{
"_links": {
"self": { "href": ".... API endpoint to call to access video ...." }
},
"id": ".... video id ....",
"parentId": ".... parent video id (of processed video) ....",
"projectId": ".... project id this video belongs to ....",
"name": ".... name ....",
"filename": ".... filename ....",
"dateCreated": "YYYY-MM-DD hh:mm:ss",
"timeLastUpdated": "YYYY-MM-DD hh:mm:ss"
},
.....
]
}
}
/v1/video
Request Body:
{
"name": ".... name of video.... (optional)",
"projectId": "... id of project to associate the video with .... (optional)"
}
Response:
{
"projectId": ".... project id that this new video was associated with ....",
"videoId": ".... id of the newly created video item .....",
"uploadMediaUrl": ".... API endpoint to call to upload media to this video item ...",
"uploadLightMediaUrl": ".... API endpoint to call to upload light ingested media to this video item ...",
"processVideoUrl": ".... API endpoint to call to initiate a process video request on this video ..."
}
/v1/process-video/[video-id]
Request Body:
{
"mediaContainerCodec": {
"container": "mov",
"codec": "h264"
},
"appleProresProfile": "standard",
"dnxhdHrProfile": "dnxhd_sq",
"scanning": {
"tag": "interlaced_tff",
"scanningType": "interlaced",
"interlacedFieldOrder": "top_field"
}
"chromaSubsampling": {
"yuv": "4:2:2",
"bits": 8
},
"bitrate": {
"mbps": 20.5
},
"deinterlacer": "deint",
"denoiser": "denoise",
"stabilizer": "dejit",
"scaler": "pabsr1",
"resolution": {
"tag": "hd_1080p",
"width": 1920,
"height": 1080,
"aspectRatioTag": "16:9"
},
"clarityBoost": "low",
"frameRateConverter": "vfi",
"frameRate": {
"tag": "film",
"fps": 24.0
},
"postProcessor": "filmgrain",
"range": {
"startPositionMilliseconds": 0,
"endPositionMilliseconds": 30000
}
}
Field | Mandatory | Permitted Value | Comments |
---|---|---|---|
mediaContainerCodec→container | No | mov | QuickTime |
mxf | Material Exchange Format | ||
mp4 | MPEG-4 | ||
mts | MPEG-2 Transport Stream | ||
mediaContainerCodec→codec | No | h264 | H.264 / AVC |
prores | Apple ProRes | ||
dnxhd | Avid DNxHD/HR | ||
xdcam | Sony XDCAM HD422 | ||
hevc | H.265 / HEVC | ||
mpeg2 | H.262 / MPEG-2 | ||
ffv1 | FF video codec 1 | ||
appleProresProfile | Only if codec is prores | proxy | Apple ProRes “proxy” profile |
lt | Apple ProRes “LT” profile | ||
standard | Apple ProRes “standard” profile | ||
hq | Apple ProRes “high quality” profile | ||
4444 | Apple ProRes “4444 high quality” profile (without alpha channel processing) | ||
4444xq | Apple ProRes “4444 XQ” profile (without alpha channel processing) | ||
dnxhdHrProfile | Only if codec is dnxhd | dnxhd_lb | DNxHD “low bandwidth” profile |
dnxhd_sq | DNxHD “standard quality” profile | ||
dnxhd_hq | DNxHD “high quality” profile | ||
dnxhd_hqx | DNxHD “high quality extended 10-bit” profile | ||
dnxhd_444 | DNxHD “4:4:4 10-bit” profile | ||
dnxhr_lb | DNxHR “low bandwidth” profile | ||
dnxhr_sq | DNxHR “standard quality” profile | ||
dnxhr_hq | DNxHR “high quality” profile | ||
dnxhr_hqx | DNxHR “high quality extended 12-bit” profile | ||
dnxhr_444 | DNxHR “4:4:4 12-bit” profile | ||
scanning→tag | No | auto | This field specifies preset scanning settings instead of specifying explicit scanning type and interlaced field order. Specifically auto means automatically determining the appropriate scanning type based on the metadata of the source and any filters selected. Not specifying anything for scanning implies auto mode. |
progressive | Force progressive output | ||
interlaced_tff | Perform explicit interlacing of the processed video, top field first | ||
interlaced_bff | Perform explicit interlacing of the processed video, bottom field first | ||
scanning→scanningType | No | progressive | Scanning type and/or interlaced field order can be specified as an alternative to using a scanning preset tag |
interlaced | Perform explicit interlacing of the processed video | ||
scanning→interlacedFieldOrder | Only if scanningType is interlaced | top_field | Top field first |
bottom_field | Bottom field first | ||
chromaSubsampling→yuv | No | 4:1:0 | YUV chroma subsampling. If not explicitly specified the chroma subsampling of the source video will be inherited for the output video. |
4:1:1 | |||
4:2:0 | |||
4:2:2 | |||
4:4:0 | |||
4:4:4 | |||
chromaSubsampling→bits | No | 8 | Pixel bit depth. If not explicitly specified the pixel depth of the source video will be inherited for the output video. |
10 | |||
12 | |||
14 | |||
16 | |||
bitrate→mbps | No | [0.01-4000.0] | Bitrate (megabits per second). A suitable value is computed automatically based on the source video bitrate and target resolution if bitrate is unspecified. |
deinterlacer | No | deint | Pixop Deinterlacer |
yadif | YADIF (“Yet Another DeInterlacing Filter”) | ||
bwdif | Bob Weaver | ||
weston3f | Weston Three Field | ||
denoiser | No | denoise | Pixop Denoiser |
hqdn3d | High Quality DeNoise 3D | ||
stabilizer | No | dejit | Pixop Dejitterer |
scaler | No | dvres2 | Pixop Deep Restoration 2 |
dvres | Pixop Deep Restoration | ||
pabsr1 | Pixop Super Resolution | ||
scale | Bicubic Interpolation | ||
frameRateConverter | No | vfi | Pixop Frame Rate Conversion |
fps | Constant FPS | ||
fblend | Frame Blending | ||
mcinterpolate | Motion Compensation | ||
postProcessor | No | filmgrain | Pixop Film Grain |
resolution→tag | No | hd_1080p | This field specifies preset resolution settings instead of specifying explicit width and height. Specifically hd_1080p implies an output frame of 1920 x 1080 pixels. |
uhd_4k | 3840 x 2160 pixels | ||
uhd_8k | 7680 x 4320 pixels | ||
no_scaling | Source video frame dimensions | ||
2x | Source video frame dimensions * 2 | ||
3x | Source video frame dimensions * 3 | ||
4x | Source video frame dimensions * 4 | ||
resolution→width | No | [16-7680] | Width and/or height must be specified if, and only if there is no tag. By only specifying one of either width or height, the other value can be determined via one of the dynamic or static aspect ratio tags below. It’s a bad request to specify all of width, height and a aspect ratio tag together. |
resolution→height | No | [16-4320] | |
resolution→aspectRatioTag | No | display | Display aspect ratio (DAR) of the source file read from the metadata. If DAR isn’t set, the storage aspect ratio will be used instead. |
storage | Storage aspect ratio of the source file | ||
16:9 | 16:9 aspect ratio (~1.777) | ||
4:3 | 4:3 aspect ratio (~1.333) | ||
clarityBoost | No | none | Defines the amount of contrast enhancement performed when Pixop Super Resolution scaler is selected |
marginal | |||
very_low | |||
low | |||
medium | |||
high | |||
very_high | |||
frameRate→tag | No | film_ntsc | This field specifies preset frame rate settings instead of specifying frames per second (FPS). Specifically film_ntsc implies an output frame rate of 23.976 FPS. |
film | 24 FPS | ||
video_pal | 25 FPS | ||
video_ntsc | 29.97 FPS | ||
video_hd | 30 FPS | ||
video_pal_fast | 50 FPS | ||
video_ntsc_fast | 59.94 FPS | ||
video_hd_fast | 60 FPS | ||
frameRate→fps | No | [0.001-999] | Frames per second must be specified if there is no tag. |
startPositionMilliseconds | No | [0-duration of video in milliseconds] | Start position, used to process a clip |
endPositionMilliseconds | No | [0-duration of video in milliseconds] | End position, used to process a clip |
Response:
{
"sourceVideoId": ".... id of video used as the source for the processing request ....",
"processedVideoId": ".... video id the processing request will generate ....",
"projectId": ".... id of project this video is associated with ....",
"checkProgressUrl": ".... API endpoint to query the progress of the process video operation ....",
"downloadMediaUrl": ".... API endpoint to download the media from the newly processed video ...."
}
Note: Any of container, codec, chroma subsampling and bitrate will be assumed based on source video metadata and target resolution when not specified in request.
/v1/check-process-video-progress/[video-id]
Response:
{
"videoId": ".... video id ....",
"projectId": ".... project id ....",
"processingState": {
"updatedAt": "YYYY-MM-DD hh:mm:ss",
"processingStatus": ".... processing status ....",
"processingProgressPercent": [float, percentage processed]
}
}
/v1/check-ingest-video-progress/[video-id]
Response:
{
"videoId": ".... video id ....",
"projectId": ".... project id ....",
"ingestionState": {
"updatedAt": "YYYY-MM-DD hh:mm:ss",
"ingestionStatus": ".... ingestion status ....",
"videoMetadataAvailable": [boolean, true if metadata is available]
}
}
/v1/video/[video-id]
Response:
{
"deletedVideos": [
{
"videoId": ".... deleted video id 1 ...."
},
{
"videoId": ".... deleted video id 2 ...."
},
.....
]
}
Note: All processed videos are also deleted when an original video is specified.
Root path: https://staging-api.pixop.com/media
Required Header | Value |
---|---|
Authorization | Bearer [JWT-TOKEN] |
/v1/upload/[video-id]
Request Body: A MIME multipart form file upload request containing the raw binary of the media payload, specifying the filename and content-type in the MIME envelope
Response:
{
"projectId": ".... project id that this new video was associated with ....",
"videoId": ".... id of the newly created video item .....",
"checkIngestProgressUrl": ".... API endpoint to query the progress of the ingest video operation ....",
"processVideoUrl": ".... API endpoint to call to initiate a process video request on this video ...."
}
/v1/upload/light/[video-id]
Notes:
/v1/download/original/[video-id]
Request:
Request Header | Required | Purpose |
---|---|---|
Authorization | Yes | Bearer [JWT-TOKEN] |
If-None-Match | No | Cache-control, if the etag of the stored media matches (ie, no update since the last download, then respond with a 304 Not Modified |
Range | No | Allow the download to be resumed, or downloaded in sections |
Response:
Response Header | Purpose |
---|---|
Content-Disposition | Filename of the downloaded media |
Etag | Hash of the currently stored media, can be passed in If-None-Match header of a future download request for cache-control purposes |
Content-Range | If a Range header was supplied |
Content-Length | Size of the stored media file |
HTTP Method | Response body contents |
---|---|
GET | The raw video file originally uploaded in binary form |
HEAD | Empty response body |
/v1/download/processed/[video-id]
Access the raw processed video file that has been generated by the video processing operation.
Note: Refer to the Download original media associated with a video item endpoint documentation as this endpoint is functionally similar.
Latest updated: December 22, 2021