---
title: "Deploy Speaches Audio API + Model Cache"
description: "OpenAI-compatible speech to text and text to speech with a model cache"
category: "AI/ML"
url: https://railway.com/deploy/speaches-audio-api-model-cache
---

# Deploy Speaches Audio API + Model Cache

OpenAI-compatible speech to text and text to speech with a model cache

**[Deploy Speaches Audio API + Model Cache on Railway](https://railway.com/template/speaches-audio-api-model-cache)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/speaches-audio-api-model-cache/manifest.json

- **Creator:** Protemplate
- **Category:** AI/ML
- **Total deploys:** 1

## Template content

### Speaches https://avatars.githubusercontent.com/u/192631691?v=4

- **Image:** ghcr.io/speaches-ai/speaches:0.9.0-rc.3-cpu
- **Health check:** /health
- **Public domain:** Yes

## Documentation

# Deploy and Host Speaches on Railway

Speaches is a self-hosted, OpenAI-compatible speech server. One endpoint handles speech to text with faster-whisper or Parakeet, text to speech with Kokoro or Piper, voice activity detection, speaker embeddings and the OpenAI Realtime API over WebSocket and WebRTC. It runs on CPU, ships a browser playground, and drops straight into any OpenAI SDK by changing the base URL.

## About Hosting Speaches

Hosting Speaches is a single container plus one volume. This template uses the official CPU image `ghcr.io/speaches-ai/speaches:0.9.0-rc.3-cpu` and gives the Hugging Face model cache a Railway volume at `/home/ubuntu/.cache/huggingface/hub`, so models are downloaded once rather than on every deploy. Speaches never downloads a model implicitly, so the template preloads a Whisper model and a Kokoro voice model at startup and the API answers real requests as soon as the healthcheck goes green. `API_KEY` is generated at deploy time and guards every `/v1` route, while `/health` stays public so Railway can probe it. `PORT` and `UVICORN_PORT` are both pinned to 8000, the bind address is `0.0.0.0` because uvicorn treats an explicit IPv6 bind as IPv6 only, and the healthcheck window is 900 seconds because the first boot downloads about 800 MB of models before the port opens. Inference runs on CPU and wants roughly 2 GB of RAM, so use the Hobby plan or higher.

## Common Use Cases

- **Drop-in OpenAI audio replacement**: point any OpenAI SDK at `/v1` for `audio.transcriptions`, `audio.translations` and `audio.speech`
- **Transcription pipelines**: meeting notes, podcast indexing, call summaries, subtitle generation in srt or vtt
- **Voice for chat UIs and agents**: Open WebUI, LibreChat, SillyTavern and voice assistants get both ears and a voice from one service
- **Realtime voice sessions**: the OpenAI Realtime API over WebSocket or WebRTC, with a bundled console at `/v1/realtime`
- **Private speech processing**: audio never leaves your Railway project, which matters for recordings you cannot send to a third party

## Dependencies for Speaches Hosting

- **A Railway volume**: for the Hugging Face model cache
- **Hugging Face Hub**: reachable on first boot to download models. No token needed for the default public models
- **Memory**: about 2 GB, 4 GB if you expect concurrent requests
- **No database, no GPU, no external API keys**

### Deployment Dependencies

- [Speaches GitHub repository](https://github.com/speaches-ai/speaches)
- [Documentation site](https://speaches.ai/)
- [Configuration reference](https://speaches.ai/configuration/)
- [Model discovery guide](https://github.com/speaches-ai/speaches/blob/v0.9.0-rc.3/docs/usage/model-discovery.md)

### Implementation Details

The image CMD is `uvicorn --factory speaches.main:create_app`, and uvicorn reads `UVICORN_HOST` and `UVICORN_PORT` from the environment, so no custom start command is needed. Key variables:

```env
PORT=8000
UVICORN_PORT=8000
UVICORN_HOST=0.0.0.0
API_KEY=${{secret(32)}}
RAILWAY_RUN_UID=0
HF_HOME=/home/ubuntu/.cache/huggingface
PRELOAD_MODELS=["Systran/faster-whisper-small","speaches-ai/Kokoro-82M-v1.0-ONNX"]
WHISPER__COMPUTE_TYPE=int8
```

`RAILWAY_RUN_UID=0` is required: the image runs as user `ubuntu` (UID 1000) and Railway volumes mount root-owned, so the cache would otherwise be unwritable.

**First steps after deploy**

1. Wait for `/health` to return `{"message":"OK"}`. The first boot downloads about 800 MB of models before the port opens, so give it several minutes. Later boots read the volume and start quickly.
2. Copy `API_KEY` from the service variables.
3. Open your Railway domain in a browser, paste the key into the playground's API Key box, and try the Speech to Text and Text to Speech tabs.
4. Point your app at `https://your-domain/v1` with that key as the OpenAI API key, using model `Systran/faster-whisper-small` for transcription and `tts-1` or `speaches-ai/Kokoro-82M-v1.0-ONNX` for speech.
5. Add more models any time with `POST /v1/models/{model_id}`, and browse what is available at `GET /v1/registry`.

Two things to know. The alias `whisper-1` resolves to `Systran/faster-whisper-large-v3`, which is not preloaded, so name a real model or add it to `PRELOAD_MODELS`. And because the service binds IPv4, sibling Railway services should call the public domain rather than `speaches.railway.internal`.

Avoid the `latest-cpu` tag when upgrading. It currently resolves to 0.8.3, where the API key also guards `/health` and the Railway healthcheck fails.

## Why Deploy Speaches on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Speaches on Railway, you get a pinned, authenticated, health-checked OpenAI-compatible speech endpoint with managed SSL, a persistent model cache, and no per-minute transcription or per-character synthesis bill.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/speaches-audio-api-model-cache