VTube Studio Public API Documentation

The postProcessingEffects array contains all available visual effects. Each effect is composed of multiple configEntries that define its parameters (e.g., strength, color, or texture).

Config Types

Each configuration entry has a type field. Only the fields corresponding to that type will be populated; all other fields should be ignored:

• Float: Uses floatValue, floatMin, floatMax, and floatDefault.
• Int: Uses intValue, intMin, intMax, and intDefault.
• Bool: Uses boolValue and boolDefault.
• String: Uses stringValue and stringDefault.
• Color: Uses colorValue (RGBA hex string, e.g., "77CCAAFF") and colorDefault. Use colorHasAlpha to check if the alpha channel is relevant.
• SceneItem: A string value representing a filename (ending in .jpg or .png) located in the VTube Studio "Items" folder.

Identifying Effects

• enumID: The primary ID used to identify the effect and its configs.
• internalID: The ID used by VTube Studio internally for preset JSON files (not recommended for most use cases, but usable via API).

{
	"apiName": "VTubeStudioPublicAPI",
	"apiVersion": "1.0",
	"requestID": "SomeID",
	"messageType": "PostProcessingListResponse",
	"data": {
		"postProcessingEffects": [
			{
				"internalID": "color_grading",
				"enumID": "ColorGrading",
				"configEntries": [
					{
						"enumID": "ColorGrading_Strength",
							"type": "Float",
						"activationConfig": true,
						"floatValue": 0.0
						
					},
						{
						"enumID": "ColorGrading_ColorFilter",
							"type": "color",
						"colorValue": "FFFFFFFF"
						}
					]
				}
			]
		}
	}
}

Certain VTube Studio API functionalities are protected by a permission system. To use these features, a plugin must request permission after authenticating. When a permission is requested, VTube Studio displays a popup to the user explaining the permission and the plugin's identity, allowing the user to grant or deny access.

Key behaviors:

• Granting: Once a permission is granted, it cannot be revoked via the API. However, users can manually revoke permissions at any time via the VTube Studio API configuration settings for your specific plugin.
• Re-requesting: If a plugin has already been granted a permission, subsequent requests for that same permission return instantly without showing a popup to the user.
• Error Handling: Errors are returned if you request an unknown permission, if the user has the API config window open, or if there are file I/O issues with the plugin config.

To receive notifications when specific actions occur in VTube Studio (like hotkey activation or model loading), you must explicitly subscribe to those events using an EventSubscriptionRequest.

Subscription Logic

• Subscribe: Set subscribe: true in the request. If you subscribe to an event multiple times, the new config will overwrite the previous one.
• Unsubscribe: Set subscribe: false for a specific eventName, or leave eventName empty to unsubscribe the entire plugin session from all events.
• Automatic Cleanup: When your plugin disconnects from the VTube Studio API, all active subscriptions are automatically removed.

Request Format

Use the EventSubscriptionRequest message type. The config object allows for event-specific filtering (e.g., filtering by modelID).

Response Format

A successful request returns an EventSubscriptionResponse containing the subscribedEventCount and a list of subscribedEvents.

{
    "apiName": "VTubeStudioPublicAPI",
    "apiVersion": "1.0",
    "requestID": "SomeID",
    "messageType": "EventSubscriptionRequest",
    "data": {
        "eventName": "ModelLoadedEvent",
        "subscribe": true,
        "config": {
            "modelID": ["1234567890abcdef1234567890abcdef"]
        }
    }
}