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

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	Contains the create_app() factory that builds the FastAPI instance and registers native routes
supertonic/cli/serve.py	CLI entry point that parses --host/--port arguments and launches uvicorn
supertonic/api.py	Implements request models and the two endpoint handlers
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:

pip install "supertonic[serve]"

CLI Usage

Launch the server with custom host and port bindings:

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:

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. Import this factory to get a pre-configured FastAPI instance that already includes the TTS routes:

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:

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:

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

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
• 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 and defined in 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 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}