---
title: "Deploy Piper TTS | (Just Updated) OpenAI-Compatible Speech API, Bearer Key From Boot"
description: "Piper text-to-speech OpenAI-compatible API with generated bearer key"
category: "AI/ML"
url: https://railway.com/deploy/piper-tts-or-just-updated-openai-compati
---

# Deploy Piper TTS | (Just Updated) OpenAI-Compatible Speech API, Bearer Key From Boot

Piper text-to-speech OpenAI-compatible API with generated bearer key

**[Deploy Piper TTS | (Just Updated) OpenAI-Compatible Speech API, Bearer Key From Boot on Railway](https://railway.com/template/piper-tts-or-just-updated-openai-compati)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/piper-tts-or-just-updated-openai-compati/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** AI/ML

## Template content

### piper

- **Image:** ghcr.io/bon5co/piper-railway:1.8.0@sha256:9c497a7da3516d5b4277d5bb5caae579217f260f9d11fad49e7880e5f81d3ba5
- **Health check:** /healthz
- **Public domain:** Yes

## Documentation

# Deploy and Host Piper TTS on Railway

**Built for an LLM agent to deploy and use.** There is nothing to fill in: the API key is generated at deploy time, every speech request needs it, a voice is already installed, and the contract below lists every URL and variable name with one script that checks health, auth and a real synthesis.

Piper is a fast, local neural text-to-speech engine that runs on CPU with no GPU and no external API. This template runs Piper 1.8 behind a small server that speaks the OpenAI speech API, so any client that can call `/v1/audio/speech` can use it by changing the base URL and the key.

## About Hosting Piper TTS

This template runs one service, built from the public wrapper [bon5co/piper-railway](https://github.com/bon5co/piper-railway) (piper-tts `1.8.0`, pinned by digest), with the volume at `/data`. Piper's own HTTP server has no authentication, so a public URL would let anyone use your CPU. Here every request under `/v1/` needs `Authorization: Bearer` plus the value of `API_KEY`; anything else gets 401. Only `/healthz` is open, and it returns 200 once the default voice is loaded.

The image ships one voice, `en_US-ljspeech-high` (trained on the public-domain LJ Speech dataset), and copies it onto the volume at first boot. Add more by setting `EXTRA_VOICES` to a comma separated list of Piper voice names such as `en_GB-alan-medium,de_DE-thorsten-medium` and redeploying, or by copying a voice's `.onnx` and `.onnx.json` files into `/data/voices`. Check each added voice's licence: some datasets are non-commercial. ONNX Runtime thread pools are sized from the container's CPU quota, not the host's core count, so synthesis does not slow down on a shared host. Output formats are `wav`, `pcm`, `mp3`, `opus`, `aac` and `flac`.

### Agent contract

- Public URL: `https://RAILWAY_PUBLIC_DOMAIN`, on the `piper` service (set `PIPER_URL` to it, no trailing slash)
- Private URL: `http://piper.railway.internal:8080` (key required)
- Credentials: the key is in `API_KEY` (on the `piper` service)
- Auth: send `Authorization: Bearer API_KEY` on every `/v1/` request; a missing or wrong key gets 401
- Health: `GET /healthz` returns 200 with no credentials once the default voice is loaded

```bash
# run with PIPER_URL and API_KEY (piper service); needs curl
curl -s -o /dev/null -w 'health %{http_code}\n' "$PIPER_URL/healthz"
curl -s -o /dev/null -w 'anonymous %{http_code}\n' "$PIPER_URL/v1/voices"
curl -s -o /dev/null -w 'wrong key %{http_code}\n' -H 'Authorization: Bearer wrong' "$PIPER_URL/v1/voices"
curl -s -H "Authorization: Bearer $API_KEY" "$PIPER_URL/v1/voices"; echo
curl -s -o speech.wav -w 'speech %{http_code} %{size_download} bytes\n' -X POST "$PIPER_URL/v1/audio/speech" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"input":"Hello from Piper on Railway.","response_format":"wav"}'
head -c 4 speech.wav; echo
```

A fresh deploy prints `health 200`, `anonymous 401`, `wrong key 401`, the voice list with `en_US-ljspeech-high`, `speech 200` with a size in the tens of kilobytes, and `RIFF`. The `voice` field is optional: a name that is not installed (including OpenAI names such as `alloy`) falls back to the default voice. `speed` takes 0.25 to 4.0.

## Why Deploy Piper TTS 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 Piper TTS on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

- **Agent-ready** - generated key, a contract block and one working script; no setup step.
- **Closed by default** - Piper's own server has no auth; here every speech call needs the key.
- **OpenAI-compatible** - point an existing speech client at the URL and key, no code change.
- **Light on CPU** - a voice runs in about 250 MB of memory and needs no GPU.
- **State survives redeploys** - voices live on the volume, and the key stays the same after every redeploy.

## Common Use Cases

- **Voice for AI agents** - give an agent a private speech endpoint that returns audio from text with one authenticated call.
- **App narration and notifications** - read articles, alerts or lessons aloud without paying per character to a cloud TTS.
- **Self-hosted OpenAI TTS replacement** - keep text on your own infrastructure and cut the per-request bill.

## Dependencies for Piper TTS Hosting

- A volume at `/data` (included in this template).

### Deployment Dependencies

- [OHF-Voice/piper1-gpl](https://github.com/OHF-Voice/piper1-gpl) - Piper, upstream project (GPL-3.0-or-later)
- [rhasspy/piper-voices](https://huggingface.co/rhasspy/piper-voices) - voice models and their licences
- [bon5co/piper-railway](https://github.com/bon5co/piper-railway) - the wrapper image this template deploys


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius v0.1 Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/piper-tts-or-just-updated-openai-compati