Getting started

To get access to Avaturn API first you need to create a project at developer portal and generate an authentication token for API.

Overview

API is built around following concepts:

• Project: Entity having unique domain and access token assigned to it. Usually <your-app-name>.avaturn.dev. You can create project in developer portal.
• User: Anonymous user that can be created with API, assigned to (owned by) Project, developers can access only to users owned by their project.
• Avatar: 3D model that can be exported. Created and customized by User during Session
• Session: Entity representing single User interaction with avaturn UI resulting an export.

When you need to allow user to perform actions with their avatar in avaturn UI you need to create new session, send resulting session url to your front-end and open it in webview.

Basic flow

1. Create a user in Avaturn with POST /users/new and save its id. This is anonymous user, we don't need any real user details.
2. Now you can create a session (session is basically a special url) for that user with POST /sessions/new.
   • Use session type create_or_edit_existing for a generic use case.
   • Use session type edit_existing if you want to open a specific avatar.
   • Use session type create if you want to open UI for creating a new avatar.
3. Send this url to your frontend and use it via our SDK. E.g. if you are building a web app, please pass the link to .init() of web SDK.

Working with individual avatars

User avatars can be listed, edited and deleted individually.

• To create a new avatar by uploading photos directly to Avaturn backend (without using Avaturn UI) use POST /avatars/new. See this doc for more info.
• To list all avatars of specified user use GET /users/{user-id}/avatars
• To delete specified avatar of specified user use DELETE /users/{user-id}/avatars/{avatar-id}
• To get and set active assets for an avatar use GET avatars/{id}/customization and PUT avatars/{id}/customization.

Important Notes

• You should store correspondence of avaturn user_id to your users if you want to allow user to reuse their previous avatars.
• You can create new user_id every time in case you need a user to always start from scratch (empty list of avatars).
• Links received in Sessions are short-lived. It is required to create a new session for every new usage.

Export

There are two types of avatar export available:

• dataURL - base64 encoded data, generated on the client side, ideal if you want to use the avatar on the frontend instantly and don't need to upload it anywhere
• httpURL - permanent http link, useful if you need the avatar on the backend.

You can choose one at developer portal