> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mascot.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Process Audio for Visemes

> Takes base64 encoded audio and streams viseme (mouth shapes) predictions using Server-Sent Events (SSE).
Requires valid API key.


Process base64 encoded audio and receive streaming viseme predictions using Server-Sent Events (SSE). This endpoint is ideal for real-time facial animation based on audio input.

## Language-Specific Models

Use the optional `model` parameter to select a viseme model optimized for your audio's language:

* `"default"` — English (used when `model` is omitted)
* `"indonesian"` — Bahasa Indonesia


## OpenAPI

````yaml POST /v1/visemes
openapi: 3.1.0
info:
  title: Viseme Prediction API
  version: 1.0.0
  description: >-
    API for processing audio and streaming viseme predictions, and for
    generating synchronized speech with visemes
servers:
  - url: https://api.mascot.bot
    description: Production server
security: []
paths:
  /v1/visemes:
    post:
      summary: Process audio and stream viseme predictions
      description: >
        Takes base64 encoded audio and streams viseme (mouth shapes) predictions
        using Server-Sent Events (SSE).

        Requires valid API key.
      operationId: getVisemes
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - audio
              properties:
                audio:
                  type: string
                  description: Base64 encoded audio data
                  example: UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=
                sample_rate:
                  type: integer
                  description: Audio sample rate in Hz
                  default: 16000
                  example: 16000
                model:
                  type: string
                  description: >
                    Viseme model to use for prediction. Different models are
                    optimized for different languages.

                    Available models: `default` (English), `indonesian` (Bahasa
                    Indonesia).
                  default: default
                  enum:
                    - default
                    - indonesian
                  example: default
      responses:
        '200':
          description: >
            Successful response streams viseme predictions using Server-Sent
            Events.

            Each event contains viseme data for a processed audio chunk.
          content:
            text/event-stream:
              schema:
                type: string
                description: |
                  Server-Sent Events stream with the following format:
                  - Each event starts with "data: " prefix followed by JSON
                  - Example normal event:
                    data: {"visemes":[...],"chunk_progress":"1/10","chunk_duration_ms":100}
                  - Example error event:
                    error: {"message":"Error message","chunk_id":5}
              examples:
                normalEvent:
                  value: >
                    data:
                    '{"visemes":[{"visemeId":1,"offset":0.1},{"visemeId":2,"offset":0.2}],"chunk_progress":"1/10","chunk_duration_ms":100}'
                errorEvent:
                  value: |
                    error: {"message":"Error processing chunk 5","chunk_id":5}
        '400':
          description: Invalid request (missing or invalid audio data)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid audio data
        '403':
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````