PrizmDoc® Viewer v13.28 Release - Updated
PrizmDoc Video / PrizmDoc Video REST API / Media
In This Topic
    Media
    In This Topic

    Media

    The Media REST API is used to download and upload videos for viewing in PrizmDoc Viewer.

    Available URLs

    URL Description
    GET /api/v1/media/:fileId/video Downloads the video for viewing.
    POST /api/v1/media when body is file bytes Uploads the video for viewing.
    POST /api/v1/media when body is JSON Creates a File ID for viewing an existing video located on PrizmDoc Server’s storage.

    GET /api/v1/media/:fileId/video

    Downloads the video for viewing.

    Parameter

    Field Type Description
    fileId String File ID returned from /api/v1/media.

    Query Parameter(s)

    Field Type Description
    AffinityToken String Affinity Token returned on upload (only when PrizmDoc is in cluster mode).

    Success 200

    Field Type Description
    body ReadableStream Byte stream of the video uploaded to /api/v1/media.

    Success-Response

    HTTP/1.1 200 OK
    <video file bytes>
    
    

    Error 4xx

    Name Description
    NotFound The fileID specified in the URL path was not found.

    Error-Response

    HTTP/1.1 404 Not Found
    { }
    
    

    POST /api/v1/media when body is file bytes

    Uploads the video for viewing.

    Header

    Field Type Description
    Content-Type String Mime type of file. Expected to be one of video/mp4, video/webm, video/ogg, application/octet-stream.

    Request Body

    Field Type Description
    Body ArrayBuffer Video file bytes.

    Success 200

    Field Type Description
    fileID String Identifier associated with uploaded file.
    affinityToken String Identifier indicating the PrizmDoc Server instance that processed the request (only when running PrizmDoc Server in cluster mode).

    Success-Response

    HTTP/1.1 200 OK
    {
      "fileId": "zgOGNBUIjfRHF2g4SNz1_A"
    }
    
    

    Success-Response with Affinity Token

    HTTP/1.1 200 OK
    {
      "fileId": "zgOGNBUIjfRHF2g4SNz1_A",
      "affinityToken":"zTfGFeeRXKxPF5o4HgnFFgZ6YU6bcbvMsJdJciYJemo="
    }
    
    

    Error 4xx

    Name Description
    FeatureNotLicensed The file exceeds evaluation limit of 5MB.
    MissingInput Content-Type header is missing.
    InvalidInput Content-Type header is not a valid value.

    413 FeatureNotLicensed

    HTTP/1.1 413 FeatureNotLicensed
    {
      "errorCode": "FeatureNotLicensed",
      "errorDetails": {
        "in": "body",
        "at": "length",
        "expected": {
          "lessThanOrEqualTo": 5242880
        }
      }
    }
    
    

    480 MissingInput

    HTTP/1.1 480 MissingInput
    {
      "errorCode": "MissingInput",
      "errorDetails": {
        "in": "headers",
        "at": "Content-Type",
        "expected": {
          "oneOf": [
            {
              "value": "video/mp4"
            },
            {
              "value": "video/webm"
            },
            {
              "value": "video/ogg"
            },
            {
              "value": "application/octet-stream"
            }
          ]
        }
      }
    }
    
    

    480 InvalidInput

    HTTP/1.1 480 InvalidInput
    {
      "errorCode": "InvalidInput",
      "errorDetails": {
        "in": "headers",
        "at": "Content-Type",
        "expected": {
          "oneOf": [
            {
              "value": "video/mp4"
            },
            {
              "value": "video/webm"
            },
            {
              "value": "video/ogg"
            },
            {
              "value": "application/octet-stream"
            }
          ]
        }
      }
    }
    
    

    POST /api/v1/media when body is JSON

    Creates a File ID for an existing video located on PrizmDoc Server’s storage. This feature is only available for single server configurations in licensed mode and requires the central configuration parameter workFiles.external.file.directory to be set on PrizmDoc server. Please contact info@accusoft.com to obtain a license.

    NOTE: If the video file is modified after the creation of the File ID, consequent GET /api/v1/media/:fileId/video requests will download the modified version.

    Request Header

    Field Type Description
    Content-Type String Must be application/json.

    Request Body

    A JSON object that conforms to the following:

    • type (String) Required. The type of storage. Must be “file”.
    • fileExtension (String) Required. Extension of the video. Supported extensions are .mp4, .ogg, and .webm
    • file (Object) Required. Object containing information of the “file” storage type.
      • path (String) Required. Relative path to the video which should be accessible by the PrizmDoc Server. The video file must be located inside the directory specified in PrizmDoc Server's workFiles.external.file.directory central configuration parameter.

    Example:

    {
        "type": "file",
        "fileExtension": "mp4",
        "file": {
          "path": "./videos/presentations/video.mp4"
        }
    }
    
    

    Successful Response

    Response Header

    Field Type Description
    Content-Type String application/json.

    Response Body

    A JSON object with the following properties:

    • fileID (String) Identifier associated with local video.

    Example:

    HTTP/1.1 200 OK
    {
      "fileId": "zgOGNBUIjfRHF2g4SNz1_A"
    }
    
    

    Error Responses

    Status Code JSON errorCode Description
    413 FeatureNotLicensed The server is not licensed to use the requested feature or API.
    480 MissingInput Content-Type or object in body is missing.
    480 InvalidInput Unsupported file extension.
    480 ExternalContentNotFound The file specified in the path does not exist or is not accessible.
    480 IncorrectUsage workFiles.external.file.directory has not been configured in PrizmDoc Server, an absolute path has been provided for the file, or the relative path points outside of the directory specified in workFiles.external.file.directory.

    413 FeatureNotLicensed

    HTTP/1.1 413 FeatureNotLicensed
    {
      "errorCode": "FeatureNotLicensed",
      "errorDetails": "The server's license does not allow the use of the requested feature or API."
    }
    
    

    480 MissingInput

    HTTP/1.1 480 MissingInput
    {
      "errorCode": "MissingInput",
      "errorDetails": {
       "in": "body",
       "at": "file",
       "expected": {
         "type": "object"
        },
        "when": [
          {
            "otherInput": {
              "in": "body",
              "at": "type",
              "is": {
                "value": "file"
              }
            }
          }
        ]
      }
    }
    
    

    480 InvalidInput

    HTTP/1.1 480 InvalidInput
    {
      "errorCode": "InvalidInput",
      "errorDetails": {
        "in": "body",
        "at": "fileExtension",
        "expected": {
          "oneOf": [
            {
              "value": "mp4"
            },
            {
              "value": "webm"
            },
            {
              "value": "ogg"
            }
          ]
        }
      }
    }
    
    

    480 ExternalContentNotFound

    HTTP/1.1 480 ExternalContentNotFound
    {
      "errorCode": "ExternalContentNotFound"
    }
    
    

    480 IncorrectUsage

    HTTP/1.1 480 IncorrectUsage
    {
      "errorCode": "IncorrectUsage"
    }