Overview

This page explains how to use our RESTful web services. Our web services are very easy to use yet extensible with many configuration options. All requests must be sent over HTTPS and return JSON (unless otherwise specified). If you have any questions or need something that is not accessible via the services listed on this page, please contact us at support@skullscan.com.

Authorization

In order to use any of our web services, you must generate an subscription key using this link: https://www.skullscan.com/developers/signup

Once you have submitted the form above, you will be emailed a subscription key. In order to use any of our web services, you must provide this key in the header of all your requests.

Here is the format for the authorization header key/pair: 

{
“Authorization”: “APIKEY your-subscription-key-string”}

Paste your subscription key here to automatically fill in all the example requests on this page:

submit

Free vs Paid Plans

Once you sign up as a Skullscan developer, you will automatically be put in the Free tier. The Free tier will limit you to 25 new avatars/month and each avatar will have a small watermark on the forehead. To remove the watermarks or to generate more than 25 avatars/month, you must upgrade to a paid plan. View more information about our paid plans here: https://www.skullscan.com/#plans

Queue Mechanism

Our avatar generation pipeline has a built in queue mechanism. For the most part, your avatars generation requests should start right away and skip the queue. In the case that our servers receive a large spike in avatar generation requests, you may notice that your avatar has been added to the queue (Status will be "queued" and you will have a Queue-Position parameter). The Queue-Position parameter is exactly how many avatars are ahead of yours, waiting to generate.

Avatar API

Generating a new avatar

Generate a new avatar from a single photo using a multipart form data request. You must provide this endpoint your subscription key (more info), a front facing picture of a person’s face (more info), as well as a JSON file containing all your configuration options (more info).

URL: https://api.skullscan.com/v1/avatars
Method: POST

Header

{ "Authorization": "APIKEY your-subscription-key-string", "Content-Type": "multipart/form-data" }

bold params are required

Body

{ "Photo": "your-photo", "Configuration": "your-json-config" }

bold params are required

Example Code

Request Photo

Request JSON Config

{ "Gender": "male", "User-ID": "demo.user@skullscan.com", "Create-Textures": true, "Texture-Resolution": 512, "Sharpen-Textures": true, "Create-Beard": true, "Create-Mouth": false, "Skin-Details": [ "wrinkles" ], "Blendshapes": "none" }

bold params are required

// USE CURL TO DOWNLOAD THE EXAMPLE PHOTO AND CONFIG FILE

curl -O https://www.skullscan.com/images/example-photo.jpg -O https://www.skullscan.com/json/example-config.json

cURL
Python
NodeJS

// SEND A MULTIPART FORM-DATA POST REQUEST WITH CONFIG FILE AND PHOTO

curl -i -H "Authorization: APIKEY your-subscription-key-string" -F "Configuration=@example-config.json" -F "Photo=@example-photo.jpg" https://api.skullscan.com/v1/avatars

{ “Success”: true, "Avatar-ID": "your-avatar-identification-string" }

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

# THIS EXAMPLE USES THE REQUESTS LIBRARY (INSTALL USING PIP)

import requests

# SEND MULTIPART FORM-DATA POST USING THE REQUESTS LIBRARY

url = 'https://api.skullscan.com/v1/avatars'
headers = {"Authorization":"APIKEY your-subscription-key-string"}
files = {'Configuration': open('example-config.json', 'rb'), 'Photo': open('example-photo.jpg', 'rb')}
r = requests.post(url, headers=headers, files=files)

print(r.text)

{ “Success”: true, "Avatar-ID": "your-avatar-identification-string" }

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

// THIS EXAMPLE USES FS AND REQUEST LIBRARIES (INSTALL USING NPM)

var fs = require('fs');
var request = require('request');

// SEND MULTIPART FORM-DATA POST USING THE REQUEST LIBRARY

request.post( { url: 'https://api.skullscan.com/v1/avatars', headers: { 'Authorization': 'APIKEY your-subscription-key-string' }, formData: { Configuration: fs.createReadStream('example-config.json'), Photo: fs.createReadStream('example-photo.jpg') }, }, function(error, response, body) { console.log(body); } );

{ “Success”: true, "Avatar-ID": "your-avatar-identification-string" }

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

Get information for all avatars

Get information pertaining to all your avatars including status and paths to all the generated assets. You must provide this endpoint with your subscription key.

URL: https://api.skullscan.com/v1/avatars
Method: GET

Request Header

{ "Authorization": “APIKEY your-subscription-key-string” }

bold params are required

Example Code

cURL
Python
NodeJS

// SEND A GET REQUEST

curl -i -X GET -H "Authorization: APIKEY your-subscription-key-string" https://api.skullscan.com/v1/avatars

[ { “Status”: "queued", “Avatar-ID”: "abd7baf9-572e-45a9-963a-df405e62ef3d", Queue-Position”: null, "Timestamp": "2018-10-28 10:06:21" "Gender": “male”, "User-ID": “demo.user@skullscan.com”, "Texture-Resolution": 512, "Create-Textures": true, "Sharpen-Textures": true, "Create-Beard": true, "Create-Mouth": false, "Skin-Details": [ "wrinkles" ], "Blendshapes": "none" }, { “Status”: "generating", “Avatar-ID”: "1d13456f-c600-4c22-9b4b-f4c2b519b3d1", "Timestamp": "2018-10-28 10:05:32" "Gender": “male”, "User-ID": “demo.user@skullscan.com”, "Texture-Resolution": 256, "Create-Textures": true, "Sharpen-Textures": false, "Create-Beard": false, "Create-Mouth": false, "Skin-Details": [], "Blendshapes": "all" }, { “Status”: "done", “Avatar-ID”: "00e371a4-c54f-49ed-b96c-d51a17736596", "Timestamp": "2018-10-28 09:57:43" "Gender": “male”, "User-ID": “demo.user@skullscan.com”, "Texture-Resolution": 256, "Create-Textures": true, "Sharpen-Textures": true, "Create-Beard": true, "Create-Mouth": false, "Skin-Details": [ "wrinkles", "freckles" ], "Blendshapes": "all", "Avatar": { "Input-Photo": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/front_raw.jpg", "Model-File": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/head.obj", "Texture-Files": { "Main": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/color_sharp.jpg", "Wrinkles": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/color_old_man.jpg", "Freckles": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/freckles_overlay.jpg", "Main-Beard": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/color_beard.jpg" }, "Blendshapes-File": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/anim.js" } } ]

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

# THIS EXAMPLE USES THE REQUESTS LIBRARY (INSTALL USING PIP)

import requests

# SEND GET REQUEST USING THE REQUESTS LIBRARY

url = 'https://api.skullscan.com/v1/avatars'
headers = {"Authorization":"APIKEY your-subscription-key-string"}
r = requests.get(url, headers=headers)

print(r.text)

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

// THIS EXAMPLE USES THE REQUEST LIBRARY (INSTALL USING NPM)

var request = require('request');

// SEND GET REQUEST USING THE REQUEST LIBRARY

request.get( { url: 'https://api.skullscan.com/v1/avatars', headers: { 'Authorization': 'APIKEY your-subscription-key-string' }, }, function(error, response, body) { console.log(body); } );

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

Get information for a single avatar

Get all information pertaining to a single avatar including status and paths to all the generated assets. You must provide thie endpoint with your subscription key as well as the avatar ID (as a string in the URL)

URL: https://api.skullscan.com/v1/avatars/Avatar-ID
Method: GET

Request Header

{ "Authorization”: “APIKEY your-subscription-key-string” }

bold params are required

Example Code

cURL
Python
NodeJS

// SEND A GET REQUEST

curl -i -X GET -H "Authorization: APIKEY your-subscription-key-string" https://api.skullscan.com/v1/avatars/Avatar-ID

{ “Status”: "done", “Avatar-ID”: "00e371a4-c54f-49ed-b96c-d51a17736596", "Timestamp": "2018-10-28 09:57:43" "Gender": “female”, "User-ID": “demo.user@skullscan.com”, "Texture-Resolution": 256, "Create-Textures": true, "Sharpen-Textures": false, "Create-Beard": true, "Create-Mouth": false, "Skin-Details": [ "wrinkles" ], "Blendshapes": "all", "Avatar": { "Input-Photo": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/front_raw.jpg", "Model-File": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/head.obj", "Texture-Files": { "Main": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/color.jpg", "Wrinkles": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/color_old_woman.jpg", "Main-Beard": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/color_beard.jpg" }, "Blendshapes-File": "https:\/\/api.skullscan.com\/v1\/avatars\/00e371a4-c54f-49ed-b96c-d51a17736596\/anim.js" } }

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

# THIS EXAMPLE USES THE REQUESTS LIBRARY (INSTALL USING PIP)

import requests

# SEND GET REQUEST WITH A SPECIFIED AVATAR-ID (RECEIVED VIA POST)

url = 'https://api.skullscan.com/v1/avatars/Avatar-ID'
headers = {"Authorization":"APIKEY your-subscription-key-string"}
r = requests.get(url, headers=headers)

print(r.text)

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

// THIS EXAMPLE THE REQUEST LIBRARY (INSTALL USING NPM)

var request = require('request');

// SEND GET REQUEST WITH A SPECIFIED AVATAR-ID (RECEIVED VIA POST)

request.get( { url: 'https://api.skullscan.com/v1/avatars/Avatar-ID', headers: { 'Authorization': 'APIKEY your-subscription-key-string' }, }, function(error, response, body) { console.log(body); } );

Having trouble? Checkout these resources for help: Perfect Picture Guide, Response & Error Codes or contact us.

API Definitions

This section contains all the definitions and possible values for all the API parameters used by our web services.

Legend: acceptable value default value

Avatar-ID

string

Unique 36 character string used to identify each avatar.

User-ID

string

Any string (up to 128 characters) which can be used to identify the user who created the assosciated avatar.

Subscription-Key

string

Your unique subscription key (mandatory in the header of all requests). If you do not have one, sign up now to generate one.

Status

string

The current state of the avatar generation pipeline for a given avatar. If our servers are overloaded, avatar generation requests will have a "queued" status. When the avatar is generating it will have a "generating" status. Once complete, it will have a "done" status. If it fails for any reason, it will have a "failed" status.

queuedgeneratingdonefailed

Queue-Position

int

When our servers are overloaded, your scans may be placed in the queue. The Queue-Position will tell you how many scans are in front of yours in the queue. You can poll the avatar information endpoints for Queue-Position updates (1 request/second maximum)

Gender

string

The gender of the assosciated avatar.

malefemale

Texture-Resolution

int

Specify the resolution in pixels for the base texture.

25651210242048

Sharpen-Textures

bool

Set this to false to disable sharpening the texture. Sharpening is used to improve texture quality from bad input photos.

truefalse

Create-Textures

bool

Set this to false to turn off texture generation

truefalse

Skin-Details

array

Add freckles, wrinkles and and skin details to your avatar’s base texture.

[ wrinkles, freckles]

Create-Mouth

bool

Set this to false to turn off the generation of the mouth

truefalse

Create-Beard

bool

Specify whether or not to include an additional beard texture

truefalse

Blendshapes

string

Include basic face blendshapes.

noneall

Timestamp

string

A timestamp (UTC) that is created as soon as the avatar request is received.

Avatar

object

Object containing paths to all 3D assets for a single avatar.

{

"Input-Photo": "path-to-file", // .jpg file

"Model-Files": { }, // see Model-Files definition for more info

"Texture-Files": { }, // see Texture-Files definition for more info

"Blendshapes-File": "path-to-file" // .js file

}

Input-Photo

string

The original photo that was used to generate the avatar.

Model-Files

object

All model files for a single avatar (.obj). Create-Mouth must be true in order to see Mouth and Tongue paths in the response.

{

"Head": "path-to-file", // head model

"Mouth": "path-to-file", // mouth model

"Tongue": "path-to-file", // tongue model

}

Texture-Files

object

All texture files that were generated for an avatar. Textures will generate in the resolution set in the generate request. Create-Textures must be true in order to see Texture-Files in the response. Create-Mouth must be true to see the Mouth-And-Tongue file path. Skin-Details must be set to ["wrinkles", "freckles"] in order to see Wrinkle and Freckles file paths. Create-Beard must be true in order to see the Main-Beard file path.

{

"Head": "path-to-file", // main head texture (.jpg)

"Mouth-And-Tongue": "path-to-file", // mouth and tongue texture (.png)

"Beard": "path-to-file", // main beard texture (.jpg)

"Freckles": "path-to-file", // texture containing freckles (.jpg)

"Wrinkles": "path-to-file" // texture containing wrinkles (.jpg)

}

Blendshapes-File

string

A JavaScript file (.js) containing all the blendshape information for a given avatar (for use in ThreeJS).

Error & Response Codes

Skullscan uses HTTP response status codes to indicate the success or failure of your requests. If your request fails, the web service will will return an error object in the response containing a code, message and list of detailed errors. Here is an example of a possible error response:

{
"Error": {
"Code": 400,
"Message": "Bad Request",
"Failures": {
"missing_key": "Mandatory key 'Gender' is missing from your request",
"bad_param": "'Skin-Details' possible array values are: ['freckles', 'wrinkles'], 'Blendshapes' possible values are: 'all', 'none', 'Texture-Resolution' possible values are: 256, 512, 1024, 2048"
}
}
}

bad_config

Invalid or missing JSON configuration file. Specify a valid JSON file.

bad_photo

Invalid or missing photo. Specify a JPG or PNG picture.

no_face

No face was detected in the input image. Make sure there is only one face in the photo and that the face takes up 1/4 to 3/4 of the picture. View our perfect picture guide for more information.

uneven_light

Our system detected shadows and/or uneven light on the face. View our perfect picture guide for more information.

bad_orientation

Make sure the input photo was taken from directly in front of the subject (head on photo, no more than 30 degrees in any direction). View our perfect picture guide for more information.

bad_mouth

Make sure the subject has a neutral expression and that their mouth closed (lips touching).

unknown_key

One or more of your key parameters in your request are incorrect. Please view API Parameters to verify each parameter’s accepted value(s)

bad_param

One of your keys has an unacceptable value. Please view API Parameters to verify each parameter’s accepted value(s)

missing_key

A mandatory key parameter is missing from your request. Please review the docs for the specific request to learn which parameters are mandatory.

bad_auth

Subscription key must appear in the header of every request (in the format “Authorization”:”APIKEY your-subscription-key-here”)