Table of Contents

Engine HTTP API

Last updated:

The Oscova Avatar Engine exposes an HTTP server, usually at http://127.0.0.1:11318. Oscova Agents calls this server to select avatars, queue speech, show message-panel text, and apply visual settings.

Note

An HTTP API is a set of callable web addresses. The engine API is owned by the Avatar Engine binary. Oscova's internal host proxy is documented in Bridge Service.

All engine routes use the /avatarbridge prefix. JSON requests and responses use PascalCase field names because the Unreal Engine Blueprint layer binds to those shapes.

Base URL

For a local engine, the base URL is usually:

http://127.0.0.1:11318

An engine endpoint is the base URL plus the route. For example:

http://127.0.0.1:11318/avatarbridge/health

Oscova's host proxy routes start with api/avatarbridge. Those are not the engine's public route names.

Connection authorization

Call POST /avatarbridge/connect before any other engine route. The first caller receives a ConnectionId and owns the bridge until the Avatar Engine stops:

{
  "Success": true,
  "Description": "Avatar Bridge claimed.",
  "ConnectionId": "opaque-connection-id"
}

Send that value with every later request:

Authorization: Bearer <ConnectionId>

Every route except connect, including health and shutdown, returns 401 Unauthorized when the header is missing or incorrect. The response explains how to provide the ID and includes WWW-Authenticate: Bearer realm="AvatarBridge". A later connect attempt receives 409 Conflict and never receives the active ID.

The connection ID exists only in process memory. If the owning client exits while the engine remains open, restart the Avatar Engine before connecting a new client.

Naming rules

Engine paths follow these rules:

  • Enumerable named state uses {domain}/list to read and {domain}/select to choose.
  • Scalar or structured properties use {domain}/{property} with POST.
  • Lifecycle actions use imperative names, such as speech/stop, message/clear, or shutdown.
  • Multi-word properties are hyphenated, such as message/font-size.
  • Status reads use health.

Speech uses a queue model. speech/queue enqueues an audio URL, and speech/queue-file enqueues a file already available to the engine.

Response shape

Most command responses include:

{ "Success": true, "Description": "ok" }

Some responses add the applied value, such as SelectedAvatar, SelectedEmotion, Volume, Width, Height, or SavedFilePath. A non-success response should include a human-readable Description that Oscova can show or log.

health, avatar/list, and emotion/list return status or catalog data instead of a single applied setting.

Message panel behavior

The message panel is a general text surface. It can be used for subtitles, captions, persistent announcements, or settings previews.

  • message/text replaces the current panel text without audio.
  • message/clear hides the panel.
  • A queued speech clip with a non-empty Message replaces the panel text while that clip plays.
  • A queued speech clip with an empty Message leaves the current panel text alone.
  • message/display-duration applies to panel text no matter which endpoint set it.

Validation

The engine returns a non-success response for invalid input instead of silently fixing the value.

Setting Accepted values
speech/volume 0.0 through 1.0
message/font-size 8 through 120
message/color RGBA components 0.0 through 1.0
message/box-position PositionX and PositionY from 0.0 through 1.0
message/box-size Width and Height greater than 0.0 through 1.0
message/display-duration DurationSeconds >= 0
background/color RGB components 0 through 255
resolution width 1 through 7680, height 1 through 4320
emotion/select case-sensitive emotion name and BlendSpeed > 0
avatar/select case-sensitive avatar name
camera/yaw host UI sends -5.0 through 5.0
graphics/preset any integer level. 0 to 3 map to Low, Medium, High, Epic

speech/queue accepts an absolute audio URL. The engine downloads the URL, saves it locally, and enqueues playback. Oscova sends /tts/ URLs generated by its speech synthesis service.

Important

Oscova's settings UI displays camera yaw as -45 through 45 degrees, but sends Yaw as -5.0 through 5.0. It also displays message box position and size as percentages, but sends fractions such as 0.25 for 25%.

Host proxy differences

Direct engine integrations should use the endpoint table below. The Oscova host proxy keeps a few compatibility route names for the Blazor UI:

Host proxy route Engine route
api/avatarbridge/emotions/set /avatarbridge/emotion/select
api/avatarbridge/message/font/size /avatarbridge/message/font-size
api/avatarbridge/message/display/duration /avatarbridge/message/display-duration

The host proxy also rejects speech/queue requests unless Url is an absolute http or https URL whose path starts with /tts/. The engine route itself is documented as accepting an absolute audio URL.

Endpoint reference

Method Path Request Response
POST /avatarbridge/connect none AvatarConnectResponse
GET /avatarbridge/health none AvatarHealthCheckResponse
GET /avatarbridge/avatar/list none AvatarListResponse
POST /avatarbridge/avatar/select AvatarSelectRequest AvatarSelectResponse
GET /avatarbridge/emotion/list none AvatarEmotionListResponse
POST /avatarbridge/emotion/select AvatarEmotionRequest AvatarEmotionResponse
POST /avatarbridge/speech/queue AvatarSpeechQueueRequest AvatarSpeechQueueResponse
POST /avatarbridge/speech/queue-file AvatarSpeechQueueFileRequest AvatarSpeechQueueFileResponse
POST /avatarbridge/speech/stop AvatarSpeechStopRequest AvatarSpeechStopResponse
POST /avatarbridge/speech/volume AvatarSpeechVolumeRequest AvatarSpeechVolumeResponse
POST /avatarbridge/message/text AvatarMessageTextRequest AvatarMessageTextResponse
POST /avatarbridge/message/clear none or {} AvatarMessageClearResponse
POST /avatarbridge/message/font-size AvatarMessageFontSizeRequest AvatarMessageFontSizeResponse
POST /avatarbridge/message/color AvatarMessageColorAndOpacityRequest AvatarMessageColorAndOpacityResponse
POST /avatarbridge/message/box-position AvatarMessageBoxPositionRequest AvatarMessageBoxPositionResponse
POST /avatarbridge/message/box-size AvatarMessageBoxSizeRequest AvatarMessageBoxSizeResponse
POST /avatarbridge/message/display-duration AvatarMessageDisplayDurationRequest AvatarMessageDisplayDurationResponse
POST /avatarbridge/background/color AvatarBackgroundColorRequest AvatarBackgroundColorResponse
POST /avatarbridge/resolution AvatarResolutionRequest AvatarResolutionResponse
POST /avatarbridge/graphics/preset AvatarGraphicsPresetRequest AvatarGraphicsPresetResponse
POST /avatarbridge/camera/yaw AvatarCameraYawRequest AvatarCameraYawResponse
POST /avatarbridge/shutdown AvatarShutdownRequest AvatarShutdownResponse
Note

The old byte-stream speech route is not exposed by the host proxy. Use speech/queue for URL clips or speech/queue-file for engine-local files.

Request examples

The following examples show JSON field names used by the engine. Most responses include Success and Description.

Queue an audio URL:

{ "Url": "http://localhost:11317/tts/session/line.wav", "Message": "Hello" }

Queue an engine-local file:

{ "FileName": "C:\\audio\\line.wav", "Message": "Hello" }

Stop speech:

{ "ForcedStop": false }

Keep ForcedStop set to false for the recommended graceful stop. Set it to true to interrupt immediately.

Set speech volume:

{ "Volume": 0.75 }

Select an avatar:

{ "AvatarName": "<name returned by avatar/list>" }

Select an emotion:

{ "EmotionName": "<name returned by emotion/list>", "BlendSpeed": 0.25 }

Show text without audio:

{ "Message": "Text to show without audio" }

Style and position the message panel:

{ "FontSize": 32 }

{ "Red": 1.0, "Green": 1.0, "Blue": 1.0, "Alpha": 1.0 }

{ "PositionX": 0.25, "PositionY": 0.75 }

{ "Width": 0.5, "Height": 0.2 }

{ "DurationSeconds": 5.0 }

Set window and rendering state:

{ "Red": 32, "Green": 32, "Blue": 32 }

{ "Width": 1920, "Height": 1080, "Fullscreen": false }

{ "Level": 2 }

{ "Yaw": 5.0 }

Request shutdown:

{ "ForceShutdown": false }

Health and catalog examples

Health response:

{ "Success": true, "Status": "running", "Version": "1.0.0", "Port": 11318 }

Avatar list response:

{ "Success": true, "Description": "ok", "Avatars": ["<engine-provided avatar name>"] }

Emotion list response:

{ "Success": true, "Description": "ok", "Emotions": ["<engine-provided emotion name>"] }

Speech queue response:

{ "Success": true, "Description": "queued", "SavedFilePath": "C:\\Avatar\\clips\\line.wav" }