API_CONTRACT.md

Custom JSON API Contract

OpenAvatar can call a custom HTTP JSON endpoint through LLMService.ProviderMode.CustomJsonApi.

Request

POST /agent-response

Headers:

Content-Type: application/json
Authorization: Bearer <api-key>   # optional

Body:

{
  "input": "The user's raw text",
  "systemPrompt": "Instruction text configured in Unity"
}

Response

Return compact JSON:

{
  "text": "I understand. I will guide you through the next step.",
  "emotion": "Comforting",
  "state": "Comforting",
  "action": "comfort_user"
}

Allowed emotion values:

• Neutral
• Thinking
• Happy
• Warning
• Comforting

Allowed state values:

• Idle
• Thinking
• Speaking
• Warning
• Comforting

If emotion, state, or action is missing, OpenAvatar resolves a safe local fallback. If the endpoint fails, the scene stays interactive through local fallback responses.

Minimal FastAPI Example

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class AgentRequest(BaseModel):
    input: str
    systemPrompt: str = ""


@app.post("/agent-response")
def agent_response(request: AgentRequest):
    return {
        "text": f"Input received: {request.input}",
        "emotion": "Thinking",
        "state": "Thinking",
        "action": "analyze_input",
    }