Consume Virtuals via APIs

Watch our tutorial on building your first dApp!

This document explains how to successfully call the Virtual Protocol API with your app and get the conversational response from Virtuals.

The runner service mentioned in this API documentation refers to the service provided by Virtual Protocol that is responsible for returning generated responses from the Virtual, whereas the Virtual Protocol Backend service refers to the service that is in charge of issuing access token to grant access to the runner service.

Follow the step-by-step guideline to understand more.

Before You Start

Create API Key at Follow step by step guide here.

1. Generate Access Token

Query the Virtual Protocol Backend POST /access/token endpoint to generate access token. The metadata field will be inserted as the JWT access token claims to be consumed by your application and the runner service.

userUid is crucial for the memory core to function well. It is a unique random UID that you generate within your dApp depending on how you wish to maintain the Virtual’s memory.

For example, memory of userUid = “277a076b-62f4-4a76-b3ce-66d3918176a3” will not be mixed with memory of other people with different userUid.

curl -i -X POST \
 -H "Content-Type: application/json" \
 "" -d '{
  "metadata": {
    "userUid": "<YOUR_UNIQUE_UID_FOR_USER>"
  "apiKey": "<YOUR_API_KEY>",
  "apiSecret": "<YOUR_API_SECRET>"

2. Retrieve runner URL from access token claims

Decode the JWT token that you received from the previous step, you should see structure similar to this:

Keep the runner value as we will use it in the next step. For this example, the URL is

3. Send prompt

Send POST /prompts request to the runner URL to get the Virtual response.

curl -i -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
    "text": "Hello",
    "skipTTS": false,
    "userName" "User",
    "botName": "Virtual"

Request body

Field Name




Text prompt from user

Hello there.


Whether to skip the text-to-speech service



User’s name that the Virtual will address as



Virtual’s name that the Virtual will address itself as


Response body

Field Name




URL to the text-to-speech audio response


Virtual’s emotion (anger, disgust, fear, joy, neutral, sadness, surprise)



Virtual’s Vocaloid Motion Data (VMD) animation’s file name



Virtual’s Vocaloid Motion Data (VMD) animation’s file url


User’s prompt text

Hello there.


Virtual’s prompt response

Hi, my dear!

There we go! You have successfully integrated with your Virtual. Prompt response may differ depending on the cores available for the selected Virtual, for example, audioUid will be empty if the Virtual does not have a voice core.

If you are using ReactJS, it is recommended to use the React SDK that provides out-of-the-box components to display and animate 3D models, fully functional input submission (including voice message) and more.

Last updated