NAV Navbar
http javascript

Introduction

/*
 preparing the environment and run javascript examples in nodejs
 1. Using the terminal run: `cd <your local client directory>`
 2. run `npm install crypto-js superagent`
 3. copy the file didimoAuth.js to you local client directory 
 4. go to the customer portal (https://app.didimo.co/) and create an Application and API keys
 5. copy the code of the header.js (below) to a local example.js file and replace the API key and API secret
 6. copy the example code to your local example.js
 7. run `node example.js`
*/

//Add this code to the beginning of your local example.js file
//file: header.js
const request = require("superagent")
    , DidimoAuth = require("./didimoAuth.js");

var APIHOST = "https://api.didimo.co";
var didimoAuth = new DidimoAuth({
    key: "<your application public key>",
    secret: "<your application secret key>"
});
// add code from the examples below

Welcome to the Didimo API!

You can use our API to create and interact with your didimos and execute some extra features.

See changes of the latest release here

Authorization

API Key

GET location HTTP/1.1
Authorization: DidimoDigest auth_method="sha256", auth_key="public_key_1a2b3c", auth_nonce="a1234567890", auth_digest="ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb"


//file: didimoAuth.js 
//add this file to your node client folder

const CryptoJS = require("crypto-js");

function DidimoAuth(config){
    this.key = config.hasOwnProperty('key') ? config.key : "";
    this.secret = config.hasOwnProperty('secret') ? config.secret : "";
}

DidimoAuth.prototype.authorizationHeader=function(uri){
    var nonce = new Date().getTime() + Math.random().toString(36).substring(7); //1/50K odds of collision in the same millisecond

    var HA1 = CryptoJS.SHA256(this.key + this.secret);
    var HA2 = CryptoJS.SHA256(this.key + nonce + uri);
    var digest = CryptoJS.HmacSHA256(HA1+HA2, this.secret);

    var authorizationHeader = {
        auth_key:this.key,
        auth_nonce:nonce,
        auth_digest:digest,
        auth_method:'sha256'
    }
    return "DidimoDigest " + Object.entries(authorizationHeader).map( ([k,v]) => k+'="'+v+'"' ).join(', ');
}

module.exports = DidimoAuth;

// don't forget to run `npm install crypto-js superagent`

After generating the API Key in the Customer Portal, the API Key can be used to authorize requests to the Didimo API

The API Key is used by setting the Authorization HTTP header on every request

General Format

Authorization: Scheme (argument="value"(, )?)*

Example

Authorization: DidimoDigest auth_method="sha256", auth_key="public_key_1a2b3c", auth_nonce="a1234567890", auth_digest="ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb"

Authorization parameters

Name Type Example Value Description
Scheme string DidimoDigest Authorization Scheme
auth_method
optional		 string sha256 Algorithm used in the digest. Must be one of:
sha256(default)
sha1
auth_key string pub_Auv2jiNh9_V4BPJrV... Public key for your application
auth_nonce string a1234567890 Single use number generated from client on every request
auth_digest string ca978112ca1.... Digest generated on client
example pseudo code on the right		 
# plus sign means concatenation
HASH1 = hash(auth_key + secret_key)
HASH2 = hash(auth_key + auth_nonce + auth_uri)
DIGEST = hash_hmac( HASH1 + HASH2, secret_key )

Other Methods

If you need another means of authentication/authorization, please contact using the email address support@didimo.co

Profile

Profile

The profile endpoint returns basic information, like the account tier, points information and available features related with the account.

Request

GET /v2/profile HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var endpoint = "/v2/profile";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body);
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "points": 10,
  "tier_code": "trial",
  "tier_label": "Trial",
  "next_expiration_date": "2020-10-18 00:00:00",
  "next_expiration_points": 10,
  "available_features": [
    "basic",
    "vertexdeform"
  ]
}

{
  "stt": "OK",
  "points": 10,
  "tier_code": "trial",
  "tier_label": "Trial",
  "next_expiration_date": "2020-10-18 00:00:00",
  "next_expiration_points": 10,
  "available_features": [
    "basic",
    "vertexdeform"
  ]
}

HTTP Request

GET /v2/profile

Query Parameters

NONE

Success Response Object

Name Type Example Value Description
stt string OK Request Status
points integer 4 Available points in your account
tier_code string trial Tier code of your account. See Packages Details
tier_label string Trial Tier code label (formatted)
next_expiration_date string 2020-10-18 00:00:00 Expiration date of the expiring batch
next_expiration_points string 4 Points expiring at next_expiration_date
available_features string[] ["basic","geometry_objs"] Array containing a string per available feature on the account

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Didimo

New

Request

POST /v2/didimo/new/photo/maya/2.0/expressions,visemes HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>
Content-Type: multipart/form-data; boundary=<<boundary>>
Accept: application/json

--<<boundary>>
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

(binary of photo.jpg)
--<<boundary>>--

// See #introduction for instructions
var input_file = '<photo_location>';
var input_type = 'photo';
var target_platform = 'maya';
var template = "2.0";
var optional_features = "basic"; //optional

var endpoint = "/v2/didimo/new/"+input_type+"/"+target_platform+"/"+template+"/"+optional_features;
request
    .post(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .attach('file', input_file)
    .end((err, res) => {
        console.log(res.body);
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "key": "<didimo_key>"
}

{
  "stt": "OK",
  "key": "<didimo_key>"
}

Uploads a photo/model and starts processing using Didimo pipeline.

HTTP Request

POST /v2/didimo/new/:input_type/:target_platform/:template/(:features)

Query Parameters

Name Type Allowed Values Description
input_type string photo
lofimesh_texture
hifimesh_texture_photo		 Type of resource uploaded (see Input Types Table)
target_platform string comma separated values:
maya
webviewer
unity
Default: maya		 Type of output required (see Target Platforms Table)
template string 1.6
2.0		 Template version
features
optional		 string comma separated values:
basic
expressions
visemes
Default: empty		 Extra features for your didimo (see Features Table)

Input Types

Type Type Content-Type Description
photo file image/jpeg Your input is a photo.
The input has a limit of 8MP (8388608 pixels) regardless of image geometry.
lofimesh_texture file application/x-zip Your input is a zip file containing a model of a human head (mesh.obj) and texture (mesh.jpg)
Tested only for Sony 3D creator). See Notes
hifimesh_texture_photo file application/x-zip Your input is a zip file containing a photogrammetry model of a human head (mesh.obj) and texture (mesh.png) taken with eyes closed, and an additional front facing photo with eyes open (photo.jpg). See Notes

Target Platforms

Name Description
maya the output will be a zip file containing a fbx model and related assets for edit time
Alias: zip
webviewer the output will be a zip file containing a fbx model and related assets for realtime
unity the output will be a zip file containing a json model and related assets for realtime
Alias: unityzip

Features

Name Description
basic support for basic animation
expressions support for facial expressions
visemes support for speech animations

Request Content-Type Header

Content-Type: multipart/form-data

Request Body Contents

See the examples on the right on how to build the request.

Success Response Object

Name Type Example Value Description
stt string OK Request Status
key string bx05aceflpsituwxss Didimo Key

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Status

Request

GET /v2/didimo/<didimo_key>/status HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/status";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "key": "<didimo_key>",
  "is_public": 1,
  "is_sample": 1,
  "error_code": 0,
  "template_version": "2.0",
  "optional_features": "tier_trial",
  "created_by": "i-01db4b6802db98d48",
  "percent": 100,
  "type": "photo",
  "created_at": "2020-04-27 18:25:05",
  "updated_at": "2020-04-27 18:26:35",
  "status": "done",
  "meta": [
    {
      "name": "supports-deformation",
      "value": "didimovertex3",
      "defined": "recipemeta"
    }
  ]
}

{
  "stt": "OK",
  "key": "<didimo_key>",
  "is_public": 1,
  "is_sample": 1,
  "error_code": 0,
  "template_version": "2.0",
  "optional_features": "tier_trial",
  "created_by": "i-01db4b6802db98d48",
  "percent": 100,
  "type": "photo",
  "created_at": "2020-04-27 18:25:05",
  "updated_at": "2020-04-27 18:26:35",
  "status": "done",
  "meta": [
    {
      "name": "supports-deformation",
      "value": "didimovertex3",
      "defined": "recipemeta"
    }
  ]
}

Check status of a didimo in our pipeline, and returns a Didimo Object: Didimo Object Definition

This endpoint is also used to check status of an Execute request.

HTTP Request

GET /v2/didimo/:key/status

Query Parameters

Name Type Example Value Description
key string bx05aceflpsituwxss A didimo key provided by New, List, or Execute

Success Response Object

Didimo Object: Didimo Object Definition

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

List

Request

GET /v2/didimo/list HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var endpoint = "/v2/didimo/list";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body);
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "total_list_size": 14,
  "samples_count" : 1,
  "ttl": 3,
  "next": "\/didimo\/list\/cursor\/oxB58XxpsKsMFLt281Ma",  
  "update": "\/didimo\/list\/update\/PGzdWRFLtsdaFSaf212X",
  "models": [
    {
      "key": "<didimo_key>",
      "is_public": 1,
      "is_sample": 0,
      "error_code": 0,
      "template_version": "2.0",
      "optional_features": "tier_trial",
      "created_by": "i-01db4b6802db98d48",
      "percent": 100,
      "type": "photo",
      "created_at": "2020-04-27 18:25:05",
      "updated_at": "2020-04-27 18:26:35",
      "status": "done",
      "meta": [
        {
          "name": "supports-deformation",
          "value": "didimovertex3",
          "defined": "recipemeta"
        }
      ]
    },
    {...more didimos...}
}

{
  "stt": "OK",
  "total_list_size": 14,
  "samples_count" : 1,
  "ttl": 3,
  "next": "\/didimo\/list\/cursor\/oxB58XxpsKsMFLt281Ma",  
  "update": "\/didimo\/list\/update\/PGzdWRFLtsdaFSaf212X",
  "models": [
    {
      "key": "<didimo_key>",
      "is_public": 1,
      "is_sample": 0,
      "error_code": 0,
      "template_version": "2.0",
      "optional_features": "tier_trial",
      "created_by": "i-01db4b6802db98d48",
      "percent": 100,
      "type": "photo",
      "created_at": "2020-04-27 18:25:05",
      "updated_at": "2020-04-27 18:26:35",
      "status": "done",
      "meta": [
        {
          "name": "supports-deformation",
          "value": "didimovertex3",
          "defined": "recipemeta"
        }
      ]
    },
    {...more didimos...}
}

Provide a paged list of didimos on your account. The response of this method also provides the links to get the next page and updates of the didimo list.

HTTP Request

First Request

GET /v2/didimo/list

Subsequent Requests

to continue/update current lists, this request Local URI is provided by the previous requests
GET /v2/didimo/list/:type/:code

Query Parameters (First Request)

NONE

Query Parameters (Subsequent Requests)

These parameters are provided by the previous requests in the form of a local URI to the API.

Name Type Example Value Description
type string cursor Type of page to request:
cursor - next/previous page
update - full update list
code string oxB58XxpsKsMFLt281Ma Cursor code, provided by previous requests

Success Response Object

Name Type Example Value Description
stt string OK Request Status
total_list_size integer 66 Number of didimos in the complete list
samples_count integer 1 Number samples in the complete list
next
optional		 string /didimo/list/cursor/oxB58XxpsKsMFLt281Ma Request cursor for next page
Only returned if there are more didimos after this page
previous
optional		 string /didimo/list/cursor/PGzdWRFLtsdaFSaf212X Request cursor for previous page
Only returned if there are more didimos before this page
ttl integer 3 Recommended seconds to wait before calling the URI in update
update string /didimo/list/update/Ky1ZaPGzdWRf0UxnJ6qz Request link to get the updates to global list
models array `Didimo[] The list of didimos, Didimo Object Definition below

Didimo Object Definition

Name Type Example Value Description
key string bx05aceflpsituwxss Didimo Key
is_public boolean 0 Is this didimo visible outside of your account
is_sample boolean 0 Is this didimo a sample
error_code integer 0 Internal error code for support purposes
template_version string 2.0 The template chosen when the didimo was generated
optional_features string expressions,visemes The extra features chosen when created
created_by string i-da24faa Internal creator instance for support purposes
percent integer 100 Integer value from 0 to 100 representing the percentage of execution
type string photo Type of resource uploaded. See New
created_at string 2020-04-22 16:55:30 Date of submission
updated_at string 2020-04-22 16:55:32 Date of last change
status string done Status can have the values:
pending
processing
error
done
meta array `Meta[] List of meta objects containing user provided information and pipeline generated information! See Meta for more details

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Download

Request

GET /v2/didimo/<didimo_key>/download HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";
var download_type = 'maya'; //optional

var endpoint = "/v2/didimo/"+didimo_key+"/download/"+download_type;
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "ttl": 300,
  "location": "https:\/\/storage.didimo.co\/didimo\/bxa74f..."
}


{
  "stt": "OK",
  "ttl": 300,
  "location": "https:\/\/storage.didimo.co\/didimo\/bxa74f..."
}

Returns the Pre-authorized link to download the didimo package which can be used on your application.

This endpoint is also used to download the assets generated using Execute.

HTTP Request

GET /v2/didimo/:key/download/:type

Query Parameters

Name Type Example Value Description
key string bx05aceflpsituwxss A didimo key provided by New, List, or Execute
type
optional		 string maya Type of download requested:
maya - default for most applications
webviewer - for web applications using the didimo web viewer. Contains model in FBX format and realtime rig in json format, and all required textures.
unity - for Unity, to be loaded using the didimo SDK. Contains model and realtime rig in json format, and all required textures.

Success Response Object

Name Type Example Value Description
stt string OK Request Status
ttl integer 300 Duration of the download link in seconds
location string https://storage.didimo.co/didimo/bxa74f... Pre-authorized link to download the requested package

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Preview

Request

GET /v2/didimo/<didimo_key>/preview HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/preview";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "ttl": 300,
  "location": "https:\/\/storage.didimo.co\/didimo\/bxa74f..."
}


{
  "stt": "OK",
  "ttl": 300,
  "location": "https:\/\/storage.didimo.co\/didimo\/bxa74f..."
}

Returns the Pre-authorized link to download a front render preview image

HTTP Request

GET /v2/didimo/:key/preview/(:filetype)

Query Parameters

Name Type Example Values Description
key string bx05aceflpsituwxss A didimo key provided by New, List, or Execute
filetype
optional		 string jpg default
png		 File type of the preview image:
jpg - solid background
png - transparent background

Success Response Object

Name Type Example Value Description
stt string OK Request Status
ttl integer 300 Duration of the download link in seconds
location string https://storage.didimo.co/didimo/bxa74f... Pre-authorized link to download the requested preview image

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Delete

Request

GET /v2/didimo/<didimo_key>/delete HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/delete";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK"
}

{
  "stt": "OK"
}

Deletes a didimo.

HTTP Request

GET /v2/didimo/:key/delete

Query Parameters

Name Type Example Value Description
key string bx05aceflpsituwxss A didimo key provided by New, List, or Execute

Success Response Object

Name Type Example Value Description
stt string OK Request Status

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

On demand features

Execute blendshapes

Request

GET /v2/didimo/<didimo_key>/execute/blendshapes HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/execute/blendshapes";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body);
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "key": "<didimo_key@child_key>"
}


{
  "stt": "OK",
  "key": "<didimo_key@child_key>"
}

Produce separate OBJ meshes of each individual blendshape using an existing didimo.
Requires a target didimo that was created using the expressions component.
Requires a target didimo with status:done. See Status.

HTTP Request

GET /v2/didimo/:key/execute/blendshapes

Query Parameters

Name Type Example Value Description
key string bx05aceflpsituwxss A didimo key provided by New, List

Success Response Object

Name Type Example Value Description
stt string OK Request Status
key string <didimo_key@child_key> Result Key - You can use this key on Status and Download

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Execute vertexdeform

Request

POST /v2/didimo/<didimo_key>/execute/vertexdeform HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>
Content-Type: application/didimo-vertex

<32bit floats>

// See #introduction for instructions
var didimo_key = "<didimo_key>";
var vertex_file = require('fs').readFileSync('<vertex_file_location>');

var endpoint = "/v2/didimo/"+didimo_key+"/execute/vertexdeform";
request
    .post(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .type('application/didimo-vertex')
    .send(vertex_file)
    .end((err, res) => {
        console.log(res.body);
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "key": "<didimo_key@child_key>"
}


{
  "stt": "OK",
  "key": "<didimo_key@child_key>"
}

Deform the vertex of a model to match the shape of the didimo

This action requires a didimo with status:done. See Status.

The vertex file must be produced by your application! To do that, extract the vertex list from the desired asset and convert to a 32bit float array little-endian where each float represents a coordinate value of a vertex, and each 3 floats represents a vertex; the resulting file must have a multiple of 12 bytes of size in the following format: XXXXYYYYZZZZXXXXYYYYZZZZXXXXYYYYZZZZ...

Check out the Step by Step Guide on how to implement asset deformation on your application.

HTTP Request

POST /v2/didimo/:key/execute/vertexdeform

Query Parameters

Name Type Example Value Description
key string bx05aceflpsituwxss A didimo key provided by New, List

Request Content-Type Header

Content-Type: application/didimo-vertex

Request Body

32bit float array little-endian where each float represents a coordinate value of a vertex, and each 3 floats represents a vertex; the resulting file must have a multiple of 12 bytes of size in the following format: XXXXYYYYZZZZXXXXYYYYZZZZXXXXYYYYZZZZ...

Success Response Object

Name Type Example Value Description
stt string OK Request Status
key string <didimo_key@child_key> Result Key - You can use this key on Status and Download

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Meta

Get

Retrieve the didimo meta information

Request

GET /v2/didimo/<didimo_key>/meta/get HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/meta/get";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body.meta)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "meta": [
    {
      "name": "supports-deformation",
      "value": "didimovertex3",
      "defined": "recipemeta"
    },
    {
      "name": "Name",
      "value": "This is a custom name"
    }
  ]
}

{
  "stt": "OK",
  "meta": [
    {
      "name": "supports-deformation",
      "value": "didimovertex3",
      "defined": "recipemeta"
    },
    {
      "name": "Name",
      "value": "This is a custom name"
    }
  ]
}

HTTP Request

GET /v2/didimo/:key/meta/get(/:name)

Query Parameters

Name Type Example Value Description
key string bx05aceflpsituwxss A didimo key provided by New, List
name
optional		 string "" The meta information to get, if not set, the endpoint returns all available

Success Response Object

Name Type Example Value Description
stt string OK Request Status
models array Meta[] The list of meta information, Meta Object definition below

Meta Object Definition

Name Type Example Value Description
name string supports-deformation Name of the meta information
value string didimovertex3 Value of the meta information
defined string recipemeta Internal creator of this meta

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Set

Set custom meta information on a didimo

Request

GET /v2/didimo/<didimo_key>/meta/set/CustomName/CustomValue HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/meta/set/CustomName/CustomValue";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK"
}

{
  "stt": "OK"
}

HTTP Request

GET /v2/didimo/:key/meta/set/:name/:value

Query Parameters

Name Type Allowed Values Description
key string bx05aceflpsituwxss A didimo key provided by New, List
name string The meta name to set, if already set, will be replaced
value string The meta value to set

Success Response Object

Name Type Example Value Description
stt string OK Request Status

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Set Multiple

Request

POST /v2/didimo/<didimo_key>/meta/set HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>
Content-Type: application/json

{
    "Favourite":"Frogger",
    "Planet":"Alpha Centauri"
}


// See #introduction for instructions
var didimo_key = "<didimo_key>";
var meta = {
   "Favourite":"Frogger", //custom name-value pair
   "Planet":"Alpha Centauri" //custom name-value pair
};

var endpoint = "/v2/didimo/"+didimo_key+"/meta/set";
request
    .post(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .send(meta)
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK"
}

{
  "stt": "OK"
}

Set multiple meta information at once, using a JSON message

HTTP Request

POST /v2/didimo/:key/meta/set

Request Content-Type Header

Content-Type: application/json

Request Body Contents

{ "meta_name_1": "meta_value_1", "meta_name_2": "meta_name_2", ..., "meta_name_n": "meta_name_n" }

Success Response Object

Name Type Example Value Description
stt string OK Request Status

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Unset

Request

GET /v2/didimo/<didimo_key>/meta/unset/CustomName HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>

// See #introduction for instructions
var didimo_key = "<didimo_key>";

var endpoint = "/v2/didimo/"+didimo_key+"/meta/set/CustomName";
request
    .get(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .end((err, res) => {
        console.log(res.body)
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK"
}

{
  "stt": "OK"
}

Remove meta information from didimo

HTTP Request

POST /v2/didimo/:key/meta/unset/:name

Query Parameters

Name Type Allowed Values Description
key string bx05aceflpsituwxss A didimo key provided by New, List
name string The meta information to unset

Success Response Object

Name Type Example Value Description
stt string OK Request Status

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Speech

Text-to-Speech

Create audio and animation visemes from a string.

This endpoint uses Amazon Polly Service. For more information go to What Is Amazon Polly.

Request

POST /v2/speech/tts/wav,json HTTP/1.1
Host: api.didimo.co
Authorization: <Check authorization section>
Content-Type: application/json

{
  "text": "Hello! My name is Eva. Glad to meet you!",
  "type": "text",
  "voice": "Amy"
}

// See #introduction for instructions
var required_types = "mp3,json";
var tts_input = {
    "text":"Hello! Welcome to the Didimo API!",
    "type":"text", //optional
    "voice":"Amy"  //optional
};

var endpoint = "/v2/speech/tts/"+required_types;
request
    .post(APIHOST+endpoint)
    .set("Authorization", didimoAuth.authorizationHeader(endpoint) )
    .set("User-Agent", "Your awesome application device" )
    .send(tts_input)
    .end((err, res) => {
        console.log(res.body);
    });

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "stt": "OK",
  "audioURL": "https://storage.didimo.co/speech/tts_5ea71643...",
  "audio_type": "audio\/mpeg",
  "audio_location": "https://storage.didimo.co/speech/tts_5ea71643...",
  "marksURL": "https://storage.didimo.co/speech/tts_5ea71643...",
  "visemes_type": "application\/x-json-stream",
  "visemes_location": "https://storage.didimo.co/speech/tts_5ea71643..."
}

{
  "stt": "OK",
  "audioURL": "https://storage.didimo.co/speech/tts_5ea71643...",
  "audio_type": "audio\/mpeg",
  "audio_location": "https://storage.didimo.co/speech/tts_5ea71643...",
  "marksURL": "https://storage.didimo.co/speech/tts_5ea71643...",
  "visemes_type": "application\/x-json-stream",
  "visemes_location": "https://storage.didimo.co/speech/tts_5ea71643..."
}

HTTP Request

POST /v2/speech/tts/:mode

Query Parameters

Name Type Example Value Description
mode string pcm,json The type of outputs desired:
wav output audio as WAV RIFF file
ogg output audio as OGG VORBIS file
pcm output audio as PCM file
mp3 output audio as MP3 file
json output JSON visemes file

values may be combined as a comma separated values string, but only the last audio format will be used.

Request Content-Type Header

Content-Type: application/json

Request Body Parameters

Name Type Example Value Description
text string Hello! I'am a Didimo! The text to be converted to audio and/or visemes
type string text Type of input text:
text - simple text input
ssml - Generating Speech from SSML Documents
voice string Brian Voice from Voices in Amazon Polly

Success Response Object

Name Type Example Value Description
stt string OK Request Status
ttl integer 300 Duration of the download link
audio_type
optional		 string audio/mpeg Mime-type of the audio files if available
audio_location
optional		 string https://storage.didimo.co/speech/tts_5ea71643... Pre-authorized link to download the audio file
audioURL
optional,alias for audio_location		 string https://storage.didimo.co/speech/tts_5ea71643... (same as audio_location) Pre-authorized link to download the audio file
visemes_type
optional		 string application/x-json-stream Mime-type of the visesmes files if available
visemes_location
optional		 string https://storage.didimo.co/speech/tts_5ea71643... Pre-authorized link to download the visemes file
marksURL
optional,alias for visemes_location		 string https://storage.didimo.co/speech/tts_5ea71643... Pre-authorized link to download the visemes file

Error Response Object

Name Type Example Value Description
stt string NOK Request Failed
msg string 12345 This is an error message Error details Full Error Table

Errors

The Didimo API uses the following error codes:

200 OK

The request is successful, but the process had an error. This kind of errors only happen using the Didimo Status endpoint

Http Error Message Error Meaning
200 100xx Error in pipeline with code {code}
200 40010 Recipe: cannot find output
200 40011 Recipe: cannot find output

400 Bad Request

The request fails because some parameter is malformed or not available.

Http Error Message Code Meaning
400 10000 Error getting list
400 10001 Field Validation Errors
400 11101 Cannot get credit information
400 12801 Upload mode not supported
400 12803 Feature not supported: {feature}
400 12804 Feature not available: {feature on demand}
400 12805 Feature not available: {feature}
400 14700 Error creating user
400 14701 Error creating user
400 14710 Error creating user
400 14711 Error authenticating user
400 19100 Invalid template
400 19101 Invalid template
400 19102 Invalid template
400 19103 Invalid template
400 23544 Asset not available
400 30001 No files found
400 30002 File input error
400 30002 mesh.jpeg not found in archive
400 30003 mesh.obj not found in archive
400 30005 Archive is empty or invalid
400 30006 Archive must be zip or rar
400 30010 Invalid input for autodetect
400 30011 Invalid input - not an image
400 30012 Invalid input - not a valid format
400 30013 Invalid input - not a valid format
400 30014 Invalid input - image has more than 8388608 pixels
400 30600 Can't parse vertex file
400 30601 Can't parse vertex file
400 30603 Matrix not found - this didimo does not support extra
400 33201 Action not authorized!
400 40005 No recipe for template
400 40005 No recipe for template
400 40006 Error with recipe for template
400 40007 Error with recipe for template
400 40101 Invalid file name
400 40110 Malformed parameters
400 40241 Can't reset didimo
400 40446 No file vertex found in input
400 40460 Asset type not supported
400 41111 Invalid key
400 50004 Invalid cursor
400 50005 Invalid cursor
400 50006 Invalid list request
400 50007 Error requesting sample didimos
400 50008 Error requesting sample didimos
400 51006 Invalid list request
400 51200 Invalid timestamp
400 51300 Invalid option
400 75005 /execute can only be called on requests when status=done
400 75006 Cannot read input
400 99998 Error with configuration or parameters
400 99999 Error with configuration or parameters

401 Unauthorized

Http Error Message Code Meaning
401 00000 Cannot authenticate
401 10032 Authentication Fail
401 10040 Cannot authenticate
401 10041 Invalid bearer token
401 10043 Invalid bearer token
401 11100 Error in session
401 11111 User is not authenticated
401 14703 User email not confirmed
401 14704 Incorrect credentials
401 14705 Incorrect credentials
401 14706 Incorrect credentials
401 14730 Incorrect credentials

402 Payment Required

Http Error Message Code Meaning
402 33200 Not enough Didimo points. Please buy more at the Customer

404 Not Found

Http Error Message Code Meaning
404 10400 Didimo not found
404 10501 Didimo key not found in your account
404 10502 Didimo key not found in your account
404 10503 Didimo key not found in your account
404 40111 Didimo doesn't exist
404 40410 Unknown asset
404 40441 Didimo not found
404 40442 Didimo not found
404 40443 Didimo not found
404 40444 Didimo not found
404 40445 Didimo not found
404 40451 The specified asset does not exist
404 40460 The asset type {type} does not exist on this didimo

Changes

Version 2.4.0

Version 2.3.0

Version 2.2.0

Version 2.1.1

Version 2.1

Version 2.0

Public release of the API

http javascript