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.
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:
submitOnce 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
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.
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
{ "Authorization": "APIKEY your-subscription-key-string", "Content-Type": "multipart/form-data" }
{ "Photo": "your-photo", "Configuration": "your-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" }
// 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
// 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" }
# 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" }
// 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" }
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
{ "Authorization": “APIKEY your-subscription-key-string” }
// 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" } } ]
# 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)
[ { “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" } } ]
// 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); } );
[ { “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" } } ]
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
{ "Authorization”: “APIKEY your-subscription-key-string” }
// 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" } }
# 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)
{ “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" } }
// 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); } );
{ “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" } }
This section contains all the definitions and possible values for all the API parameters used by our web services.
Legend: acceptable value default value
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"
}
}
}