voicebox/docs/api/overview.mdx

---
title: "API Overview"
description: "Integrate voice synthesis into your applications with the Voicebox REST API"
---

## Introduction

Voicebox exposes a full REST API that allows you to integrate voice synthesis into your own applications. The API runs on `http://localhost:17493` by default.

<Card title="Interactive API Docs" icon="book" href="http://localhost:17493/docs">
  When Voicebox is running, visit the auto-generated API documentation at `http://localhost:17493/docs`
</Card>

## Base URL

```
http://localhost:17493
```

For remote deployments, replace `localhost` with your server's IP or hostname.

## Authentication

<Note>
  Currently, the API does not require authentication for local development. Authentication will be added in a future release for production deployments.
</Note>

## Quick Example

Here's a simple example of generating speech:

```bash
# Generate speech
curl -X POST http://localhost:17493/generate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "profile_id": "abc123",
    "language": "en"
  }'
```

## API Endpoints

The Voicebox API is organized into several categories:

<CardGroup cols={2}>
  <Card title="Voice Profiles" icon="user" href="/api/voice-profiles">
    Create, list, update, and delete voice profiles
  </Card>
  <Card title="Generation" icon="waveform" href="/api/generation">
    Generate speech from text using voice profiles
  </Card>
  <Card title="Recordings" icon="microphone" href="/api/recordings">
    Record and transcribe audio
  </Card>
  <Card title="Stories" icon="film">
    Create and manage multi-voice stories (coming soon)
  </Card>
</CardGroup>

## Core Endpoints

### Voice Profiles

```http
GET    /profiles              # List all profiles
POST   /profiles              # Create a new profile
GET    /profiles/{id}         # Get profile details
PUT    /profiles/{id}         # Update a profile
DELETE /profiles/{id}         # Delete a profile
POST   /profiles/{id}/samples # Add voice sample
```

### Generation

```http
POST   /generate              # Generate speech
GET    /history               # List generation history
GET    /history/{id}          # Get generation details
DELETE /history/{id}          # Delete from history
```

### Recordings

```http
POST   /recordings            # Start recording
POST   /recordings/stop       # Stop recording
POST   /transcribe            # Transcribe audio
```

## Response Format

All API responses follow a consistent JSON format:

```json
{
  "success": true,
  "data": {
    // Response data
  },
  "error": null
}
```

Error responses:

```json
{
  "success": false,
  "data": null,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}
```

## Data Models

### Voice Profile

```json
{
  "id": "abc123",
  "name": "John Smith",
  "language": "en",
  "description": "Professional narrator voice",
  "created_at": "2024-01-29T12:00:00Z",
  "samples": [
    {
      "id": "sample123",
      "audio_path": "/path/to/sample.wav",
      "duration": 15.5
    }
  ]
}
```

### Generation

```json
{
  "id": "gen123",
  "text": "Hello world",
  "profile_id": "abc123",
  "language": "en",
  "audio_path": "/path/to/output.wav",
  "duration": 2.3,
  "created_at": "2024-01-29T12:00:00Z"
}
```

## TypeScript Client

Voicebox provides an auto-generated TypeScript client with full type safety:

```typescript
import { VoiceboxClient } from '@/lib/api'

const client = new VoiceboxClient({
  baseUrl: 'http://localhost:17493'
})

// Create a profile
const profile = await client.createProfile({
  name: 'John Smith',
  language: 'en'
})

// Generate speech
const generation = await client.generate({
  text: 'Hello world',
  profile_id: profile.id,
  language: 'en'
})
```

The client is automatically generated from the OpenAPI schema. See [Development Setup](/development/setup#generate-openapi-client) for details.

## Rate Limiting

<Info>
  Currently, there are no rate limits for local usage. Rate limiting will be added in a future release for production deployments.
</Info>

## WebSocket Support

<Note>
  Real-time streaming generation via WebSockets is planned for a future release.
</Note>

## Use Cases

<CardGroup cols={2}>
  <Card title="Game Development" icon="gamepad">
    Generate dynamic dialogue for NPCs and characters
  </Card>
  <Card title="Content Creation" icon="video">
    Automate voiceovers for videos and podcasts
  </Card>
  <Card title="Accessibility" icon="universal-access">
    Build text-to-speech tools for visually impaired users
  </Card>
  <Card title="Voice Assistants" icon="robot">
    Create custom voice interfaces
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Voice Profiles API" icon="user" href="/api/voice-profiles">
    Learn how to manage voice profiles
  </Card>
  <Card title="Generation API" icon="waveform" href="/api/generation">
    Generate speech from text
  </Card>
</CardGroup>