{
  "openapi": "3.0.3",
  "info": {
    "title": "Reblium Avatar API",
    "version": "1.0.0-beta",
    "description": "Load a Reblium 3D avatar and make it talk: text in, a WAV voice and 52 ARKit blend shape curves at 100 fps out, made by Reblium's lipsync model on Reblium's server. Avatars are published from the Reblium studio (Export panel, preset API / XR, Publish to API), not through this API. Plain-text guide for AI agents, with the curve format, emotion table and retry policy: https://app.reblium.com/web/developers/llms.txt. Call from an app or a server only: a request carrying an Origin header is refused (code browser). Keys are made on https://app.reblium.com/web/developers.html. Limits per key: 20 speak/chat/lipsync calls a minute (rate_limit), 3600 seconds of speech a day (daily_limit, reset 00:00 UTC), 600 requests an hour (429 without a code).",
    "contact": {
      "url": "https://app.reblium.com/docs/api"
    }
  },
  "servers": [
    {
      "url": "https://app.reblium.com",
      "description": "Reblium API"
    }
  ],
  "security": [
    {
      "bearerKey": []
    }
  ],
  "tags": [
    {
      "name": "avatars",
      "description": "Published 3D avatars and their packages"
    },
    {
      "name": "speech",
      "description": "Voice and face curves"
    },
    {
      "name": "account",
      "description": "This key's use"
    }
  ],
  "paths": {
    "/api/v1/avatars": {
      "get": {
        "tags": [
          "avatars"
        ],
        "operationId": "listAvatars",
        "summary": "The avatars this key may use",
        "responses": {
          "200": {
            "description": "The list (empty when nothing is published yet)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvatarList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/avatars/{id}": {
      "get": {
        "tags": [
          "avatars"
        ],
        "operationId": "getAvatar",
        "summary": "One avatar's manifest and a signed package link (valid 1 hour)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^av_[0-9]+$"
            },
            "example": "av_12"
          }
        ],
        "responses": {
          "200": {
            "description": "The avatar",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvatarDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/speak": {
      "post": {
        "tags": [
          "speech"
        ],
        "operationId": "speak",
        "summary": "Say a line of text: WAV audio plus ARKit and viseme curves",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeakRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio and curves",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpeakResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/chat": {
      "post": {
        "tags": [
          "speech"
        ],
        "operationId": "chat",
        "summary": "The avatar answers in character; the answer is spoken",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer, its audio and curves",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/lipsync": {
      "post": {
        "tags": [
          "speech"
        ],
        "operationId": "lipsync",
        "summary": "Face curves for your own audio: WAV, 16/24/32-bit integer or 32-bit float, mono or stereo, 8 to 192 kHz, at most 30 s",
        "requestBody": {
          "required": true,
          "content": {
            "audio/wav": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Curves only, no audio",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LipsyncResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          },
          "415": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/avatars/{id}/package": {
      "get": {
        "tags": [
          "avatars"
        ],
        "operationId": "downloadPackage",
        "summary": "The package zip (avatar.glb + manifest.json); use the packageUrl from getAvatar as it is",
        "description": "Signed, valid 1 hour, needs no key: send no Authorization header. Standard zip, deflate or stored entries, no Zip64, at most 40 MB.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^av_[0-9]+$"
            }
          },
          {
            "name": "exp",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Expiry, Unix seconds"
          },
          {
            "name": "sig",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The zip",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "410": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "tags": [
          "account"
        ],
        "operationId": "getUsage",
        "summary": "This key's use today, including speech seconds against the daily limit",
        "responses": {
          "200": {
            "description": "Usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A key from the Developers page, starting mk_live_. Keep it out of source control and out of command lines."
      }
    },
    "responses": {
      "Error": {
        "description": "A refusal or failure. Switch on code (fall back to reason, then to the HTTP status).",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait, sometimes sent with 429",
            "schema": {
              "type": "number"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A sentence for people and logs; wording can change"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable reason: key (401), browser (400), key_paused (403), rate_limit (429), daily_limit (429), bad_request (400), too_long (400 text over 1000 characters; 413 audio over 30 s), not_found (404), bad_type (415), bad_audio (400), too_large (413), voice (502), llm (502), not_configured (503), bad_signature (404), expired (410). The hourly limiter's 429 and a 405 carry no code.",
            "example": "daily_limit"
          },
          "reason": {
            "type": "string",
            "description": "Same as code; some older refusals send only this"
          }
        }
      },
      "AvatarSummary": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "av_12",
            "pattern": "^av_[0-9]+$"
          },
          "name": {
            "type": "string",
            "example": "Ada"
          },
          "thumb": {
            "type": "string",
            "nullable": true,
            "description": "Picture URL, or null"
          },
          "updated": {
            "type": "string",
            "format": "date-time",
            "description": "Last publish. Only the list has it: id + updated is the package cache key"
          },
          "bytes": {
            "type": "integer",
            "description": "Package zip size"
          }
        }
      },
      "AvatarList": {
        "type": "object",
        "required": [
          "avatars"
        ],
        "properties": {
          "avatars": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AvatarSummary"
            }
          }
        },
        "description": "Newest first"
      },
      "Manifest": {
        "type": "object",
        "description": "manifest.json inside the package. avatar.glb: binary glTF 2.0; nodes RebliumAvatar > MH_head, MH_teeth, MH_eyeLeft, MH_eyeRight, cards_* (hair); morph targets named via mesh.extras.targetNames (60 on each MH_* mesh: 52 ARKit + 8 emotions); metres, Y up, face toward +Z, right-handed, origin at the bottom of the neck; JPEG/PNG textures; no skeleton. Unknown fields may be added: ignore them.",
        "required": [
          "version",
          "face",
          "morphs"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string"
          },
          "units": {
            "type": "string",
            "example": "m"
          },
          "up": {
            "type": "string",
            "example": "Y"
          },
          "forward": {
            "type": "string",
            "example": "+Z"
          },
          "face": {
            "type": "string",
            "description": "NODE name of the head mesh (glTF mesh names are not set)",
            "example": "MH_head"
          },
          "morphs": {
            "type": "object",
            "properties": {
              "arkit": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "ARKit blend shape names present"
              },
              "emotions": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Emotion blend shape names, like emo_happy",
                "example": [
                  "emo_happy",
                  "emo_smile",
                  "emo_excited",
                  "emo_surprise",
                  "emo_thoughtful",
                  "emo_corners_down",
                  "emo_snarl",
                  "emo_disgust"
                ]
              },
              "empty": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Present but never moving, like tongueOut"
              }
            }
          },
          "voice": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string",
                "example": "reblium"
              },
              "voiceId": {
                "type": "string"
              }
            }
          },
          "handedness": {
            "type": "string",
            "example": "right"
          },
          "morphMeshes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every node with blend shapes; drive each name on all of them",
            "example": [
              "MH_head",
              "MH_teeth",
              "MH_eyeLeft",
              "MH_eyeRight"
            ]
          },
          "eyes": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "minItems": 3,
            "maxItems": 3,
            "description": "Between the eyes, metres, package frame"
          },
          "bounds": {
            "type": "object",
            "description": "Head mesh box, package frame",
            "properties": {
              "min": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              "max": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              }
            }
          },
          "hair": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "mesh": {
                  "type": "string"
                },
                "kind": {
                  "type": "string"
                },
                "triangles": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "additionalProperties": true
      },
      "AvatarDetail": {
        "type": "object",
        "required": [
          "id",
          "manifest",
          "packageUrl"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "manifest": {
            "$ref": "#/components/schemas/Manifest"
          },
          "packageUrl": {
            "type": "string",
            "description": "Absolute https URL of GET /api/v1/avatars/{id}/package?exp=&sig=, valid 1 hour, no key needed. 410 expired or 404 bad_signature: ask getAvatar again."
          }
        }
      },
      "SpeakRequest": {
        "type": "object",
        "required": [
          "avatar",
          "text"
        ],
        "properties": {
          "avatar": {
            "type": "string",
            "example": "av_12"
          },
          "text": {
            "type": "string",
            "description": "At most 1000 characters. A leading [tag] (like \"[happy] Hi!\") sets the emotion and is not spoken",
            "example": "Hello there!",
            "maxLength": 1000
          },
          "voice": {
            "type": "string",
            "description": "ElevenLabs voice id; default the manifest's voice",
            "pattern": "^[A-Za-z0-9]{10,40}$"
          },
          "voiceProvider": {
            "type": "string",
            "pattern": "^prv_[0-9]+$",
            "description": "Omit for Reblium's voice account; prv_N for your own ElevenLabs key registered on the Developers page"
          },
          "emotion": {
            "description": "A name (neutral, happy, sad, angry, surprised, thinking, or an emotion morph name without emo_) or {name, weight}; default from a leading [tag], else neutral, weight 0.6",
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[a-z_]{1,24}$"
              },
              {
                "$ref": "#/components/schemas/Emotion"
              }
            ]
          },
          "language": {
            "type": "string",
            "description": "Language code; default detected",
            "example": "en",
            "pattern": "^[a-z]{2}(-[A-Za-z]{2,4})?$"
          }
        },
        "description": "Leave optional fields out when unused (an empty string counts as left out)."
      },
      "ChatTurn": {
        "type": "object",
        "required": [
          "role",
          "text"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "text": {
            "type": "string",
            "maxLength": 4000
          }
        }
      },
      "ChatRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SpeakRequest"
          },
          {
            "type": "object",
            "properties": {
              "history": {
                "type": "array",
                "maxItems": 20,
                "items": {
                  "$ref": "#/components/schemas/ChatTurn"
                },
                "description": "Earlier messages, oldest first, ONE message per entry, at most 20 (more is refused); text at most 4000 characters. The server keeps no state."
              }
            }
          }
        ]
      },
      "Audio": {
        "type": "object",
        "required": [
          "format",
          "sampleRate",
          "base64"
        ],
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "wav"
            ]
          },
          "sampleRate": {
            "type": "integer",
            "example": 24000
          },
          "base64": {
            "type": "string",
            "format": "byte",
            "description": "A complete WAV file, 16-bit PCM mono"
          }
        }
      },
      "CurveTrack": {
        "type": "object",
        "required": [
          "names",
          "data"
        ],
        "description": "data is base64 of frames x names.length bytes, row major (frame after frame) in names order (not necessarily the documented ARKit order: map by name); byte / 255 is the weight 0..1; frame i is audio time i / fps.",
        "properties": {
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "data": {
            "type": "string",
            "format": "byte"
          }
        }
      },
      "Emotion": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "neutral, happy, sad, angry, surprised, thinking (chat), or the name a request gave"
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "0..1, default 0.6"
          },
          "morph": {
            "type": "string",
            "nullable": true,
            "description": "The package's blend shape to set for this emotion (null for neutral): happy emo_happy, smile emo_smile, excited emo_excited, surprised emo_surprise, thinking emo_thoughtful, sad emo_corners_down, angry emo_snarl, disgusted emo_disgust, other X emo_X. Answers only; ignored in requests.",
            "example": "emo_corners_down"
          }
        },
        "required": [
          "name"
        ]
      },
      "LipsyncResult": {
        "type": "object",
        "required": [
          "fps",
          "frames",
          "arkit"
        ],
        "properties": {
          "fps": {
            "type": "integer",
            "example": 100
          },
          "frames": {
            "type": "integer"
          },
          "arkit": {
            "$ref": "#/components/schemas/CurveTrack"
          },
          "visemes": {
            "$ref": "#/components/schemas/CurveTrack"
          },
          "durationMs": {
            "type": "number",
            "description": "Audio length; counts toward the key's daily minutes"
          },
          "encoding": {
            "type": "string",
            "example": "uint8-base64, value = byte / 255, frames x channels, row major"
          }
        }
      },
      "SpeakResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/LipsyncResult"
          },
          {
            "type": "object",
            "required": [
              "audio",
              "emotion",
              "text"
            ],
            "properties": {
              "audio": {
                "$ref": "#/components/schemas/Audio"
              },
              "emotion": {
                "$ref": "#/components/schemas/Emotion"
              },
              "text": {
                "type": "string",
                "description": "The words spoken"
              }
            }
          }
        ]
      },
      "ChatResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SpeakResult"
          },
          {
            "type": "object",
            "required": [
              "reply"
            ],
            "properties": {
              "reply": {
                "type": "string",
                "description": "The avatar's answer (same words as text), 1 to 3 short sentences"
              }
            }
          }
        ]
      },
      "Usage": {
        "type": "object",
        "additionalProperties": true,
        "description": "This key's use today. speech is the 3D avatar API's part; other fields are for Reblium's video avatars.",
        "properties": {
          "speech": {
            "type": "object",
            "nullable": true,
            "description": "null if the count is unavailable for a moment",
            "properties": {
              "secondsToday": {
                "type": "number"
              },
              "callsToday": {
                "type": "integer"
              },
              "maxDailySeconds": {
                "type": "number",
                "example": 3600
              }
            }
          }
        }
      }
    }
  }
}
