# Lovo Integration via LowCodeAPI

## Overview

Lovo (Genny) is a text-to-speech service with natural-sounding AI voices for creating voiceovers, audiobooks, and other audio content.

## Base Endpoint

```
https://api.lowcodeapi.com/lovo/
```

## Authentication

LowCodeAPI handles authentication automatically. You only need to:

1. **Sign up** at https://lovo.ai/
2. **Connect your account** in LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Lovo API key from database
- Apply it to each request with proper X-API-KEY header

**Auth Type**: `API Key` (Header-based)

## API Categories

- Text to Speech AI
- Teams
- Speakers
- Text-To-Speech

## Common Endpoints

### Category: Teams

#### Get team billing information

**Method**: `GET` | **LowCodeAPI Path**: `/v1/teams/status`

**Full URL**:
```
https://api.lowcodeapi.com/lovo/v1/teams/status?api_token={api_token}
```

**Description**: Retrieve billing status and information for your team account.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/lovo/v1/teams/status?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://docs.genny.lovo.ai/reference/apikeyteaminformationcontroller_getusage

---

### Category: Speakers

#### Retrieve speakers

**Method**: `GET` | **LowCodeAPI Path**: `/v1/speakers`

**Full URL**:
```
https://api.lowcodeapi.com/lovo/v1/speakers?page={page}&api_token={api_token}
```

**Description**: Get a list of all available AI voices with filtering and pagination.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | string | Yes | Number of pages to skip (pagination) |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `limit` | string | No | Number of speakers per page |
| `sort` | string | No | Sort by: displayName, locale, gender, speakerType, ageRange |

**Example Request**:
```bash
# Get first page of speakers
curl -X GET "https://api.lowcodeapi.com/lovo/v1/speakers?page=0&limit=50&api_token=YOUR_API_TOKEN"

# Sort by display name
curl -X GET "https://api.lowcodeapi.com/lovo/v1/speakers?page=0&sort=displayName:1&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": [
    {
      "id": "speaker_abc123",
      "displayName": "James",
      "gender": "Male",
      "locale": "en-US",
      "speakerType": "Neural",
      "styles": ["narration", "commercial"]
    }
  ]
}
```

**Official Documentation**: https://docs.genny.lovo.ai/reference/retrieve-speakers

---

### Category: Text-To-Speech

#### Sync TTS

**Method**: `POST` | **LowCodeAPI Path**: `/v1/tts/sync`

**Full URL**:
```
https://api.lowcodeapi.com/lovo/v1/tts/sync?api_token={api_token}
```

**Description**: Convert text to speech with synchronous response (90 second timeout). Returns audio directly or creates job if processing takes longer.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to be converted to audio |
| `speaker` | string | Yes | Speaker ID from Retrieve Speakers API |
| `speed` | number | No | Audio playback speed (0.5 - 2.0, default: 1.0) |
| `speakerStyle` | string | No | Speaker style ID for variety in voice delivery |

**Example Request**:
```bash
# Convert text to speech with specific voice
# Returns audio directly if processed within 90 seconds
curl -X POST "https://api.lowcodeapi.com/lovo/v1/tts/sync?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to our product demo. Today we will explore the amazing features of our platform.",
    "speaker": "SPEAKER_ID",
    "speed": 1.0
  }'
```

**Official Documentation**: https://docs.genny.lovo.ai/reference/sync-tts

---

#### Async TTS

**Method**: `POST` | **LowCodeAPI Path**: `/v1/tts`

**Full URL**:
```
https://api.lowcodeapi.com/lovo/v1/tts?api_token={api_token}
```

**Description**: Convert text to speech asynchronously for long texts. Returns a job ID to check later.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to be converted to audio |
| `speaker` | string | Yes | Speaker ID from Retrieve Speakers API |
| `speed` | number | No | Audio playback speed (0.5 - 2.0) |
| `speakerStyle` | string | No | Speaker style ID |
| `callbackUrls` | string | No | Callback URLs for job completion (max 4) |

**Example Request**:
```bash
# For long texts, use async processing
# Returns jobId to retrieve audio later
curl -X POST "https://api.lowcodeapi.com/lovo/v1/tts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is a very long text that will take more than 90 seconds to process...",
    "speaker": "SPEAKER_ID",
    "callbackUrls": "https://your-domain.com/webhook"
  }'
```

**Official Documentation**: https://docs.genny.lovo.ai/reference/async-tts

---

#### Async Retrieve Job

**Method**: `GET` | **LowCodeAPI Path**: `/v1/tts/jobid`

**Full URL**:
```
https://api.lowcodeapi.com/lovo/v1/tts/jobid?jobId={jobId}&api_token={api_token}
```

**Description**: Retrieve the result of an async TTS job.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jobId` | string | Yes | Job ID from Async TTS response |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Example Request**:
```bash
# Check job status and get audio when ready
# jobId returned from async TTS request
curl -X GET "https://api.lowcodeapi.com/lovo/v1/tts/jobid?jobId=JOB_ID&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "id": "job_123",
    "status": "finished",
    "url": "https://cdn.genny.lovo.ai/audio/xyz123.mp3"
  }
}
```

**Official Documentation**: https://docs.genny.lovo.ai/reference/async-retrieve-job

---

## Usage Examples

### Example 1: Create Voiceover for Short Content

Generate audio for short announcements or ads.

```bash
# Step 1: Get available speakers
# Returns list of voices with IDs
curl -X GET "https://api.lowcodeapi.com/lovo/v1/speakers?page=0&api_token=YOUR_API_TOKEN"

# Step 2: Generate audio using sync TTS
# Use the speaker ID from step 1
curl -X POST "https://api.lowcodeapi.com/lovo/v1/tts/sync?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Introducing our revolutionary new product that will change the way you work forever. Experience unparalleled productivity today.",
    "speaker": "SPEAKER_ID",
    "speed": 1.1,
    "speakerStyle": "commercial"
  }'
```

### Example 2: Generate Audiobook for Long Content

Process long texts with async job handling.

```bash
# Step 1: Submit async job for long text
# Returns jobId for tracking
curl -X POST "https://api.lowcodeapi.com/lovo/v1/tts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Chapter 1: The Beginning. It was a bright cold day in April, and the clocks were striking thirteen...",
    "speaker": "SPEAKER_ID",
    "callbackUrls": "https://your-server.com/tts-callback"
  }'

# Step 2: Check job status periodically
# Use the jobId returned from step 1
# Poll until status shows "finished"
curl -X GET "https://api.lowcodeapi.com/lovo/v1/tts/jobid?jobId=JOB_ID&api_token=YOUR_API_TOKEN"
```

### Example 3: Find Voices by Characteristics

Search for voices matching your needs.

```bash
# Get speakers sorted by display name
# Filter results programmatically for gender, locale, or type
curl -X GET "https://api.lowcodeapi.com/lovo/v1/speakers?page=0&limit=100&sort=displayName:1&api_token=YOUR_API_TOKEN"

# Use different voices for variety
# Test with different speakerStyle options
curl -X POST "https://api.lowcodeapi.com/lovo/v1/tts/sync?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is the same text but with a different voice style.",
    "speaker": "SPEAKER_ID",
    "speakerStyle": "narration"
  }'
```

## Speaker Selection Tips

- Use `displayName` to find voices by name
- Filter by `locale` for regional accents (en-US, en-GB, etc.)
- `speakerType` of "Neural" provides highest quality
- `speakerStyle` options vary by voice (narration, commercial, conversation, etc.)
- Adjust `speed` for pacing (1.0 = normal, <1.0 = slower, >1.0 = faster)

## Complete Endpoint Reference

For a complete list of all endpoints and their parameters, refer to:
- **OpenAPI Definition**: `https://backend.lowcodeapi.com/lovo/definition`
- **Official Provider Documentation**: https://docs.genny.lovo.ai/reference/intro/getting-started

## Rate Limits & Best Practices

- Sync TTS has a 90-second timeout
- Use Async TTS for texts longer than ~500 words
- Check job status before attempting to download audio
- Cache speaker IDs to avoid repeated API calls

## Error Handling

Standard HTTP status codes apply. Verify speaker IDs are valid and text content is properly formatted before submission.