### Initialize and Start Project with Makefile

Source: https://github.com/deepgram-starters/rust-text-to-speech/blob/main/README.md

Use this Makefile to initialize the project, set up environment variables by copying a sample file, and start the local development server. Ensure your DEEPGRAM_API_KEY is added to the .env file.

```bash
make init
cp sample.env .env  # Add your DEEPGRAM_API_KEY
make start
```

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

### Install Backend and Frontend Dependencies

Source: https://github.com/deepgram-starters/rust-text-to-speech/blob/main/AGENTS.md

Install backend dependencies using Cargo and frontend dependencies using pnpm. Ensure you have Rust and Node.js (with pnpm) installed.

```bash
cargo build
```

```bash
cd frontend && corepack pnpm install
```

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

### Project Initialization and Build Commands

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Makefile commands for managing project dependencies, starting servers, and running tests.

```bash
# Check prerequisites (git, rustc, cargo, pnpm)
make check-prereqs

# Initialize submodules and install dependencies
make init

# Copy sample environment file and add your API key
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

# Start both backend and frontend servers
make start

# Or start only the backend server
make start-backend

# Build frontend for production
make build

# Run contract conformance tests
make test

# Clean build artifacts
make clean
```

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

### Initialize and Run Deepgram TTS App

Source: https://github.com/deepgram-starters/rust-text-to-speech/blob/main/AGENTS.md

Use these make commands to initialize dependencies, set up the environment by copying a sample .env file, and start both the backend and frontend servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

```bash
make start
```

```bash
# Terminal 1 — Backend
cargo run

# Terminal 2 — Frontend
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

```bash
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
```

```bash
rm -rf target frontend/node_modules frontend/.vite
make init
```

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

### GET /api/metadata

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Retrieves project metadata parsed from the configuration file.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata including title, description, author, and tags parsed from deepgram.toml.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Project title
- **description** (string) - Project description
- **author** (string) - Author information
- **repository** (string) - GitHub repository URL
- **tags** (array) - List of project tags

#### Response Example
{
  "title": "Rust Text-to-Speech",
  "description": "Get started using Deepgram's Text-to-Speech with this Rust demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com>",
  "repository": "https://github.com/deepgram-starters/rust-text-to-speech",
  "tags": ["text-to-speech", "tts", "audio-generation", "rust", "axum"]
}
```

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

### Conventional Commit Examples

Source: https://github.com/deepgram-starters/rust-text-to-speech/blob/main/AGENTS.md

Follow these formats for all project commits. Exclude Co-Authored-By lines for Claude.

```text
feat(rust-text-to-speech): add diarization support
fix(rust-text-to-speech): resolve WebSocket close handling
refactor(rust-text-to-speech): simplify session endpoint
chore(deps): update frontend submodule
```

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

### GET /health

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Provides a simple health check for monitoring purposes.

```APIDOC
## GET /health

### Description
Provides a simple health check for monitoring and load balancer configurations.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.

#### Response Example
{
  "status": "ok"
}
```

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

### GET /api/session

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Issues a JWT token for authenticating subsequent API requests.

```APIDOC
## GET /api/session

### Description
Issues a JWT token for authenticating subsequent API requests. Tokens are signed using an environment-configured or random secret with a 1-hour expiration.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - The JWT session token.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Complete Text-to-Speech Workflow in Rust

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Demonstrates obtaining a session token and using it to convert text to speech, saving the resulting audio to a file.

```rust
use reqwest::Client;
use serde::Deserialize;
use std::fs::File;
use std::io::Write;

#[derive(Deserialize)]
struct SessionResponse {
    token: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let base_url = "http://localhost:8081";

    // Step 1: Get session token
    let session: SessionResponse = client
        .get(format!("{}/api/session", base_url))
        .send()
        .await?
        .json()
        .await?;

    println!("Got session token: {}...", &session.token[..20]);

    // Step 2: Convert text to speech
    let audio_bytes = client
        .post(format!("{}/api/text-to-speech?model=aura-2-thalia-en", base_url))
        .header("Authorization", format!("Bearer {}", session.token))
        .header("Content-Type", "application/json")
        .body(r#"{"text": "Hello from the Rust Text-to-Speech API!"}"#)
        .send()
        .await?
        .bytes()
        .await?;

    // Step 3: Save audio to file
    let mut file = File::create("output.mp3")?;
    file.write_all(&audio_bytes)?;

    println!("Audio saved to output.mp3 ({} bytes)", audio_bytes.len());

    Ok(())
}
```

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

### Environment Configuration

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Required and optional environment variables for server configuration.

```bash
# Required - Deepgram API key from https://console.deepgram.com
DEEPGRAM_API_KEY=your_api_key_here

# Optional - Backend API server port (default: 8081)
PORT=8081

# Optional - Server host binding (default: 0.0.0.0)
HOST=0.0.0.0

# Optional - Session secret for JWT signing (auto-generated if not set)
SESSION_SECRET=your_secret_key_here
```

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

### Retrieve Project Metadata

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Fetches application metadata defined in the deepgram.toml configuration file.

```bash
# Get project metadata
curl -X GET http://localhost:8081/api/metadata

# Response
{
  "title": "Rust Text-to-Speech",
  "description": "Get started using Deepgram's Text-to-Speech with this Rust demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/rust-text-to-speech",
  "useCase": "text-to-speech",
  "language": "rust",
  "framework": "axum",
  "sdk": "N/A",
  "tags": ["text-to-speech", "tts", "audio-generation", "rust", "axum"]
}
```

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

### Testing and Endpoint Verification

Source: https://github.com/deepgram-starters/rust-text-to-speech/blob/main/AGENTS.md

Execute conformance tests or manually verify API endpoints using curl.

```bash
# Run conformance tests (requires app to be running)
make test

# Manual endpoint check
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

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

### POST /api/text-to-speech

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Converts text input into binary MP3 audio data using Deepgram's TTS service.

```APIDOC
## POST /api/text-to-speech

### Description
Converts text to audio using Deepgram's TTS service. Requires Bearer token authentication.

### Method
POST

### Endpoint
/api/text-to-speech

### Parameters
#### Query Parameters
- **model** (string) - Optional - The voice model to use (defaults to aura-2-thalia-en).

#### Request Body
- **text** (string) - Required - The text content to convert to speech.

### Request Example
{
  "text": "Hello, welcome to the Deepgram text-to-speech demo!"
}

### Response
#### Success Response (200)
- **binary** (audio/mpeg) - The generated MP3 audio file.

#### Error Response (400/401)
- **error** (object) - Contains error type, code, and message.
```

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

### Check Server Health

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Verifies the operational status of the API server.

```bash
# Check server health
curl -X GET http://localhost:8081/health

# Response
{
  "status": "ok"
}
```

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

### Request Session Token

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Retrieves a JWT token for authenticating subsequent API requests.

```bash
# Request a session token
curl -X GET http://localhost:8081/api/session

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4MjM0NTYsImV4cCI6MTcwOTgyNzA1Nn0.abc123..."
}
```

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

### Convert Text to Speech

Source: https://context7.com/deepgram-starters/rust-text-to-speech/llms.txt

Converts text to audio using the Deepgram TTS service. Requires a Bearer token and supports optional voice model selection.

```bash
# Convert text to speech with default model
curl -X POST http://localhost:8081/api/text-to-speech \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, welcome to the Deepgram text-to-speech demo!"}' \
  --output speech.mp3

# Use a specific voice model
curl -X POST "http://localhost:8081/api/text-to-speech?model=aura-2-andromeda-en" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "This uses the Andromeda voice model."}' \
  --output speech.mp3

# Error response for empty text (400 Bad Request)
{
  "error": {
    "type": "ValidationError",
    "code": "EMPTY_TEXT",
    "message": "Text parameter is required",
    "details": {
      "originalError": "Text parameter is required"
    }
  }
}

# Error response for invalid token (401 Unauthorized)
{
  "error": {
    "type": "AuthenticationError",
    "code": "INVALID_TOKEN",
    "message": "Invalid session token",
    "details": {}
  }
}
```

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