> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs-beta-7agmae.voicedub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the VoiceDub API endpoints, authentication, and responses

The VoiceDub API provides programmatic access to AI voice dubbing and custom voice training capabilities. Transform any audio with 10,000+ voices or train your own voice models.

## Base URL

All API requests should be made to:

```
https://api.voicedub.ai
```

## Authentication

The API uses API key authentication. Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Api-Key YOUR_API_KEY
```

Get your API key from the [API Keys Dashboard](https://voicedub.ai/developer/keys).

## Request Format

* **Content-Type:** `application/json` for all POST/PATCH requests
* **Accept:** `application/json` for all responses
* **Encoding:** UTF-8

### Query Parameters

For array query parameters, the API supports multiple syntax formats:

```bash theme={null}
# Repeated parameter names (more widely supported by HTTP clients)
?param=value1&param=value2&param=value3

# Array notation with brackets
?param[]=value1&param[]=value2&param[]=value3

# Indexed array notation
?param[0]=value1&param[1]=value2&param[2]=value3

# Comma-separated values (not recommended since a comma could appear in a value, but easier for testing)
?param=value1,value2,value3
```

**Example usage:**

```bash theme={null}
# Filter voices by multiple genres
GET /v1/voices?genres=pop&genres=rap&genres=rock
GET /v1/voices?genres[]=pop&genres[]=rap&genres[]=rock
GET /v1/voices?genres[0]=pop&genres[1]=rap&genres[2]=rock
GET /v1/voices?genres=pop,rap,rock
```

## Response Format

All API responses return JSON with consistent structure:

### Success Responses

```json theme={null}
{
  "user": {
    "apiCredits": 1000
  }
}
```

### Error Response Examples

**400 Bad Request:**

```json theme={null}
{
  "code": "invalid_arguments",
  "message": "Invalid request parameters or body",
  "errors": {
    "params": "...",
    "query": "...",
    "body": "..."
  }
}
```

**401 Unauthorized:**

```json theme={null}
{
  "code": "unauthorized",
  "message": "You are not authorized to perform this action"
}
```

**403 Insufficient Credits:**

```json theme={null}
{
  "code": "not_enough_credits", 
  "message": "Looks like you don't have enough credits! Purchase more at https://voicedub.ai/developer/billing"
}
```

**404 Not Found:**

```json theme={null}
{
  "code": "not_found",
  "message": "Dub not found"
}
```

**429 Rate Limited:**

```json theme={null}
{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait before making more requests."
}
```

## HTTP Status Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `400` | Bad Request - Invalid parameters        |
| `401` | Unauthorized - Invalid API key          |
| `403` | Forbidden - Insufficient credits        |
| `404` | Not Found - Resource doesn't exist      |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error - Server issue    |

## Endpoints Overview

### User Management

* `GET /v1/me` - Get account information and credit balance

### Voice Dubbing

* `GET /v1/me/dubs/{dubId}` - Get dub details and status
* `POST /v1/me/dubs` - Create a new voice dub
* `POST /v1/me/dubs/{dubId}/preprocess` - Start dub preprocessing
* `POST /v1/me/dubs/{dubId}/generate` - Start dub generation

### Voice Models

* `GET /v1/voices` - List public voices with filtering
* `GET /v1/me/voices/{voiceId}` - Get custom voice details
* `POST /v1/me/voices` - Create a custom voice for training
* `POST /v1/me/voices/{voiceId}/clone` - Start voice training

## Pagination

List endpoints support cursor-based pagination:

<ParamField query="limit" type="integer" default={50}>
  Number of items to return (8-50)
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for next page (from previous response)
</ParamField>

**Paginated Response:**

```json theme={null}
{
  "voices": [...],
  "nextCursor": "2_123e4567-e89b-12d3-a456-426614174001"
}
```

## Webhooks

Webhooks are not currently supported. Use polling to check job status:

* **Dubs:** Poll `/v1/me/dubs/{dubId}` maximum once every 3 seconds
* **Voices:** Poll `/v1/me/voices/{voiceId}` maximum once every 3 seconds

## Rate Limits

The API enforces different rate limits based on the type of operation:

### Read Operations (GET requests)

* **10,000 requests per minute**
* Includes polling endpoints like checking dub/voice status

### Write Operations (POST, PATCH, DELETE requests)

* **500 requests per minute**
* **20,000 requests per hour**
* Includes creating dubs, starting processing, voice training, etc.

### Global Limit

* **15,000 requests per minute** (across all endpoints)

When you exceed rate limits, you'll receive a `429 Too Many Requests` response with retry information in the headers.

<Info>
  For detailed rate limiting behavior and best practices, see our [Rate Limits Guide](/guides/rate-limits).
</Info>

## SDKs and Libraries

Official SDKs are not yet available. For now, use standard HTTP libraries:

<CardGroup cols={2}>
  <Card title="Node.js" icon="js">
    Use `fetch()` or `axios` for HTTP requests
  </Card>

  <Card title="Python" icon="python">
    Use `requests`, `aiohttp`, or `httpx` libraries for HTTP requests
  </Card>

  <Card title="cURL" icon="terminal">
    Use cURL for command-line testing
  </Card>

  <Card title="Postman" icon="square-p">
    Import our [OpenAPI spec](/api-reference/openapi#import-into-api-tools) for testing
  </Card>

  <Card title="Custom SDK" icon="code">
    Generate your own SDK using our [OpenAPI spec](/api-reference/openapi#generate-custom-sdks)
  </Card>
</CardGroup>

## Testing

Use these test resources for development:

### Test Audio URLs

* **Moments:** `https://www.youtube.com/watch?v=14CjyUYO8lE`

### Test Voice IDs

Search for these popular voices:

* **Character voices:** Search "plankton", "spongebob"
* **Music voices:** Search by genre `?genres=pop,rap`
* **Language-specific:** Search by language `?languages=english,spanish`

## Support

* **Documentation:** You're reading it!
* **Discord Community:** [Join here](https://discord.gg/p7nFCn6EtM)
* **Email Support:** [help@voicedub.ai](mailto:help@voicedub.ai)

<Info>
  Ready to start building? Check out our [Quick Start Guide](/quickstart) or dive into the endpoint documentation below.
</Info>