> ## 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.

# Get Signed URL

> Generates a signed URL for connecting to conversational AI providers via our proxy.
The signed URL is valid for 10 minutes. Connections made via the signed URL proxy requests to your chosen provider and add visemes to the audio stream.

**Supported providers:**
- `elevenlabs` - ElevenLabs Conversational AI
- `gemini` - Google Gemini Live API
- `openai` - OpenAI Realtime API


Send your provider connection details and get a signed WebSocket URL on our server that sets up a proxied connection between your client SDK and your chosen conversational AI provider — with real-time visemes injected into the stream for avatar lip sync.

**Supported providers:**

* **`elevenlabs`** — ElevenLabs Conversational AI Agents
* **`gemini`** — Google Gemini Live API
* **`openai`** — OpenAI Realtime API

## Language-Specific Viseme Models

All providers support an optional `viseme_model` field in `provider_config` to select a language-optimized viseme prediction model:

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

```json Example: ElevenLabs with Indonesian model theme={null}
{
  "config": {
    "provider": "elevenlabs",
    "provider_config": {
      "api_key": "sk_your_key",
      "agent_id": "agent_123",
      "viseme_model": "indonesian"
    }
  }
}
```


## OpenAPI

````yaml POST /v1/get-signed-url
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/get-signed-url:
    post:
      summary: Get signed URL for conversational AI proxy
      description: >
        Generates a signed URL for connecting to conversational AI providers via
        our proxy.

        The signed URL is valid for 10 minutes. Connections made via the signed
        URL proxy requests to your chosen provider and add visemes to the audio
        stream.


        **Supported providers:**

        - `elevenlabs` - ElevenLabs Conversational AI

        - `gemini` - Google Gemini Live API

        - `openai` - OpenAI Realtime API
      operationId: getSignedUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - config
              properties:
                config:
                  type: object
                  description: Configuration parameters
                  properties:
                    provider:
                      type: string
                      description: Name of the conversational AI provider
                      enum:
                        - elevenlabs
                        - gemini
                        - openai
                      example: elevenlabs
                    provider_config:
                      type: object
                      description: >
                        Provider-specific configuration (varies by provider).

                        All providers support an optional `viseme_model` field
                        to select the viseme prediction model.
                      properties:
                        viseme_model:
                          type: string
                          description: >
                            Viseme model to use for lip sync prediction.
                            Different models are optimized for different
                            languages.

                            Available models: `default` (English), `indonesian`
                            (Bahasa Indonesia).
                          default: default
                          enum:
                            - default
                            - indonesian
            examples:
              elevenlabs:
                summary: ElevenLabs Configuration
                value:
                  config:
                    provider: elevenlabs
                    provider_config:
                      api_key: sk_your_elevenlabs_api_key_here
                      agent_id: agent_1234567890
                      sample_rate: 16000
              elevenlabs_indonesian:
                summary: ElevenLabs with Indonesian Viseme Model
                value:
                  config:
                    provider: elevenlabs
                    provider_config:
                      api_key: sk_your_elevenlabs_api_key_here
                      agent_id: agent_1234567890
                      sample_rate: 16000
                      viseme_model: indonesian
              gemini:
                summary: Gemini Configuration (with ephemeral token)
                value:
                  config:
                    provider: gemini
                    provider_config:
                      ephemeral_token: google-ephemeral-token-from-authTokens-create
                      model: gemini-2.5-flash-preview
              openai:
                summary: OpenAI Realtime API Configuration (with ephemeral token)
                value:
                  config:
                    provider: openai
                    provider_config:
                      ephemeral_token: openai-client-secret-from-realtime-client_secrets
                      model: gpt-realtime
                      voice: marin
      responses:
        '200':
          description: >
            Successful response containing connection credentials for the
            conversational AI proxy.

            The response format varies by provider:


            **ElevenLabs:** Returns a `signed_url` — use it directly as the
            WebSocket URL with the ElevenLabs SDK.


            **Gemini:** Returns `api_key` and `base_url` — pass them to the
            Google AI SDK as `apiKey` and `httpOptions.baseUrl`.


            **OpenAI:** Returns a `signed_url` — use it as the WebSocket URL in
            `OpenAIRealtimeWebSocket`'s `createWebSocket` factory.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signed_url:
                    type: string
                    description: >-
                      (ElevenLabs, OpenAI) Signed WebSocket URL with encrypted
                      token. For ElevenLabs, use directly as the WebSocket URL.
                      For OpenAI, pass to createWebSocket in
                      OpenAIRealtimeWebSocket.
                    example: >-
                      wss://api.mascot.bot/v1/conversation?token=eyJhbGciOiJIUzI1NiIs...
                  api_key:
                    type: string
                    description: >-
                      (Gemini) Mascot Bot proxy token — use as `apiKey` in
                      GoogleGenAI
                    example: mascot_ephemeral_abc123...
                  base_url:
                    type: string
                    description: >-
                      (Gemini) Proxy base URL — use as `httpOptions.baseUrl` in
                      GoogleGenAI
                    example: https://api.mascot.bot
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid provider config
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid API key
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````