API docs by Redocly

Homunculus API (1.0.0)

Download OpenAPI specification:

API for controlling the Homunculus desktop pet.

vrm

VRM model management and control operations

Find a VRM model by name

Locate a VRM model entity using its name identifier.

query Parameters
name
required
string

The name of the VRM model to find

Responses

Response samples

Content type
application/json
0
0

Spawn a VRM model

Create and display a new VRM 3D model instance in the application with optional transform settings.

Request Body schema: application/json
required
asset
required
string (ModAssetId)

Asset ID for a mod. (e.g. basic::vrm.vrm)

object (TransformArgs)

Responses

Request samples

Content type
application/json
{
  • "asset": "basic::vrm.vrm",
  • "transform": {
    }
}

Response samples

Content type
application/json
0
0

Wait for a VRM model to load

Wait for the specified VRM model to finish loading before returning its entity ID.

query Parameters
name
required
string

The name of the VRM model to wait for

Responses

Response samples

Content type
application/json
0
0

Despawn a VRM model

Remove and destroy the specified VRM model instance from the application.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Get the state of a VRM model

Retrieve the current state/mode of the specified VRM model.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

Responses

Response samples

Content type
application/json
{
  • "state": "idle"
}

Set the state of a VRM model

Update the state/mode of the specified VRM model to control its behavior.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

Request Body schema: application/json
required
state
required
string

The state/mode to set for the VRM model

Responses

Request samples

Content type
application/json
{
  • "state": "dancing"
}

Subscribe to VRM events

Establish a Server-Sent Events stream to receive real-time events from the VRM model.

Available events:

  • drag-start: Fired when a drag starts
  • drag: Fired when a drag is in progress
  • drag-end: Fired when a drag ends
  • pointer-press: Fired when a pointer is pressed
  • pointer-click: Fired when a click occurs
  • pointer-move: Fired when a pointer moves
  • pointer-release: Fired when a pointer is released
  • pointer-over: Fired when a pointer is over the VRM
  • pointer-out: Fired when a pointer is out of the VRM
  • pointer-cancel: Fired when a pointer action is canceled
  • state-change: Fired when the VRM state changes
path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

Responses

Get or create VRMA animation for a VRM model

Get or create a VRMA animation entity for the specified VRM model and animation source.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

query Parameters
source
required
string

The VRMA animation source path relative to the mods directory

Responses

Response samples

Content type
application/json
0
0

Set VRM look-at target

Configure the VRM model to look at a specific entity target.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

target
required
integer <uint64> (Entity)

The entity ID to look at

Responses

Set VRM to look at cursor

Configure the VRM model to look at the mouse cursor position.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

Responses

Disable VRM look-at functionality

Disable the look-at functionality for the specified VRM model.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

Responses

Speak using VoiceVox

Generate speech audio using VoiceVox text-to-speech synthesis for the specified VRM model.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRM model entity

Request Body schema: application/json
required
sentences
required
Array of strings

Array of sentences to synthesize into speech

speaker
integer

The VoiceVox speaker ID

pause
number <float>

The pause duration in seconds between sentences

waitForCompletion
boolean

If true, the method will wait for the speech to complete

object (SubtitleOptions)

Responses

Request samples

Content type
application/json
{
  • "sentences": [
    ],
  • "speaker": 0,
  • "pause": 0.1,
  • "waitForCompletion": true,
  • "subtitle": {
    }
}

Fetch all VRM models

Retrieve a list of all currently spawned VRM models with their metadata. Supports optional streaming response.

query Parameters
stream
boolean

Whether to return results as a streaming response

Responses

Response samples

Content type
[
  • {
    }
]

vrma

VRMA animation playback control

Play a VRMA animation

Start playing a VRMA animation on the specified VRMA entity with optional transition duration and repeat settings.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRMA animation entity

Request Body schema: application/json
transitionSecs
number <float>

Transition duration in seconds for smooth animation blending

object (VrmaRepeat)

Repeat configuration for VRMA animation playback

Responses

Request samples

Content type
application/json
{
  • "transitionSecs": 0.5,
  • "repeat": {
    }
}

Stop a VRMA animation

Stop the currently playing VRMA animation on the specified VRMA entity.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the VRMA animation entity

Responses

cameras

Camera coordinate transformation utilities

Get the global viewport from world coordinates

Convert 3D world coordinates to 2D global viewport coordinates for positioning UI elements or interactions.

query Parameters
x
number <float>

X coordinate in world space

y
number <float>

Y coordinate in world space

z
number <float>

Z coordinate in world space

Responses

Response samples

Content type
application/json
{
  • "x": 0.1,
  • "y": 0.1
}

Convert a global viewport to a 2D world position

Transform global viewport coordinates back to 2D world position coordinates.

query Parameters
x
number <float>

X coordinate in global viewport space

y
number <float>

Y coordinate in global viewport space

Responses

Response samples

Content type
application/json
{
  • "x": 0.1,
  • "y": 0.1
}

displays

Display and monitor information

Get all display information

Retrieve information about all connected displays including dimensions, position, and scale factor for multi-monitor support.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

effects

Visual and audio effects

Play a sound effect

Trigger playback of a sound effect from the specified mod asset.

Request Body schema: application/json
required
source
required
string (ModModuleSource)

Module source identifier (e.g. basic::sound.wav)

Responses

Request samples

Content type
application/json
{
  • "source": "basic::sound.wav"
}

Show a stamp effect

Display a visual stamp effect at the specified position with customizable size, opacity, and duration.

Request Body schema: application/json
required
source
required
string (ModModuleSource)

Module source identifier (e.g. basic::sound.wav)

x
number <float>
y
number <float>
width
number <float>
height
number <float>
alpha
number <float>
duration
number <float>

Responses

Request samples

Content type
application/json
{
  • "source": "basic::sound.wav",
  • "x": 0.1,
  • "y": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "alpha": 0.1,
  • "duration": 0.1
}

gpt

ChatGPT integration and configuration

Fetch the available models from the ChatGPT API

Retrieve a list of all ChatGPT models available for use with the current API configuration.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Send a chat message to the GPT API

Send a user message to the ChatGPT API and receive a structured response including message, dialogue, and emotion data.

Request Body schema: application/json
required
userMessage
required
string
object (ChatVrmRequestOptions)

Responses

Request samples

Content type
application/json
{
  • "userMessage": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "dialogue": "string",
  • "emotion": "happy"
}

Check the model used by the GPT API

Get the currently configured ChatGPT model for the specified VRM or global setting.

query Parameters
vrm
integer <uint64> (Entity)

Optional VRM entity to get model for (defaults to global setting)

Responses

Response samples

Content type
application/json
"string"

Set the model used by the GPT API

Configure which ChatGPT model to use for chat interactions.

Request Body schema: application/json
required
model
required
string
vrm
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "vrm": 0
}

Fetch the system prompt

Retrieve the current system prompt used to configure the GPT assistant's behavior and personality.

query Parameters
vrm
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Response samples

Content type
application/json
"string"

Set the system prompt

Configure the system prompt that defines the GPT assistant's behavior, personality, and response style.

Request Body schema: application/json
required
systemPrompt
required
string
vrm
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Request samples

Content type
application/json
{
  • "systemPrompt": "string",
  • "vrm": 0
}

Check if web search is enabled for the GPT API

Determine whether the GPT assistant is configured to use web search for enhanced responses.

query Parameters
vrm
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Response samples

Content type
application/json
true

Set whether web search is enabled for the GPT API

Enable or disable web search functionality for the GPT assistant to access current information.

Request Body schema: application/json
required
useWebSearch
required
boolean
vrm
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Request samples

Content type
application/json
{
  • "useWebSearch": true,
  • "vrm": 0
}

Get the VoiceVox speaker ID

Retrieve the VoiceVox speaker ID used for text-to-speech synthesis.

query Parameters
vrm
integer <uint64> (Entity)

Optional VRM entity to get speaker for (defaults to global setting)

Responses

Response samples

Content type
application/json
0
0

Set the VoiceVox speaker ID

Configure the VoiceVox speaker ID used for text-to-speech synthesis.

Request Body schema: application/json
required
id
required
integer <uint32>

The VoiceVox speaker ID to use for text-to-speech synthesis

vrm
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "vrm": 0
}

webview

Webview window management

Open a webview

Create and display a new webview window with specified content from a mod asset, with customizable positioning and appearance options.

Request Body schema: application/json
required
asset
required
string (ModAssetId)

Asset ID for a mod. (e.g. basic::vrm.vrm)

caller
integer <uint64> (Entity)

The unique identifier for an entity.

transparent
boolean
showToolbar
boolean
shadow
boolean
IVec2 (object) or object (WebviewOpenPosition)
object (Vec2)
openSound
string (ModAssetId)

Asset ID for a mod. (e.g. basic::vrm.vrm)

closeSound
string (ModAssetId)

Asset ID for a mod. (e.g. basic::vrm.vrm)

Responses

Request samples

Content type
application/json
{
  • "asset": "basic::vrm.vrm",
  • "caller": 0,
  • "transparent": true,
  • "showToolbar": true,
  • "shadow": true,
  • "position": {
    },
  • "resolution": {
    },
  • "openSound": "basic::vrm.vrm",
  • "closeSound": "basic::vrm.vrm"
}

Response samples

Content type
application/json
0
0

Close a webview

Close and destroy the specified webview window.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Check if a webview is closed

Determine whether the specified webview window is currently closed or still active.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier for an entity.

Responses

Response samples

Content type
application/json
true

mods

Mod system and menu management

Fetch all mod menus

Retrieve metadata for all available mod menu items including thumbnails, text, and webview configurations.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

preferences

Application preference storage

Load a preference value by key

Retrieve a stored preference value using its unique key identifier.

path Parameters
key
required
string

The unique key identifier for the preference

Responses

Response samples

Content type
application/json
{ }

Save a preference value by key

Store or update a preference value with the specified key for persistent application settings.

path Parameters
key
required
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

settings

Runtime application settings

Get the current FPS limit

Retrieve the current frames per second limit setting for the application rendering.

Responses

Response samples

Content type
application/json
0.1

Set the FPS limit

Configure the maximum frames per second for application rendering to optimize performance.

Request Body schema: application/json
required
number <double>

Responses

Request samples

Content type
application/json
0.1

scripts

JavaScript execution system

Execute a JavaScript file

Run a JavaScript script from the specified mod asset for custom functionality and automation.

Request Body schema: application/json
required
source
required
string (ModModuleSource)

Module source identifier (e.g. basic::sound.wav)

Responses

Request samples

Content type
application/json
{
  • "source": "basic::sound.wav"
}

shadow-panel

Shadow panel overlay controls

Get the current alpha value of the shadow panel

Retrieve the current transparency level of the shadow panel overlay.

Responses

Response samples

Content type
application/json
0.1

Set the alpha value of the shadow panel

Configure the transparency level of the shadow panel with optional speaker and subtitle settings.

Request Body schema: application/json
required
alpha
required
number <float> [ 0 .. 1 ]
speaker
integer <uint32>
object (SubtitleOptions)

Responses

Request samples

Content type
application/json
{
  • "alpha": 1,
  • "speaker": 0,
  • "subtitle": {
    }
}

commands

Command execution system

Stream command results

Get a streaming response for the specified command execution.

path Parameters
command
required
string

The command to stream results for

Responses

Send a command

Execute the specified command and return results.

path Parameters
command
required
string

The command to execute

Responses

app

Application control

Exit the application

Gracefully shut down the Homunculus application.

Responses

entities

Find an entity by name

Locate an entity using its name identifier, optionally within a specific parent entity.

query Parameters
name
required
string

The name of the entity to find

root
integer <uint64> (Entity)

Optional root entity to search within

Responses

Response samples

Content type
application/json
0
0

Get the name of an entity

Retrieve the human-readable name of the specified entity.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the entity

Responses

Response samples

Content type
application/json
"string"

Get the transform of an entity

Retrieve position, rotation, and scale data for the specified entity.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the entity

Responses

Response samples

Content type
application/json
{
  • "translation": [
    ],
  • "rotation": [
    ],
  • "scale": [
    ]
}

Set the transform of an entity

Update the position, rotation, and scale of the specified entity.

path Parameters
entity_id
required
integer <uint64> (Entity)

The unique identifier of the entity

Request Body schema: application/json
required
translation
Array of numbers <float> = 3 items [ items <float > ]

Position in 3D space [x, y, z]

rotation
Array of numbers <float> = 4 items [ items <float > ]

Rotation quaternion [x, y, z, w]

scale
Array of numbers <float> = 3 items [ items <float > ]

Scale factors [x, y, z]

Responses

Request samples

Content type
application/json
{
  • "translation": [
    ],
  • "rotation": [
    ],
  • "scale": [
    ]
}