# How to Set Up the Supertonic Serve HTTP Server with Custom Endpoints

> Learn to set up the supertonic serve HTTP server with custom endpoints. Extend built-in TTS functionality with your own business logic using FastAPI and APIRouter.

- Repository: [Supertone Inc./supertonic](https://github.com/supertone-inc/supertonic)
- Tags: how-to-guide
- Published: 2026-06-14

---

**Use the `create_app()` factory function from `supertonic.server` to instantiate the FastAPI application, attach custom `APIRouter` instances, and launch with uvicorn to extend the built-in TTS endpoints with your own business logic.**

The **supertonic serve HTTP server** is a production-ready FastAPI application that ships with the `supertone-inc/supertonic` Python package. While the CLI command `supertonic serve` launches a standard server with native Text-to-Speech (TTS) endpoints, the underlying architecture allows you to import the application factory and mount custom routers for health checks, preprocessing, or domain-specific APIs.

## Understanding the Built-in Server Architecture

The server is implemented as a standard FastAPI application that wraps the Supertonic inference engine. When you need to customize behavior, you work directly with the factory function rather than modifying internal source files.

### Built-in Routes

The stock server automatically registers two inference endpoints:

- **`POST /v1/tts`** – Native Supertonic inference accepting JSON payloads with `text`, `lang`, `voice_style`, `total_steps`, and `speed` parameters
- **`POST /v1/audio/speech`** – OpenAI-compatible endpoint that mirrors the `/v1/audio/speech` contract for drop-in client compatibility

Both routes expose the interactive OpenAPI documentation at `http://<host>:<port>/docs`.

### Core Source Files

According to the `supertonic-py` source code, the server logic is split across these modules:

| File | Purpose |
|------|---------|
| [`supertonic/server.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/server.py) | Contains the `create_app()` factory that builds the FastAPI instance and registers native routes |
| [`supertonic/cli/serve.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/cli/serve.py) | CLI entry point that parses `--host`/`--port` arguments and launches uvicorn |
| [`supertonic/api.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/api.py) | Implements request models and the two endpoint handlers |
| [`supertonic/tts.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/tts.py) | Houses the `TextToSpeech` class used for inference |

Under the hood, `create_app()` loads model assets, instantiates the `TextToSpeech` object, and injects it into FastAPI’s dependency system for use by the built-in routes.

## Running the Stock Server

For standard use cases without custom logic, the CLI provides immediate access to the HTTP API.

### Installation

Install the package with the server extras to include FastAPI and uvicorn dependencies:

```bash
pip install "supertonic[serve]"

```

### CLI Usage

Launch the server with custom host and port bindings:

```bash
supertonic serve --host 0.0.0.0 --port 8080

```

The server starts on the specified interface and automatically serves the OpenAPI documentation at `/docs`. You can immediately POST to `http://localhost:8080/v1/tts`:

```bash
curl -X POST http://localhost:8080/v1/tts \
     -H "Content-Type: application/json" \
     -d '{
           "text": "Hello from Supertonic",
           "lang": "en",
           "voice_style": {"style_ttl": "...", "style_dp": "..."},
           "total_steps": 8,
           "speed": 1.0
         }' \
     --output output.wav

```

## Adding Custom Endpoints to Supertonic Serve

Because the server exposes a standard FastAPI application instance, you can extend it using FastAPI’s `APIRouter` pattern. This approach keeps your custom code separate from the core library while sharing the same process and request-handling pipeline.

### Importing the Factory Function

The entry point for customization is the `create_app()` function in [`supertonic/server.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/server.py). Import this factory to get a pre-configured FastAPI instance that already includes the TTS routes:

```python
from supertonic.server import create_app
from fastapi import APIRouter

# Create the base application with /v1/tts and /v1/audio/speech

app = create_app()

```

### Creating Custom Routers

Define your business logic using FastAPI’s `APIRouter`, then mount it to the application:

```python
custom_router = APIRouter()

@custom_router.get("/health")
def health_check():
    """Kubernetes-style health probe."""
    return {"status": "ok", "service": "supertonic"}

@custom_router.post("/v1/custom/preprocess")
def preprocess_text(payload: dict):
    """Custom preprocessing before TTS generation."""
    cleaned_text = payload.get("text", "").strip().lower()
    return {"processed": cleaned_text, "original_length": len(payload.get("text", ""))}

# Mount the router

app.include_router(custom_router)

```

### Full Custom Server Example

Combine the factory, custom routers, and uvicorn launcher in a single executable script:

```python

# file: custom_server.py

from supertonic.server import create_app
from fastapi import APIRouter
import uvicorn

# Initialize custom router

custom_router = APIRouter()

@custom_router.get("/health")
def health_check():
    return {"status": "ok"}

@custom_router.post("/echo")
def echo(payload: dict):
    """Debug endpoint to verify request routing."""
    return {"received": payload}

# Build application with built-in + custom routes

app = create_app()
app.include_router(custom_router)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=7788)

```

Running `python custom_server.py` starts the server with both the native Supertonic endpoints and your custom routes available on the same port.

## Production Deployment Patterns

When deploying the customized server to production, treat it as a standard Python application rather than using the CLI tool.

### Docker Configuration

Containerize your custom server by copying the script and installing dependencies:

```dockerfile
FROM python:3.11-slim
WORKDIR /app

# Install supertonic with server dependencies

RUN pip install "supertonic[serve]"

# Copy your custom server implementation

COPY custom_server.py .

EXPOSE 7788
CMD ["python", "custom_server.py"]

```

This pattern ensures your custom endpoints (health checks, metrics, preprocessing) run alongside the TTS inference engine in a single containerized process.

## Summary

- **supertonic serve HTTP server** is a FastAPI application exposed through the `create_app()` factory in [`supertonic/server.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/server.py)
- The stock CLI command launches uvicorn with built-in routes at `/v1/tts` and `/v1/audio/speech`
- To add custom endpoints, import `create_app()`, attach `APIRouter` instances, and launch with uvicorn directly
- The `TextToSpeech` inference engine is injected into the FastAPI dependency system and shared across all routes
- Production deployments should use the factory pattern with custom scripts rather than the CLI entry point

## Frequently Asked Questions

### How do I add authentication to the Supertonic serve HTTP server?

Mount a custom `APIRouter` with FastAPI’s `Depends` and security utilities. Since `create_app()` returns a standard FastAPI instance, you can apply middleware or dependency injection at the app level before starting uvicorn. Apply your authentication logic to the custom router or use `app.add_middleware()` to protect all endpoints including the built-in TTS routes.

### Can I modify the built-in `/v1/tts` endpoint behavior?

The built-in routes are registered inside `create_app()` in [`supertonic/server.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/server.py) and defined in [`supertonic/api.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/api.py). Rather than modifying source files, create a custom endpoint that preprocesses the payload, calls the native endpoint internally, or post-processes the response. Alternatively, import the `TextToSpeech` class directly from [`supertonic/tts.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/tts.py) and build a completely custom FastAPI app without using `create_app()`.

### What is the difference between `supertonic serve` and using `create_app()` directly?

The CLI command `supertonic serve` (implemented in [`supertonic/cli/serve.py`](https://github.com/supertone-inc/supertonic/blob/main/supertonic/cli/serve.py)) is a convenience wrapper that parses arguments and calls `create_app()` followed by `uvicorn.run()`. Using `create_app()` directly gives you programmatic control to attach additional FastAPI routers, configure middleware, or modify the application instance before the server starts, which is necessary for adding custom endpoints.

### Does the custom server support OpenAI-compatible endpoints?

Yes. When you instantiate the app via `create_app()`, the OpenAI-compatible endpoint at `POST /v1/audio/speech` is automatically registered alongside the native `/v1/tts` route. This endpoint remains available even when you attach custom routers, allowing existing OpenAI SDK clients to communicate with your customized server without code changes.