# LarVoice API Reference

Welcome to the LarVoice API Documentation. This document is designed to be AI-friendly. You can comfortably feed this entire markdown file to an LLM so it can understand and interact with the LarVoice APIs natively.

## Base URL
Production Base URL: `https://larvoice.com/api/v2`

## Authentication
All API endpoints require a Bearer token.
Header structure:
`Authorization: Bearer sk-YOUR_API_KEY`

To get your API key, login to LarVoice and navigate to the **API Management** settings.

---

## 1. Retrieve Account Info & Quota
Get details on your account, specifically to check your remaining AI credit quota before running generation tools.

**Endpoint:** `/me`
**Method:** `GET`
**Headers:**
- `Authorization`: `Bearer sk-YOUR_API_KEY`

**Success Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "credits": 25000,
    "paid_user": true,
    "plan_name": "PRO",
    "plan_end_at": "2024-12-31 23:59:59"
  }
}
```

---

## 2. Text to Speech (TTS) Generation (Streaming)
Transform text into studio-quality synthesized speech using LarVoice's asynchronous chunk streaming architecture.

**Step 1: Initiate Stream Session**
**Endpoint:** `/tts_stream`
**Method:** `POST`
**Headers:**
- `Authorization`: `Bearer sk-YOUR_API_KEY`
- `Content-Type`: `application/json`

**Payload Properties (All defaults highly recommended):**
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | Yes | The textual payload to convert to speech. |
| `ref_voice_id` | integer | Yes | The specific integer ID of the voice. E.g. `1` |
| `language` | string | Yes | E.g. `vi` |
| `audio_format` | string | Yes | `mp3` or `wav` |
| `speed`, `run_speed`, `pitch`, `volume` | float | Yes | Set defaults to `1.0` |
| `strength` | float | Yes | Set default to `2.2` |
| `pause` | float | Yes | Set default to `0` or `0.5` |
| `bass`, `treble`, `compress` | float | Yes | Set defaults to `0` |
| `first_trim_ms`, `last_trim_ms` | integer | Yes | Set defaults to `0` |
| `split_by_newline` | boolean | Yes | `true` or `false` |

**Example Request:**
```json
{
  "text": "Chào mừng bạn đến với hệ thống LarVoice.",
  "ref_voice_id": 1,
  "language": "vi",
  "audio_format": "mp3",
  "speed": 1.0, "run_speed": 1.0, "pitch": 1.0, "volume": 1.0,
  "strength": 2.2, "pause": 0, "bass": 0, "treble": 0, "compress": 0,
  "first_trim_ms": 0, "last_trim_ms": 0, "split_by_newline": false
}
```

**Step 2: Poll for Stream Status**
**Endpoint:** `/download/{uuid}/stream_status`
**Method:** `GET`
**Headers:**
- `Authorization`: `Bearer sk-YOUR_API_KEY`

Use the `uuid`, `base_url`, and `stream_status_url` returned from Step 1 to poll for audio chunks as they complete processing.


---

## 3. Subtitle / Speech to Text (STT) [Upcoming]
Convert pre-recorded audio or external storage files into text transcripts and timestamps.

**Endpoint:** `/stt/transcribe`
**Method:** `POST`
**Headers:**
- `Authorization`: `Bearer sk-YOUR_API_KEY`
- `Content-Type`: `application/json`

**Example Request:**
```json
{
  "audio_url": "https://example.com/audio-snippet.mp3",
  "language": "vi"
}
```

---

## Error Handling

When errors occur, LarVoice returns standard HTTP status codes along with a JSON body explaining the specific error.

**Common Codes:**
- `400 Bad Request`: Invalid payload parameters (e.g. text exceeds limit, bad voice ID).
- `401 Unauthorized`: API key is missing or invalid.
- `403 Forbidden`: API Key has insufficient privileges or soft-deleted.
- `402 Payment Required`: You have insufficient credits to fulfill the request.
- `429 Too Many Requests`: Rate limit exceeded (Default max: 60/minute per API key).
- `500 Internal Server Error`: An acoustic model generation failure.

**Error JSON Structure:**
```json
{
  "success": false,
  "error_code": "INSUFFICIENT_CREDITS",
  "message": "Your account has run out of characters."
}
```

## Best Practices
1. Include caching on your application end to reuse identical audio outputs.
2. Poll or check `/me` initially during your app's boot process to quickly catch an inactive API key or blank quota.
3. If embedding in your own SaaS platform, ensure user text limits correspond to LarVoice limits to avoid 400 Bad Request responses.