Routes

The API currently provides two routes:

/process3dPicture

Send a picture for processing. Due to the time it takes to process a picture (generally between 30s and 3 minutes, depending mostly on print size and DPI), the result is partially asynchronous.

Parameters must be sent via a JSON object as follows:

{
  "apiKey": "myApiKey",
  "input": {
    "url": "https://example.com/picture.png"
  },
  "output": {
    "hook": "https://httpbin.org/post",
    "instantSignedUrl": false,
    "signatureExpirationSeconds": 3600
  },
  "configName": "my-config"
}

Parameters

  • apiKey: API key.
  • input.url: a URL from which the API can download the source picture. Supported formats: PNG and PDF
  • output.hook (optional): a URL to which the API will send the asynchronous result (cf below).
  • output.instantSignedUrl (optional): boolean, if true, a signed URL to the final file will be returned instantly. This URL can be queried later, to get the file once it is ready. Make sure you either set it to true or define a hook, otherwise you won’t have any way to fetch the result.
  • output.signatureExpirationSeconds (optional): integer, how long, in seconds, the signed URL is valid. Applies to both the signed URL from instantSignedUrl and the URL from the hook. Must be between 60 seconds and 2 days (172800 seconds). Default value: 84600 secondes (1 day).
  • configName: name of the configuration to be used, as listed in your dashboard

Synchronous return

The route will first return a "fast" OK or error response as follows:

{
  "result": "ok",
  "data": {
    "requestId": "ZJ6EsQinWPMcmvSkKLiXM8PWAtdaEh7P",
    "outputUrl": "https://some.signed.url/if/instantSignedUrl/is/true"
  }
}

or for instance:

{
  "result": "error",
  "error": {
    "code": "CONFIG_FILE_NOT_FOUND",
    "description": "No config file matching this name",
    "details": "Couldn't find config file someConfigName"
  }
}

Possible error codes at this stage are:

Code Description
MISSING_API_KEY apiKey parameter missing
INVALID_API_KEY Provided API key is invalid
CONFIG_FILE_NOT_FOUND No config file matching this name.
NB: if you have multiple labs, note that each API key will have access to only its lab’s config files
CONFIG_ERROR_PDF_DPI When using PDF outpout, DPI must be the same in X and Y
MISSING_INPUT_PARAMETER One or more input parameters are missing or invalid. The details field will provide a list of missing fields
UNKNOWN_ERROR This shouldn’t happen... but we still have a code for it


Asynchronous return

When the processing is done (or failed), the API will send a POST request with a JSON object to the URL specified in output.hook, with either an OK reponse and a link to download the result picture, or an error response as follows:

{
  "result": "ok",
  "data": {
    "requestId": "ZJ6EsQinWPMcmvSkKLiXM8PWAtdaEh7P",
    "inputUrl": "https://example.com/picture.png",
    "outputUrl": "https://somebucket.s3.amazonaws.com/example.png?AWSAccessKeyId=ABCD&Expires=1618168259&Signature=Cc%2Bletc&x-amz-security-token=averylongstring"
  }
}

or for instance:

{
  "result": "error",
  "data": {
    "requestId": "ZJ6EsQinWPMcmvSkKLiXM8PWAtdaEh7P",
    "inputUrl": "https://example.com/picture.png"
  },
  "error": {
    "code": "PROCESSING_FAILED",
    "description": "Picture processing failed"
  }
}

In case of a success, outputUrl is a signed URL that is valid for output.signatureExpirationSeconds seconds.

Possible error codes at this stage are:

Code Description
FILE_NOT_FOUND Couldn’t download the input file
FILE_TOO_BIG The file is too large (the current limit is 40 MiB)
PROCESSING_FAILED Picture processing failed


/processMultipagePdf

This route is in beta

Send a PDF with multiple pictures (one picture per page) for processing. Currently returns a PDF with multiple interlaced pictures (one picture per page).

Parameters must be sent via a JSON object as follows:

{
  "apiKey": "myApiKey",
  "input": {
    "url": "https://example.com/pictures.pdf"
  },
  "output": {
    "hook": "https://httpbin.org/post",
    "instantSignedUrl": true,
    "signatureExpirationSeconds": 3600
  },
  "configName": "my-config"
}

Note that sending multiple pictures in a single PDF rather than sending individual pictures one by one to POST /process3dPicture incurs significant delays and adds constraints (notably, the input PDF cannot exceed 100 MiB). Using POST /process3dPicture should be preferred whenever possible, particularly if processing single-picture PDFs.

For rate-limiting purposes, a multi-picture PDF is treated as as many requests as the amount of pictures it contains. A large enough PDF might, as a result, not fit into the highest priority queue.

Parameters

  • apiKey: API key
  • input.url: a URL from which the API can download the source PDF.
  • output.hook: a URL to which the API will send the asynchronous result.
  • output.instantSignedUrl (optional): boolean, if true, a signed URL to the final file will be returned instantly. This URL can be queried later, to get the file once it is ready. Make sure you either set it to true or define a hook, otherwise you won’t have any way to fetch the result.
  • output.signatureExpirationSeconds (optional): integer, how long, in seconds, the signed URL is valid. Applies to both the signed URL from instantSignedUrl and the URL from the hook. Must be between 180 seconds and 2 days (172800 seconds). Default value: 84600 secondes (1 day). For the hook, the output URL is signed during picture processing, before the final file is ready. So the lower bound of 180 secondes may be too low if creating large pictures or if your processing queue is full.
  • configName: name of the configuration to be used, as listed in your dashboard. The input PDF file can only contain pictures corresponding to one configuration.

Synchronous return

The route will first return a "fast" OK or error response as follows:

{
  "result": "ok",
  "data": {
    "requestId": "phn48wMVVeE4YZf0f4lAVchsgMBj97JH",
    "outputUrl": "https://somebucket.s3.amazonaws.com/phn48wMVVeE4YZf0f4lAVchsgMBj97JH.zip?AWSAccessKeyId=ABCD&Expires=1632827003&Signature=Cc%2Bletc&x-amz-security-token=averylongstring"
  }
}

or for instance:

{
  "result": "error",
  "error": {
    "code": "MISSING_INPUT_PARAMETER",
    "description": "One or more input parameters are missing or invalid",
    "details": "A mandatory string property is missing (varName=input.url)"
  }
}

Possible error codes at this stage are:

Code Description
MISSING_API_KEY apiKey parameter missing
INVALID_API_KEY Provided API key is invalid
CONFIG_FILE_NOT_FOUND No config file matching this name.
NB: if you have multiple labs, note that each API key will have access to only its lab’s config files
MISSING_INPUT_PARAMETER One or more input parameters are missing or invalid. The details field will provide a list of missing fields
UNKNOWN_ERROR This shouldn’t happen... but we still have a code for it


Asynchronous return

When the processing is done (or failed), the API will send a POST request with a JSON object to the URL specified in output.hook, with either an OK reponse and a link to download the result picture, or an error response as follows:

{
  "result": "ok",
  "data": {
    "requestId": "phn48wMVVeE4YZf0f4lAVchsgMBj97JH",
    "inputUrl": "https://example.com/pictures.pdf",
    "outputUrl": "https://somebucket.s3.amazonaws.com/example.zip?AWSAccessKeyId=ABCD&Expires=1618168259&Signature=Cc%2Bletc&x-amz-security-token=averylongstring"
  }
}

or for instance:

{
  "result": "error",
  "data": {
    "requestId": "phn48wMVVeE4YZf0f4lAVchsgMBj97JH",
    "inputUrl": "https://example.com/pictures.pdf"
  },
  "error": {
    "code": "FILE_TOO_BIG",
    "description": "Input file is too big"
  }
}

In case of a success, outputUrl is a signed URL that is valid for output.signatureExpirationSeconds seconds.

Possible error codes at this stage are:

Code Description
FILE_NOT_FOUND Couldn’t download the input file
FILE_TOO_BIG The file is too large (the current limit is 100 MiB)

At the moment, a failure in the processing of a picture within the PDF will cause the whole PDF to fail, without a return. A future update will change this to return a zip archive with one text file replacing each failed picture.