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@mydidimo.com
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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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.mydidimo.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 fileogg output audio as OGG VORBIS filepcm output audio as PCM filemp3 output audio as MP3 filejson 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
- Didimo Preview interface updated with new optional parameter
filetype
allowing selection of a solid backgroundjpg
or transparent backgroundpng
Changed from
GET /v2/didimo/:key/preview/
to
GET /v2/didimo/:key/preview/(:filetype)
- Updated error codes:
- New error code 19200 - Invalid template
- Pipeline Improvements:
- Improved iris position, coloring and texture
- Improved texture blending on nose
- Increase 1:1 geometric accuracy to the output
Version 2.3.0
- Performance improvements
Version 2.2.0
Didimo Status fix the missing
stt
parameter in the result message.Pipeline Improvements:
- New skin tone color matching
- Improved real time rig accuracy and animation robustness
- Improved hair segmentation
- Improved texture blending
- Improved eyes positioning and fitting
- Improved eyelash removal
Version 2.1.1
- Didimo New when input_type is
photo
, the input image has a limit of 8MP (8388608 pixels) regardless of image geometry.
Version 2.1
Didimo New interface changed and now requires the paramenter target_platform
Changed from
POST /v2/didimo/new/:type/:template/(:features)
to
POST /v2/didimo/new/:input_type/:target_platform/:template/(:features)
Didimo Download interface changed now requires the type becomes mandatory
Changed from
GET /v2/didimo/:key/download/(:type)
toGET /v2/didimo/:key/download/:type
Didimo Status now returns full didimo information see Didimo Object Definition
Didimo List now returns sample didimos at the end of the list and samples_count
Version 2.0
Public release of the API