Collapse All Expand All

Content Conversion

The content conversion API allows you to convert files from a variety of input formats to several common output formats.

To convert a file:

1. Upload a file you want to use as input using the WorkFile API.
2. Start a conversion operation by using the POST URL below.
3. Check the status of the conversion by (repeatedly) using the GET URL below.
4. When complete, a separate output file will exist which you can download via the WorkFile API.

Available URLs

URL	Purpose
POST /v2/contentConverters	Create and start a content conversion
GET /v2/contentConverters/{processId}	Get the status of a content conversion

Note that these URLs begin with /v2, not /PCCIS/V1.

POST /v2/contentConverters

Creates a new contentConverter resource which represents the conversion process and begins converting an input file which you have previously uploaded using the WorkFile API. A successful response will include a unique processId which identifies this contentConverter. You will use this processId in subsequent GET calls to get the status and final results of the conversion.

Request Headers

Name	Value	Details
Content-Type	application/json	required

Request Body

At a high level, your request body should be JSON containing an input object with details about the src and dest for the conversion.

Here is a minimal example:

POST http://localhost:18681/v2/contentConverters
Content-Type application/json
{
    "input": {
        "src": { 
            "fileId": "ek5Zb123oYHSUEVx1bUrVQ" 
        },
        "dest": {
            "format": "pdf"
        }
    }
}

Additional options are available. Here is the full reference:

input.src

The input.src object specifies the file to use as input.

Name	Description	Details
input.src.fileId	The id of the WorkFile to use as input. See Supported Input File Formats	string, required Example: "ek5Zb123oYHSUEVx1bUrVQ"

input.dest

The input.dest object specifies the destination file format and any additional details which control how the content is converted.

Name	Description	Details
input.dest.format	Specifies the output file format. Must be one of the following: "jpeg" "pdf" "png" "svg" "tiff"	string, required
input.dest.jpegOptions	Additional options when input.dest.format is "jpeg".	object, optional
input.dest.pdfOptions	Additional options when input.dest.format is "pdf".	object, optional
input.dest.pngOptions	Additional options when input.dest.format is "png".	object, optional
input.dest.tiffOptions	Additional options when input.dest.format is "tiff".	object, optional

input.dest.jpegOptions

Name	Description	Details
input.dest.jpegOptions.maxWidth	The maximum pixel width of the output image, expressed as a CSS-style string, e.g. "800px". When specified, the output image is guaranteed to never be wider than the specified value and its aspect ratio will be preserved. This is useful if you need all of your output images to fit within a single column.	string, optional Example: "800px"
input.dest.jpegOptions.maxHeight	The maximum pixel height of the output image, expressed as a CSS-style string, e.g. "600px". When specified, the output image is guaranteed to never be taller than the specified value and its aspect ratio will be preserved. This is useful if you need all of your output images to fit within a single row.	string, optional Example: "600px"

input.dest.pdfOptions

Name	Description	Details
input.dest.pdfOptions.forceOneFilePerPage	If true, the conversion process will produce single-page PDF files, one file for each page of content (instead of a single PDF with multiple pages). Setting this option to true is not currently supported when the source format is "tiff". Default is false.	boolean, optional

input.dest.pngOptions

Name	Description	Details
input.dest.pngOptions.maxWidth	The maximum pixel width of the output image, expressed as a CSS-style string, e.g. "800px". When specified, the output image is guaranteed to never be wider than the specified value and its aspect ratio will be preserved. This is useful if you need all of your output images to fit within a single column.	string, optional Example: "800px"
input.dest.pngOptions.maxHeight	The maximum pixel height of the output image, expressed as a CSS-style string, e.g. "600px". When specified, the output image is guaranteed to never be taller than the specified value and its aspect ratio will be preserved. This is useful if you need all of your output images to fit within a single row.	string, optional Example: "600px"

input.dest.tiffOptions

Name	Description	Details
input.dest.tiffOptions.forceOneFilePerPage	When the destination format is "tiff", you must provide a tiffOptions object with a forceOneFilePerPage property which is set to true. We currently only support single-page TIFF output. We expect this may change in a future release, in which case this property would then become optional and use a default value of false. Until then, you must explicitly set this property to true.	boolean, required with a value of true
input.dest.tiffOptions.maxWidth	The maximum pixel width of the output image, expressed as a CSS-style string, e.g. "800px". When specified, the output image is guaranteed to never be wider than the specified value and its aspect ratio will be preserved. This is useful if you need all of your output images to fit within a single column.	string, optional Example: "800px"
input.dest.tiffOptions.maxHeight	The maximum pixel height of the output image, expressed as a CSS-style string, e.g. "600px". When specified, the output image is guaranteed to never be taller than the specified value and its aspect ratio will be preserved. This is useful if you need all of your output images to fit within a single row.	string, optional Example: "600px"

minSecondsAvailable

Allows you to specify a minimum number of seconds in which you can continue to GET the status of this conversion operation after the initial POST has been submitted. The default value is 60, ensuring that you have at least 60 seconds to get the result status of any conversion operation.

Response Body

A successful response will return JSON which contains:

1. The input object submitted in the request, normalized to include default values.
2. Information about the status of the conversion.

Here is an example:

200 OK
Content-Type: application/json
{
    "input": {
        "src": { 
            "fileId": "ek5Zb123oYHSUEVx1bUrVQ" 
        },
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "processing",
    "percentComplete": 0
}

Conversion Status Details

Name	Description	Details
processId	The id of the contentConverter resource which represents the file conversion operation.	string
expirationDateTime	The date and time (in ISO 8601 Extended Format) when the contentConverter resource will be deleted.	string Example: "2015-12-17T20:38:39.796Z"
state	The current state of the conversion process, which will be one of the following: "processing" - The conversion is still in progress. "complete" - The conversion has completed successfully. "error" - The conversion failed due to a problem. For the initial POST, this value will almost always be "processing". Results are typically only available with a subsequent GET.	string
percentComplete	An integer from 0 to 100 that indicates what percentage of the conversion is complete.	integer Example: 0
errorCode	An error code string if a problem occurred during the conversion process.	string Example: "CouldNotConvertFile"

HTTP Status Codes

• 200 OK - The contentConverter was created and the conversion process was started.
• 405 Method Not Allowed - POST was not used.
• 480 - Something was wrong with the request input. Check the response body for details.

GET /v2/contentConverters/{processId}

Gets the status of a content conversion operation and its final output if available.

In general, the response JSON will contain:

1. The input object submitted in the POST request, normalized to include default values.
2. Information about the status of the conversion.
3. Information about the output of the conversion, if available.

Requests can be sent to this URL repeatedly while the state is "processing".

When the state is "complete", the output section will list one or more WorkFile ids for each output file, and the files themselves can be downloaded using the WorkFile API.

Parameters

Name	Description	Details
processId	The processId for a particular contentConverter. This processId was returned in the response for the initial POST.	string, required

Response Body

While processing, the response will return JSON with only the processing details. For example:

200 OK
Content-Type: application/json
{
    "input": {
        "src": { 
            "fileId": "ek5Zb123oYHSUEVx1bUrVQ" 
        },
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "processing",
    "percentComplete": 82
}

Once the processing has completed, the response will return JSON showing the WorkFile id of the output file or files.

If the output format supports multiple pages (e.g. PDF), then only a single output file will be created. For example:

200 OK
Content-Type: application/json
{
    "input": {
        "src": { 
            "fileId": "ek5Zb123oYHSUEVx1bUrVQ" 
        },
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "complete",
    "percentComplete": 100,
    "output": {
        "results": [
            {
                "fileId": "KOrSwaqsguevJ97BdmUbXi"
                "src": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "1-3" }]
            }
        ]
    }
}

If the output format does not support multiple pages (e.g. JPEG), then multiple output files will be created. For example:

200 OK
Content-Type: application/json
{
    "input": {
        "src": { 
            "fileId": "ek5Zb123oYHSUEVx1bUrVQ" 
        },
        "dest": {
            "format": "jpeg"
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "complete",
    "percentComplete": 100,
    "output": {
        "results": [
            {
                "fileId": "N6uDE11Ed6+JQPy0POu+8A",
                "src": [{ "fileId": "mUiXiqsQuevJKO9Swa32Bd", "pages": "1" }]
            },
            {
                "fileId": "+4b6QW90Fb9yjDak+ALFEg",
                "src": [{ "fileId": "mUiXiqsQuevJKO9Swa32Bd", "pages": "2" }]
            },
            {
                "fileId": "Lx/4z8AyJKV5eMjWKsBm5w",
                "src": [{ "fileId": "mUiXiqsQuevJKO9Swa32Bd", "pages": "3" }]
            }
        ]
    }
}

Conversion Status Details

Name	Description	Details
processId	The id of the contentConverter resource which represents the file conversion operation.	string
expirationDateTime	The date and time (in ISO 8601 Extended Format) when the contentConverter resource will be deleted.	string Example: "2015-12-17T20:38:39.796Z"
state	The current state of the conversion process, which will be one of the following: "processing" - The conversion is still in progress. "complete" - The conversion has completed successfully. "error" - The conversion failed due to a problem.	string
percentComplete	An integer from 0 to 100 that indicates what percentage of the conversion is complete.	integer Example: 0
errorCode	An error code string if a problem occurred during the conversion process.	string Example: "CouldNotConvertFile"

Conversion Output Details

Name	Description	Details
output.results	An array of objects, one for each output file created.	object
output.results[n].fileId	The WorkFile id for an output file. Use this id to download the output file using the WorkFile API.	string
output.results[n].src	An array of objects, one for each source file which contributed to this output file (currently this array will only contain a single item, but a future version of the product may allow you to submit multiple input source files).	array
output.results[n].src[n].fileId	The WorkFile id of the source input file (currently this will always be the same as input.src.fileId).	string
output.results[n].src[n].pages	The page or pages used from the source file. This will be a string value using one-based indexing. For example, if the output file represents page 2 of the source document, pages would have a value of "2". If the output file represents all 20 pages of a source document, pages would have a value of "1-20".	string Examples: "1-3" or "2"

HTTP Status Codes

• 200 OK - The contentConverter was created and the conversion process was started.
• 404 Not Found - No contentConverter exists with the given processId. It is possible the contentConverter has expired and is no longer available.
• 405 Method Not Allowed - GET was not used.
• 480 - Something was wrong with the request input. Check the response body for details.

Appendix

Supported Document Types       

For a complete list, refer to Supported Document Types.

 

 

 

---

©2015. Accusoft Corporation. All Rights Reserved.

Send Feedback