### Install and Run Speaches AI with Python and uv

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Installs Speaches AI using the uv package manager, creates a virtual environment, and starts the uvicorn server.

```bash
git clone https://github.com/speaches-ai/speaches.git
cd speaches
uv python install
uv venv
source .venv/bin/activate
uv sync
uvicorn --factory --host 0.0.0.0 speaches.main:create_app
```

--------------------------------

### Start Service with Docker Compose

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Starts the Speaches AI service in detached mode using Docker Compose.

```bash
docker compose up --detach
```

--------------------------------

### .NET OpenAI SDK - Transcription Only

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/realtime-api.md

This snippet shows how to initiate a transcription session using the .NET OpenAI SDK. It requires setting up the client with your API key and endpoint, then starting a session for transcription.

```csharp
using OpenAI.Realtime;
using OpenAI;

var options = new OpenAIClientOptions();
options.Endpoint = new Uri("http://speaches:8000/v1");
var apiKey = "sk-233dadawd"; // your optional speaches API key
var openAiClient = new OpenAIClient(new System.ClientModel.ApiKeyCredential(apiKey), options);
var realtimeClient = openAiClient.GetRealtimeClient();

var cancellationTokenSource = new CancellationTokenSource();
using var session = await realtimeClient.StartSessionAsync("your-transcription-model", "transcription", new RequestOptions()
{
    CancellationToken = cancellationTokenSource.Token,
});

var transcriptionText = new StringBuilder();
await foreach (RealtimeUpdate update in _session.ReceiveUpdatesAsync(cancellationToken))
{
    switch (update)
    {
        case InputAudioTranscriptionDeltaUpdate transcriptionDelta:
            transcriptionText.Append(transcriptionDelta.Delta);
            Console.Write(transcriptionDelta.Delta);
            break;
        // Handle other events as needed...
    }
}
```

--------------------------------

### Get Speech Timestamps with Max Speech Duration

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/vad.md

This example shows how to retrieve speech timestamps while limiting the maximum duration of detected speech segments using the `max_speech_duration_s` parameter.

```shell
curl "$SPEACHES_BASE_URL/v1/audio/speech/timestamps" -F "file=@audio.wav"  -F "max_speech_duration_s=0.2"
# "[{"start":64,"end":256},{"start":288,"end":480},{"start":512,"end":704},{"start":800,"end":992},{"start":1024,"end":1216}]"
```

--------------------------------

### User Message with Text and Audio Input

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Example of a user message payload containing both text and an audio input, formatted for the Speaches AI proxy.

```json
[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "What is in this recording?"
      },
      {
        "type": "input_audio",
        "input_audio": {
          "data": "<bytes omitted>",
          "format": "wav"
        }
      }
    ]
  }
]
```

--------------------------------

### Get Speech Timestamps (Default Settings)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/vad.md

Use this command to get speech timestamps from an audio file using default VAD parameters. The output is a JSON array of start and end times in milliseconds.

```shell
curl "$SPEACHES_BASE_URL/v1/audio/speech/timestamps" -F "file=@audio.wav"
# "[{"start":64,"end":1323}]"
```

--------------------------------

### Assistant Response with Text Content

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Example of an assistant's response payload containing only text, after being processed by the LLM.

```json
[
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "The recording says Hello World!."
      }
    ]
  }
]
```

--------------------------------

### Standard OpenAI-Compatible WebSocket Connection

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/realtime-api.md

Connect to the Speaches server using WebSocket for standard OpenAI-compatible real-time communication. Ensure the correct model and authorization headers are provided. This setup is for conversation mode.

```javascript
// Standard OpenAI-compatible usage
const ws = new WebSocket("wss://your-speaches-server/v1/realtime?model=gpt-4o-realtime-preview", {
  headers: {
    'Authorization': 'Bearer your-api-key'
    // Note: OpenAI also requires 'OpenAI-Beta': 'realtime=v1' header
  }
});

// Session configuration (OpenAI standard)
// Note: Speaches supports session.update, but transcription model changes
// only apply to new audio buffers, not currently processing ones
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    input_audio_transcription: {
      model: "whisper-1"
    }
  }
}));
```

--------------------------------

### List Models by Task Type (Speaches CLI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Filter the list of available models by specifying a task type using the Speaches CLI. For example, to list models for automatic speech recognition.

```bash
uvx speaches-cli registry ls --task automatic-speech-recognition
```

--------------------------------

### Define Model Aliases

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Configure model aliases by mapping friendly names to actual model IDs in the `model_aliases.json` file. This file is located in the root directory of your Speaches installation.

```json
{
  "tts-1": "speaches-ai/Kokoro-82M-v1.0-ONNX",
  "tts-1-hd": "speaches-ai/Kokoro-82M-v1.0-ONNX",
  "whisper-1": "Systran/faster-whisper-large-v3"
}
```

--------------------------------

### Get Speech Timestamps with Custom Threshold

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/vad.md

Adjust the VAD sensitivity by setting a custom `threshold` value. A higher threshold requires more confidence for a segment to be classified as speech.

```shell
curl "$SPEACHES_BASE_URL/v1/audio/speech/timestamps" -F "file=@audio.wav"  -F "max_speech_duration_s=0.2" -F "threshold=0.99"
# "[{"start":96,"end":288},{"start":320,"end":512},{"start":544,"end":736},{"start":832,"end":1024},{"start":1056,"end":1248}]"
```

--------------------------------

### List Downloaded Models (Speaches CLI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

List all models that have been successfully downloaded and are available for use with the Speaches CLI.

```bash
uvx speaches-cli model ls
```

--------------------------------

### List All Available Models (Speaches CLI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Use the Speaches CLI to list all available machine learning models in the registry. Ensure the SPEACHES_BASE_URL environment variable is set.

```bash
uvx speaches-cli registry ls
```

--------------------------------

### Build Docker Image from Source (Direct)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Builds the Speaches AI Docker image locally from source code. Supports multi-platform builds and specifying a base image.

```bash
# Download the source code
git clone https://github.com/speaches-ai/speaches.git
cd speaches

docker build --tag speaches .

# NOTE: you need to install and enable [buildx](https://github.com/docker/buildx) for multi-platform builds
# Build image for both amd64 and arm64
docker buildx build --tag speaches --platform linux/amd64,linux/arm64 .

# Build image without CUDA support
docker build --tag speaches --build-arg BASE_IMAGE=ubuntu:24.04 .
```

--------------------------------

### Download a Speech Embedding Model

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

Use the `uvx` CLI to list, download, and verify speech embedding models. Ensure the SPEACHES_BASE_URL environment variable is set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"

# Listing all available speech embedding models
uvx speaches-cli registry ls --task speaker-embedding | jq '.data | [].id'

# Downloading a model
uvx speaches-cli model download pyannote/wespeaker-voxceleb-resnet34-LM

# Check that the model has been installed
uvx speaches-cli model ls --task speaker-embedding | jq '.data | map(select(.id == "pyannote/wespeaker-voxceleb-resnet34-LM"))'
```

--------------------------------

### List All Available Models (cURL)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Use cURL to query the /v1/registry endpoint and retrieve a list of all available machine learning models. Ensure the SPEACHES_BASE_URL environment variable is set.

```bash
curl "$SPEACHES_BASE_URL/v1/registry"
```

--------------------------------

### Build Docker Image from Source (CUDA)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Builds the Docker image with CUDA support from source code. Requires Docker Buildx.

```bash
# NOTE: you need to install and enable [buildx](https://github.com/docker/buildx) for multi-platform builds

# Download the source code
git clone https://github.com/speaches-ai/speaches.git
cd speaches

# Build image with CUDA support
docker compose --file compose.cuda.yaml build
```

--------------------------------

### Download a Model (Speaches CLI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Download a specific machine learning model using its identifier with the Speaches CLI. This makes the model available for use.

```bash
uvx speaches-cli model download Systran/faster-distil-whisper-small.en
```

--------------------------------

### Set OpenAI Base URL and API Key

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Configure the CHAT_COMPLETION_BASE_URL and CHAT_COMPLETION_API_KEY environment variables for using OpenAI's API.

```bash
export CHAT_COMPLETION_BASE_URL=https://api.openai.com/v1
export CHAT_COMPLETION_API_KEY=sk-xxx
```

--------------------------------

### Run Docker Container (CPU)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Runs the Speaches AI Docker container with CPU-only support, publishing port 8000 and mounting a volume for Hugging Face cache.

```bash
docker run \
  --rm \
  --detach \
  --publish 8000:8000 \
  --name speaches \
  --volume hf-hub-cache:/home/ubuntu/.cache/huggingface/hub \
  ghcr.io/speaches-ai/speaches:latest-cpu
```

--------------------------------

### Download Docker Compose Files (CPU)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Downloads the Docker Compose files for CPU-only support and sets the COMPOSE_FILE environment variable.

```bash
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.yaml
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.cpu.yaml
export COMPOSE_FILE=compose.cpu.yaml
```

--------------------------------

### Download an STT Model

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-to-text.md

Use this command to download a specific STT model. Ensure the SPEACHES_BASE_URL is set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"

# Listing all available STT models
uvx speaches-cli registry ls --task automatic-speech-recognition | jq '.data | [].id'

# Downloading a Systran/faster-distil-whisper-small.en model
uvx speaches-cli model download Systran/faster-distil-whisper-small.en

# Check that the model has been installed
uvx speaches-cli model ls --task text-to-speech | jq '.data | map(select(.id == "Systran/faster-distil-whisper-small.en"))'
```

--------------------------------

### Build Docker Image from Source (CPU)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Builds the Docker image without CUDA support from source code. Requires Docker Buildx.

```bash
# NOTE: you need to install and enable [buildx](https://github.com/docker/buildx) for multi-platform builds

# Download the source code
git clone https://github.com/speaches-ai/speaches.git
cd speaches

# Build image without CUDA support
docker compose --file compose.cpu.yaml build
```

--------------------------------

### Run Docker Container (CUDA with CDI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Runs the Speaches AI Docker container with CUDA and CDI enabled, using the --device flag for GPU access.

```bash
docker run \
  --rm \
  --detach \
  --publish 8000:8000 \
  --name speaches \
  --volume hf-hub-cache:/home/ubuntu/.cache/huggingface/hub \
  --device=nvidia.com/gpu=all \
  ghcr.io/speaches-ai/speaches:latest-cuda
```

--------------------------------

### Transcribe Audio using OpenAI CLI

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-to-text.md

Use the OpenAI CLI to transcribe audio. Set OPENAI_BASE_URL and OPENAI_API_KEY environment variables.

```bash
export OPENAI_BASE_URL=http://localhost:8000/v1/
export OPENAI_API_KEY="cant-be-empty"
openai api audio.transcriptions.create -m Systran/faster-whisper-small -f audio.wav --response-format text
```

--------------------------------

### Run Docker Container (CUDA)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Runs the Speaches AI Docker container with CUDA support, publishing port 8000 and mounting a volume for Hugging Face cache.

```bash
docker run \
  --rm \
  --detach \
  --publish 8000:8000 \
  --name speaches \
  --volume hf-hub-cache:/home/ubuntu/.cache/huggingface/hub \
  --gpus=all \
  ghcr.io/speaches-ai/speaches:latest-cuda
```

--------------------------------

### Download and Verify TTS Model

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/text-to-speech.md

Commands to list, download, and verify TTS models using the speaches-cli. Ensure the SPEACHES_BASE_URL is set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"

# Listing all available TTS models
uvx speaches-cli registry ls --task text-to-speech | jq '.data | [].id'

# Downloading a TTS model
uvx speaches-cli model download speaches-ai/Kokoro-82M-v1.0-ONNX

# Check that the model has been installed
uvx speaches-cli model ls --task text-to-speech | jq '.data | map(select(.id == "speaches-ai/Kokoro-82M-v1.0-ONNX"))'
```

--------------------------------

### Download Docker Compose Files (CUDA with CDI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Downloads Docker Compose files for CUDA with the Container Discovery Interface (CDI) feature enabled.

```bash
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.yaml
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.cuda.yaml
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.cuda-cdi.yaml
export COMPOSE_FILE=compose.cuda-cdi.yaml
```

--------------------------------

### List Downloaded Models (cURL)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

List all downloaded models by querying the /v1/models endpoint using cURL. This provides a list of models ready for inference.

```bash
curl "$SPEACHES_BASE_URL/v1/models"
```

--------------------------------

### Download Docker Compose Files (CUDA)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/installation.md

Downloads the necessary Docker Compose files for CUDA support and sets the COMPOSE_FILE environment variable.

```bash
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.yaml
curl --silent --remote-name https://raw.githubusercontent.com/speaches-ai/speaches/master/compose.cuda.yaml
export COMPOSE_FILE=compose.cuda.yaml
```

--------------------------------

### Transcribe Audio using Python (httpx)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-to-text.md

Use the httpx library in Python to send an audio file for transcription. The audio file is opened in binary read mode.

```python
import httpx

with open('audio.wav', 'rb') as f:
    files = {'file': ('audio.wav', f)}
    response = httpx.post('http://localhost:8000/v1/audio/transcriptions', files=files)

print(response.text)
```

--------------------------------

### Set Ollama Base URL

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Configure the CHAT_COMPLETION_BASE_URL environment variable to point to your Ollama instance for voice chat.

```bash
export CHAT_COMPLETION_BASE_URL=http://localhost:11434/v1
```

--------------------------------

### Generate Speech using Python (httpx)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/text-to-speech.md

Generates speech from text using the httpx library in Python. Saves the output to 'output.mp3'. Ensure the base URL is correctly configured.

```python
from pathlib import Path

import httpx

client = httpx.Client(base_url="http://localhost:8000/")
model_id = "speaches-ai/Kokoro-82M-v1.0-ONNX"
voice_id = "af_heart"
res = client.post(
    "v1/audio/speech",
    json={
        "model": model_id,
        "voice": voice_id,
        "input": "Hello, world!",
        "response_format": "mp3",
        "speed": 1,
    },
).raise_for_status()
with Path("output.mp3").open("wb") as f:
    f.write(res.read())
```

--------------------------------

### Generate Speech using OpenAI Python SDK

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/text-to-speech.md

Generates speech from text using the OpenAI Python SDK. Requires setting OPENAI_API_KEY and OPENAI_BASE_URL environment variables or passing them to the client. Saves the output to 'output.mp3'.

```python
from pathlib import Path

from openai import OpenAI

openai = OpenAI(base_url="http://localhost:8000/v1", api_key="cant-be-empty")
model_id = "speaches-ai/Kokoro-82M-v1.0-ONNX"
voice_id = "af_heart"
res = openai.audio.speech.create(
    model=model_id,
    voice=voice_id,
    input="Hello, world!",
    response_format="mp3",
    speed=1,
)
with Path("output.mp3").open("wb") as f:
    f.write(res.response.read())
```

--------------------------------

### Transcribe Audio using OpenAI Python SDK

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-to-text.md

Utilize the OpenAI Python SDK for audio transcription. Requires setting the base URL and a non-empty API key.

```python
from pathlib import Path

from openai import OpenAI

client = OpenAI()

with Path("audio.wav").open("rb") as audio_file:
    transcription = client.audio.transcriptions.create(model="Systran/faster-whisper-small", file=audio_file)

print(transcription.text)
```

--------------------------------

### Customizing Transcription and Speech Models with OpenAI SDK

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Demonstrates how to specify custom transcription and speech models using the 'extra_body' parameter in the OpenAI Python SDK.

```python
openai_client.chat.completions.create(
        model="gpt-4o-mini",
        modalities=["text", "audio"],
        audio={"voice": "alloy", "format": "wav"},
        stream=False,
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this recording?"},
                    {"type": "input_audio", "input_audio": {"data": "<bytes ommitted>", "format": "wav"}},
                ],
            },
        ],
        extra_body={"transcription_model": "Systran/faster-whisper-tiny.en", "speech_model": "hexgrad/Kokoro-82M"}
    )
```

--------------------------------

### Assistant Response with Audio Output

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Shows the final response format when the assistant's text response is converted back into audio.

```json
[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "refusal": null,
      "audio": {
        "id": "audio_abc123",
        "expires_at": 1729018505,
        "data": "<bytes omitted>",
        "transcript": "The recording says Hello World!."
      }
    },
    "finish_reason": "stop"
  }
]
```

--------------------------------

### Mount Model Aliases in Docker

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

When deploying Speaches with Docker, bind mount your local `model_aliases.json` file into the container to ensure custom aliases are loaded.

```bash
# Mount your local model_aliases.json file
docker run -v /path/to/your/model_aliases.json:/home/ubuntu/speaches/model_aliases.json speaches
```

--------------------------------

### Configure Speaches AI via Docker Compose Environment Variables

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/open-webui-integration.md

Configure Open WebUI to use Speaches AI by setting environment variables in your Docker Compose file. This method is useful for automated deployments. Note that this may not work if the STT engine was previously set via the UI.

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ...
    environment:
      ...
      # Environment variables are documented here https://docs.openwebui.com/getting-started/env-configuration#speech-to-text
      AUDIO_STT_ENGINE: "openai"
      AUDIO_STT_OPENAI_API_BASE_URL: "http://speaches:8000/v1"
      AUDIO_STT_OPENAI_API_KEY: "does-not-matter-what-you-put-but-should-not-be-empty"
      AUDIO_STT_MODEL: "Systran/faster-distil-whisper-large-v3"
  speaches:
    image: ghcr.io/speaches-ai/speaches:latest-cuda
    ...
```

--------------------------------

### User Message with Audio Transcribed to Text

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/voice-chat.md

Illustrates the payload after the input audio has been transcribed into text by the Speaches AI proxy.

```json
[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "What is in this recording?"
      },
      {
        "type": "text",
        "text": "Hello World!"
      }
    ]
  }
]
```

--------------------------------

### Download Model using Alias (CLI)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Use the defined alias 'whisper-1' to download a model via the Speaches CLI. This is equivalent to downloading the model using its full repository path.

```bash
# Use alias instead of full model path
uvx speaches-cli model download whisper-1

# This is equivalent to:
uvx speaches-cli model download Systran/faster-whisper-large-v3
```

--------------------------------

### Download a Model (cURL)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Download a specific machine learning model by making a POST request to the /v1/models endpoint using cURL. The model identifier is part of the URL.

```bash
curl "$SPEACHES_BASE_URL/v1/models/Systran/faster-distil-whisper-small.en" -X POST
```

--------------------------------

### Transcribe Audio using cURL

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-to-text.md

Send an audio file for transcription using cURL. Ensure SPEACHES_BASE_URL and TRANSCRIPTION_MODEL_ID are set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"
export TRANSCRIPTION_MODEL_ID="Systran/faster-distil-whisper-small.en"

curl -s "$SPEACHES_BASE_URL/v1/audio/transcriptions" -F "file=@audio.wav" -F "model=$TRANSCRIPTION_MODEL_ID"
```

--------------------------------

### Configure Speaches AI via Open WebUI Settings

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/open-webui-integration.md

Use this method to set Speaches AI as the speech-to-text engine directly within the Open WebUI administration interface. Ensure all required fields are populated correctly.

```text
Speech-to-Text Engine: OpenAI
API Base URL: http://speaches:8000/v1
API Key: does-not-matter-what-you-put-but-should-not-be-empty
Model: Systran/faster-distil-whisper-large-v3
```

--------------------------------

### Generate Speech using cURL (WAV)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/text-to-speech.md

Generates speech from text using cURL, saving the output as a WAV file. Requires SPEACHES_BASE_URL, SPEECH_MODEL_ID, and VOICE_ID to be set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"
export SPEECH_MODEL_ID="speaches-ai/Kokoro-82M-v1.0-ONNX"

export VOICE_ID="af_heart"

curl "$SPEACHES_BASE_URL/v1/audio/speech" -s -H "Content-Type: application/json" \
  --output audio.wav \
  --data @- << EOF
{
  "input": "Hello World!",
  "model": "$SPEECH_MODEL_ID",
  "voice": "$VOICE_ID",
  "response_format": "wav"
}
EOF
```

--------------------------------

### Realtime API with Additional Parameters

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/realtime-api.md

Configure the Speaches Realtime API endpoint with additional URL parameters for enhanced flexibility. This allows specifying the intent, language, and transcription model.

```url
/v1/realtime?model=your-model&intent=transcription&language=en&transcription_model=whisper-1
```

--------------------------------

### Generate Speech using cURL (MP3)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/text-to-speech.md

Generates speech from text using cURL, saving the output as an MP3 file. Requires SPEACHES_BASE_URL, SPEECH_MODEL_ID, and VOICE_ID to be set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"
export SPEECH_MODEL_ID="speaches-ai/Kokoro-82M-v1.0-ONNX"

export VOICE_ID="af_heart"

# Generate speech
curl "$SPEACHES_BASE_URL/v1/audio/speech" -s -H "Content-Type: application/json" \
  --output audio.mp3 \
  --data @- << EOF
{
  "input": "Hello World!",
  "model": "$SPEECH_MODEL_ID",
  "voice": "$VOICE_ID"
}
EOF
```

--------------------------------

### Generate Speech using cURL (Faster Speed)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/text-to-speech.md

Generates speech from text using cURL with an increased speed, saving the output as an MP3 file. Requires SPEACHES_BASE_URL, SPEECH_MODEL_ID, and VOICE_ID to be set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"
export SPEECH_MODEL_ID="speaches-ai/Kokoro-82M-v1.0-ONNX"

export VOICE_ID="af_heart"

curl "$SPEACHES_BASE_URL/v1/audio/speech" -s -H "Content-Type: application/json" \
  --output audio.mp3 \
  --data @- << EOF
{
  "input": "Hello World!",
  "model": "$SPEECH_MODEL_ID",
  "voice": "$VOICE_ID",
  "speed": 2.0
}
EOF
```

--------------------------------

### Calculate Voice Similarity with Embeddings

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

Compares two audio files by generating their speech embeddings and calculating the cosine similarity. Use this to quickly assess how alike two voice samples are. Requires audio files and a specified model ID.

```python
import httpx
import numpy as np

def get_embedding(audio_path: str, model_id: str) -> list[float]:
    with open(audio_path, 'rb') as f:
        files = {'file': (audio_path, f)}
        data = {'model': model_id}
        response = httpx.post(
            'http://localhost:8000/v1/audio/speech/embedding',
            files=files,
            data=data
        )
    result = response.json()
    return result['data'][0]['embedding']

def cosine_similarity(embedding1: list[float], embedding2: list[float]) -> float:
    vec1 = np.array(embedding1)
    vec2 = np.array(embedding2)
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

model_id = 'pyannote/wespeaker-voxceleb-resnet34-LM'

embedding1 = get_embedding('speaker1.wav', model_id)
embedding2 = get_embedding('speaker2.wav', model_id)

similarity = cosine_similarity(embedding1, embedding2)
print(f"Cosine similarity: {similarity:.4f}")

if similarity > 0.8:
    print("High similarity - likely the same speaker")
elif similarity > 0.5:
    print("Moderate similarity - possibly the same speaker")
else:
    print("Low similarity - likely different speakers")

```

--------------------------------

### JavaScript - Simple Transcription

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/realtime-api.md

This JavaScript snippet demonstrates a basic WebSocket connection for real-time transcription. It parses incoming messages and logs the completed transcription.

```javascript
const ws = new WebSocket("wss://speaches-server/v1/realtime?model=your-transcription-model&intent=transcription&api_key=your-api-key");

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'conversation.item.input_audio_transcription.completed') {
        console.log('Transcription:', data.transcript);
    }
};
```

--------------------------------

### List Models by Task Type (cURL)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Filter the list of available models by specifying a task type in the query parameter when using cURL to access the /v1/registry endpoint.

```bash
curl "$SPEACHES_BASE_URL/v1/registry?task=automatic-speech-recognition"
```

--------------------------------

### Configure Model Aliases in Docker Compose

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Configure the `volumes` section in your `docker-compose.yaml` file to mount the `model_aliases.json` file into the Speaches container.

```yaml
services:
  speaches:
    volumes:
      - ./model_aliases.json:/home/ubuntu/speaches/model_aliases.json
```

--------------------------------

### Implement Speaker Verification System

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

A class-based approach to speaker verification that enrolls a voice sample and then verifies against it. Useful for applications requiring reliable speaker identification. Requires audio files, a base URL, model ID, and a similarity threshold.

```python
import httpx
import numpy as np
from pathlib import Path

class SpeakerVerifier:
    def __init__(self, base_url: str, model_id: str, threshold: float = 0.7):
        self.base_url = base_url
        self.model_id = model_id
        self.threshold = threshold

    def get_embedding(self, audio_path: str | Path) -> np.ndarray:
        with open(audio_path, 'rb') as f:
            files = {'file': (str(audio_path), f)}
            data = {'model': self.model_id}
            response = httpx.post(
                f'{self.base_url}/v1/audio/speech/embedding',
                files=files,
                data=data
            )
        result = response.json()
        return np.array(result['data'][0]['embedding'])

    def cosine_similarity(self, emb1: np.ndarray, emb2: np.ndarray) -> float:
        return np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2))

    def verify(self, enrollment_audio: str | Path, test_audio: str | Path) -> tuple[bool, float]:
        enrollment_embedding = self.get_embedding(enrollment_audio)
        test_embedding = self.get_embedding(test_audio)
        similarity = self.cosine_similarity(enrollment_embedding, test_embedding)
        is_same_speaker = similarity > self.threshold
        return is_same_speaker, similarity

verifier = SpeakerVerifier(
    base_url='http://localhost:8000',
    model_id='pyannote/wespeaker-voxceleb-resnet34-LM',
    threshold=0.7
)

is_same, score = verifier.verify('enrollment.wav', 'test.wav')
print(f"Same speaker: {is_same}, Similarity score: {score:.4f}")

```

--------------------------------

### Add Custom Model Aliases

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Add new custom model aliases or modify existing ones in the `model_aliases.json` file. Ensure you restart the server for changes to take effect.

```json
{
  "my-whisper": "openai/whisper-large-v3",
  "fast-tts": "speaches-ai/Kokoro-82M-v1.0-ONNX"
}
```

--------------------------------

### Access Model Info using Alias (cURL)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/model-discovery.md

Make API requests using a model alias, such as 'whisper-1', with cURL. This simplifies API calls by using the friendly alias name instead of the full model ID.

```bash
# Use alias in API requests
curl "$SPEACHES_BASE_URL/v1/models/whisper-1" -X POST

# This is equivalent to:
curl "$SPEACHES_BASE_URL/v1/models/Systran/faster-whisper-large-v3" -X POST
```

--------------------------------

### Extract Speech Embedding via Python (httpx)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

Use the httpx library in Python to send an audio file and model ID for speech embedding extraction. The code prints the dimension of the extracted embedding.

```python
import httpx

with open('audio.wav', 'rb') as f:
    files = {'file': ('audio.wav', f)}
    data = {'model': 'pyannote/wespeaker-voxceleb-resnet34-LM'}
    response = httpx.post(
        'http://localhost:8000/v1/audio/speech/embedding',
        files=files,
        data=data
    )

result = response.json()
embedding = result['data'][0]['embedding']
print(f"Embedding dimension: {len(embedding)}")
```

--------------------------------

### Set SPEACHES_BASE_URL Environment Variable

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/vad.md

Before making API requests, set the SPEACHES_BASE_URL environment variable to your Speaches API endpoint.

```shell
export SPEACHES_BASE_URL="http://localhost:8000"
```

--------------------------------

### Extract Speech Embedding via Python (requests)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

Use the requests library in Python to send an audio file and model ID for speech embedding extraction. The code prints the dimension of the extracted embedding.

```python
import requests

with open('audio.wav', 'rb') as f:
    files = {'file': ('audio.wav', f)}
    data = {'model': 'pyannote/wespeaker-voxceleb-resnet34-LM'}
    response = requests.post(
        'http://localhost:8000/v1/audio/speech/embedding',
        files=files,
        data=data
    )

result = response.json()
embedding = result['data'][0]['embedding']
print(f"Embedding dimension: {len(embedding)}")
```

--------------------------------

### Extract Speech Embedding via Curl

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

Use cURL to send an audio file and model ID to the speech embedding API endpoint. Ensure SPEACHES_BASE_URL and EMBEDDING_MODEL_ID are set.

```bash
export SPEACHES_BASE_URL="http://localhost:8000"
export EMBEDDING_MODEL_ID="pyannote/wespeaker-voxceleb-resnet34-LM"

curl -s "$SPEACHES_BASE_URL/v1/audio/speech/embedding" \
  -F "file=@audio.wav" \
  -F "model=$EMBEDDING_MODEL_ID"
```

--------------------------------

### Transcription-Only Mode WebSocket Connection (Speaches Extension)

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/realtime-api.md

Connect to the Speaches server for transcription-only mode using a WebSocket. This mode disables AI response generation and is useful for speech-to-text applications. It can be configured via URL parameters or headers.

```javascript
// Transcription-only mode (Speaches extension)
const ws = new WebSocket(
  "wss://your-speaches-server/v1/realtime?model=deepdml/faster-whisper-large-v3-turbo-ct2&intent=transcription&api_key=your-api-key"
);

// Or with headers
const ws = new WebSocket("wss://your-speaches-server/v1/realtime?model=deepdml/faster-whisper-large-v3-turbo-ct2&intent=transcription", {
  headers: {
    'Authorization': 'Bearer your-api-key'
  }
});
```

--------------------------------

### Speech Embedding API Response Format

Source: https://github.com/speaches-ai/speaches/blob/master/docs/usage/speech-embedding.md

The response from the Speech Embedding API follows a structure similar to OpenAI's text embedding endpoint, providing a list of embeddings for the input audio.

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.006929283495992422,
        -0.005336422007530928,
        -4.547132266452536e-5,
        -0.024047505110502243,
        ...
      ]
    }
  ],
  "model": "pyannote/wespeaker-voxceleb-resnet34-LM",
  "usage": {
    "prompt_tokens": 48000,
    "total_tokens": 48000
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.