Web API

🍀

Helpful note:

We created a simple React app implementation on GitHub for helping people with an quicker/easier implementation. Link here: https://github.com/Kaedim/API_Implementation

Credentials

In order to use the Kaedim API you will need a devID, an API-key and a refresh token. You can find all three of those by logging in to the web app at https://app.kaedim3d.com and navigating to Settings > API Settings. There you should be able to see all the necessary details. If your keys are not working for any reason don’t hesitate to contact us at support@kaedim3d.com

Step 1: Registering a webhook

To register a webhook endpoint you will need your API key and developer ID, which can be both found under your user setting page inside the Kaedim platform.

Your API key should always be provided in the X-API-Key Header in your post requests.

Register a webhook

Example of registering a webhook using node.js

POST	https://api.kaedim3d.com/api/v1/registerHook

Parameters

Name

Requirement

Section

Type

Description

X-API-Key

Required

Head

String

User API key used to authenticate requests

devID

Required

Body

String

Your developer ID

destination

Required

Body

String

Your webhook endpoint url

🗒️

Please note that the following code is Node.js


import fetch from "node-fetch"
const url = "https://api.kaedim3d.com/api/v1/registerHook"
const headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}
const body = {
    'devID': 'your_dev_id',
    'destination': 'your_endpoint_url'
}
try {
    fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}

🗒️

Please note that the following responses are in JSON

200 response


{
    "status": "success",
    "userID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "sessionExpireAt": "2022-02-14T14:06:16Z"
    "jwt":"eyJhbGciOiJIUzI1…"
    "refreshToken":"adghad9as7aewn89…"
}

200

201 response


{
    "status": "success",
    "message": "Endpoint is already registered"
    "sessionExpireAt": "2022-02-14T14:06:16Z"
    "jwt" : "eyJhbGciOiJIUzI1…"
}

201

404 response


{
    "status": "error",
    "message": "Invalid 'devID'"
}

404

Upon successful authentication you will receive a JWT, which needs to be added as a Bearer Token header on all processing requests. You will also receive a refreshToken to be used to generate a new JWT.

Your JWT will expire after 12 hours, see below for how to refresh your token.

Step 2: Processing an image

All processing requests must include the JWT in the Bearer Authorization header, alongside your API-key, and your devID inside the request body. We also support high-detail requests using the high-detail parameter.

Post processing request

Example of sending a processing request in node.js

POST	https://api.kaedim3d.com/api/v1/process

POST TABLE

Parameters

Name

Requirement

Section

Type

Description

X-API-Key

Required

Head

String

User API key used to authenticate requests

Authorization

Required

Head

String

Your valid JWT

devID

Required

Body

String

Your developer ID

imageUrls

Required

Body

Array

Any number of images to be processed alternatively you can upload the files themselves

LoQ

Required

Body

String

Level of quality: “standard”/”high”/”ultra”

test

optional

Body

Boolean

Used to process request as a test

polycount

optional

Body

Number

Upper polycount limit

height

optional

Body

Number

Desired height in cm (default 200)

🗒️

Please note that the following code is Node.js


const url = "https://api.kaedim3d.com/api/v1/process"
const headers = {
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}
const formData = new FormData();
formData.append('devID', 'your_devID');
formData.append('imageUrls', [url1,url2]);
formData.append('LoQ', 'standard');
formData.append('polycount', 20000);
formData.append('height', 200);
try {
  fetch(url, {
      method: "POST",
      headers,
      body:formData,
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}

🗒️

Please note that the following responses are in JSON

201 response


{
"status": "success",
"requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
"message" : "request sent successfully, please check webhook  endpoint in 10-15 minutes"
}

201

400 response


{
"status": "error",
"requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
"message" : "Request failed due to {reason}, please check your payload and headers and try again"
}

400

Once the asset has been successfully generated, a download URL will be sent to the registered webhook endpoint.

Please note that you will need to perform a GET request on the URL's to get the file containing the completed asset.

Each completed asset is available in 4 supported formats obj, fbx, glb, gltf, all of which have separate download links in the post request.

Download links expire after an hour.

We also provide the functionality to fetch all requests, see below.

We also provide the option for test requests using a boolean test body parameter. If set to true, a plain empty cube will be returned in the response. We recommend using this to get an idea of the structure of the response once an asset is completed.

Upon successful generation you will receive a response similar to the following:

201 response


{
    "status": "success",
    "userID" : KaedimUser,
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "results" : {
        "obj": "https://....."
        "fbx": "https://....."
        "glb": "https://....."
        "gltf": "https://....."
    }
}

201

400 response


{
    "status": "error",
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "message" : "Asset creation failed"
    "cause" : "The request was too complex, we aim to deal with…"
}

400

Asset creation may fail due to various reasons some of which include: complexity, visibility of the object, multiple objects in the scene, inappropriate content etc. Please see our guidelines for more information.

Other useful routes

Check the progress and results of your generation

We provide functionality to check the prograss of your generation based on the requestID

GET	https://api.kaedim.com/api/v1/fetchRequest

Parameters

Name

Requirement

Section

Type

Description

X-API-Key

Required

Head

String

User API key used to authenticate requests

Authorization

Required

Head

String

Your valid JWT

devID

Required

Body

String

Your developer ID

requestID

Required

Body

String

Your requestID

🗒️

Please note that the following code is Node.js


const devID = 'your-devID';
// mm-dd-yy
const start = '02-01-2022';
const end = '02-14-2022';
const url = `https://api.kaedim3d.com/api/v1/fetchRequest`
const headers = {
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}
const body = {
  "devID": "your_devID",
  "requestID":  "your_requestID"
}
try {
   fetch(url, {
      method: "GET",
      headers,
			body: JSON.stringify(body),
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}

🗒️

Please note that the following responses are in JSON

200 response


{
    "requestID": "81...236",
    "createdAt": "202...",
    "image": [
        "https://s...",
    ],
    "image_tags": [],
    "polycount": "20000",
    "iterations": [
        {
            "createdAt": "2023-0...",
            "iterationID": "0",
            "results": {
                "obj": "https://s...",
                "fbx": "https://s...",
                "glb": "https://s...",
                "gltf": "https://s...",
                "mtl": "https://s...",
            },
            "status": "completed",
            "userID": "b6e...",
            "email": "mar...",
            "loq": "standard",
            "dismissedReason": null,
            "editDescription": null,
            "texturingMethod": null
        }
    , ...]
}

200

400 response

Get All Assets

We provide functionality to retrieve all asset requests (even if they’re pending) based on date ranges (if provided).

GET	https://api.kaedim3d.com/api/v1/fetchAll

Parameters

Name

Requirement

Section

Type

Description

X-API-Key

Required

Head

String

User API key used to authenticate requests

Authorization

Required

Head

String

Your valid JWT

devID

Required

Body

String

Your developer ID

start, end

optional

Body

String

Date range provided in MM-DD-YYYY. If left blank all assets associated to the devID will be returned

🗒️

Please note that the following code is Node.js


const devID = 'your-devID';
// mm-dd-yy
const start = '02-01-2022';
const end = '02-14-2022';
const url = `https://api.kaedim3d.com/api/v1/fetchAll`
const headers = {
  "X-API-Key": "your_api_key",
  "Authorization":  "your_JWT"
}
const body = {
  "devID": "your_devID",
  "dates": {start, end}
}
try {
   fetch(url, {
      method: "GET",
      headers,
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}

🗒️

Please note that the following responses are in JSON

200 response


{
    "assets": [
        {
            "requestID": "81...236",
            "createdAt": "202...",
            "image": [
                "https://s...",
            ],
            "image_tags": [],
            "polycount": "20000",
            "iterations": [
                {
                    "createdAt": "2023-0...",
                    "iterationID": "0",
                    "results": {
                        "obj": "https://s...",
                        "fbx": "https://s...",
                        "glb": "https://s...",
                        "gltf": "https://s...",
                        "mtl": "https://s...",
                    },
                    "status": "completed",
                    "userID": "b6e...",
                    "email": "mar...",
                    "loq": "standard",
                    "dismissedReason": null,
                    "editDescription": null,
                    "texturingMethod": null
                }
            ]
        },...
    ]
}

200

400 response


{
    "status": "error",
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "message" : "Request failed, please check your payload, headers and query paramaters and try again"
    "cause": "...."
}

400

Refreshing a JWT

Your web token will expire after 12 hours from its creation. You can only have one JWT valid at a time, therefore creating a new JWT will automatically invalidate the old token. To get a new JWT you must use the refresh token generated at webhook registration. You can find the refresh token in user settings in the Kaedim platform next to the API-key.

Post a refresh request in node.js

If successful you will receive a new JWT that can also be accessed in your user-settings page inside the Kaedim Platform. Please use this to authenticate any future requests.

POST	https://api.kaedim3d.com/api/v1/refreshJWT

Parameters

Name

Requirement

Section

Type

Description

X-API-Key

Required

Head

String

User API key used to authenticate requests

refresh-token

Required

Head

String

Token used to generate more JWT’s

devID

Required

Body

String

Your developer ID

🗒️

Please note that the following code is Node.js


const url = "https://api.kaedim3d.com/api/v1/refreshJWT"
const headers = {
  "Content-Type": "application/json",
  "X-API-Key": "your_api_key",
  "refresh-token": "your-refresh-token"
}
const body = {
'devID': 'your_dev_id',
}
try {
   fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    }).then((res) => {
      res.json().then((data) => {
        console.log(data);
      });
    });
} catch (e) {
}

🗒️

Please note that the following responses are in JSON

200 response


{
    "status": "sucess",
    "message": "JWT refreshed successfully. Please use the new JWT and devID to authenticate your future requests",
    "jwt": "eyJhaU.....",
    "devID": "609d43109ff0b252cce4bc6e"
}

200

400 response


{
    "status": "error",
    "requestID": "1248947ds7an-ad98q3yhans92S-2Asda9212",
    "message" : "Request failed, please check your api-key and refresh-token and try again"
    "cause": "...."
}

400

Error codes

We use normal HTTP codes to indicate the success or failure of your API requests. If your request fails, Kaedim will return an appropriate error message.

Field Name	Type	Description
Status	String	Short string describing the status of the request. Generally "success" or "error".
Message	String	Short human-readable string giving more context on the reason the error occurred.
Cause	Optional <object>	Optional cause of the error, for example if the request image has been denied for a specific reason.

< Previous

Next >