By avatarion
Updated 4 months ago
Popularity Score
Success Rate

Portrait3D API Overview

Portrait3D API is based on Avatarion’s Tethys 3D™ solution, and provides software developers with a technology to create animated facial models based on photos.

Contact API Provider


Portrait3D™ API takes an image as input and generates a photorealistic 3D avatar that can move and express emotions.
3D avatar can be published on a Web-page (requires Adobe® Flash® Player).

Portrait3D may be useful for various social applications, games and chat rooms to bring in power and features of 3D while maintaining photorealistic quality.

API Description

Source Image Restrictions

Portrait3D has some restrictions on source images:

  • Image Type: JPEG or PNG
  • Image Dimensions: 200×200 up to 4000×4000
  • Image File Size: 10 KBytes up to 5 MBytes

Images that don’t fit these requirements are rejected with HTTP Status Code 400.

Source Image Recommendations

To get best looking avatar, follow these simple recommendations:

  • Image should contain only one face
  • Best results are achieved on full face images with minimum rotation around the vertical axis
  • Image resolution should be high enough to produce high-quality avatar

In general: quality of the source photograph affects quality of the resulting avatar.

Passing Image URL

If your image is hosted somewhere, you may use the URL to create an avatar. URL should be passed in the 'url' parameter using GET method:


Note: {URL} string should be url-encoded.

Example (using cURL):

curl -H "X-Mashape-Authorization: {Your Mashape Authorization Code}" "https://avatarion-portrait3d.p.mashape.com/create/?url=http%3A%2F%2Favatarion.com%2Fimages%2Fharrison-ford.jpg" -k

POSTing Image File

Another option is to upload an image using POST request and the 'image' parameter. Example (using cURL):

curl -H "X-Mashape-Authorization: {Your Mashape Authorization Code}" "https://avatarion-portrait3d.p.mashape.com/create/" -F "[email protected];" -k

In this example 'test.jpg' is the actual image file to be uploaded.

API Response

Regardless of the chosen method, if no errors occur the API sets HTTP Status Code to 200 and returns JSON object in the response body:

"avatar" : "abc123"

'abc123' is the Avatar ID that can be used to publish an avatar on a desired Web page (see below).

Error Handling

If something goes wrong the API sets HTTP Status Code to one of the following values:

  • 400 – indicates a problem with the provided image (wrong file type, size, URL does not exist, etc.)
  • 500 – indicates an internal API error. If this error persists please contact us.

Additionally, error details are passed in the response body in JSON format:


Using Created Avatars

Created avatars can be published on a Web page using the following HTML code:

<iframe width="250" height="250" frameborder="0" src="http://content.avatarion.com/portrait3d/v1/embed/{AvatarID}?emotion={Emotion}"></iframe>

{AvatarID} is an ID of an avatar returned by the API.

The 'emotion' parameter sets the primary emotion, expressed by the avatar (optional). Currently we support the following emotions: neutral, smile, wink, sad and surprise.

Additionally you may change 'width' and 'height' attributes of the iframe tag.

Note: you can also use a secure connection for sites that work over SSL, just replace 'http' with 'https' in the <iframe> src attribute.


<iframe width="250" height="250" frameborder="0" src="http://content.avatarion.com/portrait3d/v1/embed/83kw36?emotion=wink"></iframe>

Or (if your site requires SSL):

<iframe width="250" height="250" frameborder="0" src="https://content.avatarion.com/portrait3d/v1/embed/83kw36?emotion=wink"></iframe>

Install SDK for NodeJS


To utilize unirest for node.js install the the npm module:

$ npm install unirest

After installing the npm package you can now start simplifying requests like so:

var unirest = require('unirest');

Creating Request

.header("X-RapidAPI-Host", "avatarion-portrait3d.p.rapidapi.com")
.header("X-RapidAPI-Key", "SIGN-UP-FOR-KEY")
.header("Content-Type", "application/x-www-form-urlencoded")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
OAuth2 Authentication
Client ID
Client Secret
OAuth2 Authentication