API Reference

Here's everything you need to know to integrate and use Pixop's REST API.

Pixop Video Processing REST API v1

The API is split across 3 services: accounts, videos and media.

The Accounts Service Endpoints allow you to authenticate your account credentials, generate an auth (JWT) token for use in other API calls, and perform some basic account management operations on your account. A JWT token is valid for 15 minutes.
The Videos Service Endpoints allow you to create and browse and manage projects and their associated videos, as well as triggering requests to apply processing to videos that have been uploaded and tracking the progress of any in progress processing requests.
The Media Service Endpoints allow you to upload video files that relate to a video item, and to download the resultant processed media.

Accounts Service Endpoints

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

Authenticate account credentials and generate JWT token

Subpath: /v1/token
Method: GET
Authentication: HTTP Basic auth in Authorization header (passing email and password)

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:

{
  "userId": ".... user id ....",
  "teamId": ".... team id ....",
  "jwtToken": ".... token ...."
}

Authenticate JWT token and return associated account and team identity

Subpath: /v1/token
Method: POST
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [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": ".... exception ....",
  "errorMessage": ".... error message ...."
}

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

Retrieve account details

Subpath: /v1/account
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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"
  }
}

Generate authentication secret

Subpath: /v1/generate-auth-secret
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN] or HTTP Basic auth in Authorization header (passing email and password)

Response:

{
  "user": {
    "id": ".... user id ....",
    "authSignatureMethod": ".... JWT signature algorithm ....",
    "authSignaturePublicKey": ".... public key used for signing JWT ....",
    "authSignaturePublicKeyId": ".... public key id used for signing JWT ....",
    .....
  }
}

Generate API signed-request signature secret

Subpath: /v1/generate-signature-secret
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN] or HTTP Basic auth in Authorization header (passing email and password)

Response:

{
  "user": {
    "id": ".... user id ....",
    .....
    "apiRequestSignatureSecret": ".... shared secret used for signing API requests ....",
    "apiRequestSignatureMethod": ".... signing algorithm for signing API requests ...."
    .....
  }
}

Update account password

Subpath: /v1/update-password
Method: POST
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN] or HTTP Basic auth in Authorization header (passing email and password)

Request Body:

{
  "newPassword": ".... new password ...."
}

Response:

{
  "user": {
    "id": ".... user id ....",
    .....
   }
}

Videos Service Endpoints

Root path: https://staging-api.pixop.com/videos

Required Header	Value
Authorization	Bearer [JWT-TOKEN]
Accept	application/json
Content-Type	application/json

Retrieve project details

Subpath: /v1/project/[project-id]
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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"
  }
}

Retrieve paginated list of projects associated with this user

Subpath: /v1/projects
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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"
      },
      .....
    ]
  }
}

Create new project

Subpath: /v1/project
Method: PUT
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

Request Body:

{
  "name": "... name ...."
}

Response:

{
  "project": {
    "id": ".... project id ....",
    .....
  }
}

Update project details

Subpath: /v1/project/[project-id]
Method: POST
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

Request Body:

{
  "name": "... updated name ...."
}

Response:

{
  "project": {
    "id": ".... project id ....",
    .....
  }
}

Delete project

Subpath: /v1/project/[project-id]
Method: DELETE
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

Note: This request will fail if there are videos currently associated with the project, they must be deleted first.

Retrieve video item details

Subpath: /v1/video/[video-id]
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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"
  }
}

Retrieve paginated list of videos associated with this user

Subpath: /v1/videos
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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"
      },
      .....
    ]
  }
}

Create new video

Subpath: /v1/video
Method: PUT
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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 ..."
}

Trigger a request to process a video

Subpath: /v1/process-video/[video-id]
Method: POST
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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
		video_uhd_fast	120 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.

Check progress of a video currently being processed

Subpath: /v1/check-process-video-progress/[video-id]
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

Response:

{
  "videoId": ".... video id ....",
  "projectId": ".... project id ....",
  "processingState": {
    "updatedAt": "YYYY-MM-DD hh:mm:ss",
    "processingStatus": ".... processing status ....",
    "processingProgressPercent": [float, percentage processed]
  }
}

Check progress of a video currently being ingested

Subpath: /v1/check-ingest-video-progress/[video-id]
Method: GET
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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]
  }
}

Delete video and any new media generated so far

Subpath: /v1/video/[video-id]
Method: DELETE
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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.

Media Service Endpoints

Root path: https://staging-api.pixop.com/media

Required Header	Value
Authorization	Bearer [JWT-TOKEN]

Upload media relating to a video item

Subpath: /v1/upload/[video-id]
Method: POST
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]
Required Header: Content-Type: multipart/form-data

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 ...."
}

Upload media relating to a video item for light ingestion

Subpath: /v1/upload/light/[video-id]
Method: POST
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]
Required Header: Content-Type: multipart/form-data

Notes:

Only metadata is ingested. Thumbnails and web video artifacts are not generated, also quality assessment and deep scanning type analysis is not performed. Useful for third party integrations that process video in an ephemeral way.
Refer to the Upload media relating to a video item endpoint documentation as this endpoint is functionally similar.

Download original media associated with a video item

Subpath: /v1/download/original/[video-id]
Method: GET / HEAD
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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

Download processed media associated with a video item

Subpath: /v1/download/processed/[video-id]
Method: GET / HEAD
Authentication: A valid JWT token passed in Authorization header :: Authorization Bearer [TOKEN]

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

API Reference

Pixop Video Processing REST API v1

Services List

Accounts Service Endpoints

Authenticate account credentials and generate JWT token

Authenticate JWT token and return associated account and team identity

Retrieve account details

Generate authentication secret

Generate API signed-request signature secret

Update account password

Videos Service Endpoints

Retrieve project details

Retrieve paginated list of projects associated with this user

Create new project

Update project details

Delete project

Retrieve video item details

Retrieve paginated list of videos associated with this user

Create new video

Trigger a request to process a video

Check progress of a video currently being processed

Check progress of a video currently being ingested

Delete video and any new media generated so far

Media Service Endpoints

Upload media relating to a video item

Upload media relating to a video item for light ingestion

Download original media associated with a video item

Download processed media associated with a video item

Stay in the loop