Routes

The API currently only provides one route, POST /process3dPicture.

/process3dPicture

Send a picture for processing. Parameters must be sent via a JSON object as follows:

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

Parameters

  • apiKey: API key
  • input.url: a URL from which we the API can download the source picture. Note that only PNG pictures are currently supported
  • output.hook: a URL to which the API will send the asynchronous result (cf below)
  • configName: name of the configuration to be used, as listed in your dashboard

Note that pictures must be properly oriented: the top must point towards the top, not to the left or right (or bottom, to a lesser extent). Unlike flat prints, 3D prints must be printed in the same orientation as the picture will be physically viewed, otherwise the 3D effect won’t work. An upside-down picture will have working 3D, but the depth map will likely be degraded.

Synchronous return

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

{
  "result": "ok"
}

or for instance:

{
  "result": "error",
  "error": {
    "code": "FILE_NOT_FOUND",
    "description": "Couldn't download the file https://example.com/picture.png",
    "details": ""
  }
}

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 follow:

{
  "result": "ok",
  "data": {
    "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": {
    "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 60 minutes.

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