# IndexTeam/IndexTTS-2 Documentation

This document describes the input/output parameters for calling the `IndexTeam/IndexTTS-2` speech synthesis model API on the UModelverse platform, for reference when using the interface.

## API Endpoint

`https://api-us-ca.umodelverse.ai/v1/audio/infer` <br/> Note: The request body format for this endpoint must be `multipart/form-data` (form mode).

## Request Parameters: Form File Parameters (Form Data)

| Parameter      | Type          | Required | Description |
| -------------- | ------------- | -------- | ----------- |
| model          | string        | Yes      | The TTS model name to use. Here: `IndexTeam/IndexTTS-2` |
| spk_audio_file | File (binary) | Yes      | Speaker reference audio file for voice timbre extraction. Only MP3 and WAV supported. File must be under 20 MB. |
| emo_audio_file | File (binary) | No       | Emotion reference audio file for emotional feature extraction. Only MP3 and WAV supported. File must be under 20 MB. |
| payload        | string        | Yes      | JSON-formatted configuration parameter string |

#### payload Configuration Parameters (JSON Format)

| Parameter          | Type         | Required | Default                    | Description |
| ------------------ | ------------ | -------- | -------------------------- | ----------- |
| input              | string       | Yes      | -                          | Text content to synthesize. Maximum `600` characters. |
| sample_rate        | int          | No       | `22050`                    | Output audio sample rate in Hz. Common values: `22050`, `44100`, `48000`. |
| speed              | float        | No       | `1`                        | Speech speed factor. Range: `0.25 <= value <= 4.0`. |
| gain               | float        | No       | `1`                        | Volume factor. `1` = original volume; `>1` louder; `<1` quieter. |
| emo_control_method | int          | No       | `0`                        | Emotion control mode: `0` = none; `1` = audio reference (requires `emo_audio_file`); `2` = vector reference; `3` = text reference. |
| emo_alpha          | float        | No       | `1`                        | Emotion blending weight, controlling the influence of emotional features on the output. |
| emo_vec            | array[float] | No       | `[0,0,0,0,0,0,0,0]`       | 8-dimensional emotion vector. Only effective when `emo_control_method = 2`. Sum of all elements must not exceed `1.5`. Example: `[0.1, 0.2, 0.0, 0.3, 0.1, 0.0, 0.2, 0.4]`. |
| emo_text           | string       | No       | `""`                       | Emotion text description. Only effective when `emo_control_method = 3`. |
| use_random         | bool         | No       | `false`                    | Emotion randomness switch. `true` randomly introduces emotional variation; `false` synthesizes strictly to the specified emotion. |
| interval_silence   | int          | No       | `200`                      | Silence duration between text chunks during segmented synthesis, in milliseconds. |

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or other API tools.

```bash
curl https://api-us-ca.umodelverse.ai/v1/audio/infer \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "model=IndexTeam/IndexTTS-2" \
  -F "spk_audio_file=@/path/to/speaker.wav" \
  -F "emo_audio_file=@/path/to/emotion.wav" \
  -F 'payload={"input":"Text to synthesize.","emo_weight":0.8,"emo_control_method":1}' \
  --output output.wav
```

## Response Format

The API returns a binary audio file stream.

- **Audio Format**: Currently only **WAV** format output is supported
- **Content-Type**: `audio/wav`

## Error Response

When a request fails, the API returns a standard JSON error response:

```json
{
  "code": 400,
  "message": "Error description",
  "request_id": "",
  "param": "<Request ID for feedback or troubleshooting>"
}
```

## Also Compatible with the Following Endpoint

API Endpoint: `https://api-us-ca.umodelverse.ai/v1/audio/speech`

---

# OpenAI TTS API Documentation

The UModelverse platform offers a fully compatible speech synthesis interface with the OpenAI TTS (Text-to-Speech) API. Developers can seamlessly invoke high-quality TTS models deployed on Modelverse using familiar OpenAI SDKs or standard HTTP clients.

> **🎉 Limited Time Free**: The TTS voice synthesis service is now open for free for a limited time. Welcome to experience!

## Quick Start

You can call the Modelverse TTS API using the `curl` command or any client library that supports the OpenAI API. The platform supports a variety of high-quality speech synthesis models, such as `IndexTeam/IndexTTS-2`.

## Request Parameters

| Parameter | Type   | Required | Description                                                                                                                       |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| model     | string | Yes      | The TTS model name to use, e.g., `IndexTeam/IndexTTS-2`                                                                           |
| input     | string | Yes      | The text content to be converted to speech (supports up to 600 characters)                                                        |
| voice     | string | Yes      | The voice to use, optional values include: built-in voices (`jack_cheng`, `sales_voice`, `crystla_liu`, `stephen_chow`, `xiaoyueyue`, `mkas`, `entertain`, `novel`, `movie`), or you can provide a custom voice ID (like `uspeech:xxxx`, see below for "Using Custom Voices") |

## Call Example

The following example demonstrates using the `IndexTeam/IndexTTS-2` model for speech synthesis. Make sure to replace `$MODELVERSE_API_KEY` with your own API Key.

 <!-- tabs:start -->

#### ** curl **
```bash
curl https://api-us-ca.umodelverse.ai/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -d '{
    "model": "IndexTeam/IndexTTS-2",
    "input": "Hello! Welcome to Modelverse voice synthesis service.",
    "voice": "jack_cheng"
  }' \
  --output speech.wav
```
    
#### ** python **
```python
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("MODELVERSE_API_KEY", "<YOUR_MODELVERSE_API_KEY>"),
    base_url="https://api-us-ca.umodelverse.ai/v1/",
)

speech_file_path = Path(__file__).parent / "generated-speech.wav"

with client.audio.speech.with_streaming_response.create(
    model="IndexTeam/IndexTTS-2",
    voice="jack_cheng",
    input="Hello! Welcome to Modelverse voice synthesis service.",
) as response:
    response.stream_to_file(speech_file_path)

print(f"Audio saved to {speech_file_path}")
```

<!-- tabs:end -->

## Using Custom Voices (Optional)

In addition to using built-in `voice` names, you can upload your own voice timbre (even sample voices with specific emotions) to generate an exclusive `voice_id`, which can then be referenced in TTS requests through the `voice` field.

> Note: Current custom voice resources will be automatically cleaned up **7 days** after upload. If you need to use them for a long time, please remember to back up or re-upload in advance. (You can contact the sales team for long-term storage requirements.)

The use method can be simply understood as **three steps**:

1. **Upload voice, get `voice_id`**  
   Call `POST /v1/audio/voice/upload` to upload a sample voice meeting the requirements. The interface will return an `id` as the custom voice ID.  
   For detailed request parameters and return structures, please refer to the "[Custom Voice Management API Documentation](/docs/modelverse/modelverse/audio_api/custom_voice_api)".
2. **Use `voice_id` in TTS requests**  
   In the `/v1/audio/speech` request, set the `voice` field to the `id` returned in step one. A complete example will be given below.
3. **Manage existing custom voices (optional)**  
   To view or delete existing voices, call `GET /v1/audio/voice/list` and `POST /v1/audio/voice/delete`.  
   The specific request/return format is also in the "[Custom Voice Management API Documentation](/docs/modelverse/modelverse/audio_api/custom_voice_api)".

> Tip: Custom voices are fully compatible with the OpenAI protocol and reuse the `voice` field. No need to learn new parameter names.

### Using Custom voice_id in TTS Requests

Once you have a custom voice `id` (e.g., `uspeech:xxxx`), you only need to change the `voice` field to that `id` in the `/v1/audio/speech` request.

```bash
VOICE_ID="uspeech:xxxx-xxxx-xxxx-xxxx"

curl https://api-us-ca.umodelverse.ai/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -d "{
    \"model\": \"IndexTeam/IndexTTS-2\",\
    \"input\": \"Hello, I am the gentle custom female voice.\",\
    \"voice\": \"$VOICE_ID\"\
  }" \
  --output speech-custom.wav
```

Behavior Description:

- `voice` empty: Use default voice or model's built-in default configuration.
- `voice` is a built-in name (like `jack_cheng`, etc.): Use the platform's built-in preset voice.
- `voice` has a value like `uspeech:xxxx`: Means using your uploaded custom voice. The platform will find and apply the corresponding voice/emotion material according to that ID, no extra configuration needed.

  ## Response Format

API returns a binary audio file stream.

- **Audio Format**: Currently only supports **WAV** format output
- **Content-Type**: `audio/wav`

## Notes

1. **Limited Time Free**: The current TTS service is open for free for a limited time. The official charging standard will be notified separately later.
2. **Audio Format**: The format of the binary stream response currently only supports WAV. Other audio formats are not supported yet.
3. **Text Length Limit**: The text length limit for a single request varies depending on the specific model. The `IndexTeam/IndexTTS-2` model usually supports text within 600 characters.
4. **Voice Type**: Different `voice` parameters will produce voices with different timbres and styles. It is recommended to choose the appropriate voice type according to the actual scenario.

## Error Handling

When a request fails, the API returns a standard JSON format error response:

```json
{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "<Request ID, for feedback or troubleshooting the cause of the error>"
  }
}
```

### Frequently Asked Questions (FAQ)

- **Q: What are the requirements for the audio I upload?**  
  A: It must be in MP3/WAV, a single file ≤ 20MB, duration 5–30 seconds, sampling rate at least 16kHz. If it does not meet the requirements, a 4xx error will be returned, and the reason will be specified in `error.code`.

- **Q: What should be filled in the `voice` field?**  
  A:
  - If you want to directly use the fixed voices provided by the platform, fill in the built-in names (e.g., `jack_cheng`);
  - If you want to use your recorded voice, first call the upload interface to get the `id`, and then set `voice` to this `id` in the TTS request (e.g., `uspeech:xxxx`).

- **Q: What should I do if an `invalid_voice_id` / `voice_not_found` error occurs?**  
  A: This means that this `voice_id` cannot be found under the current account, or it has been deleted. You can first call `/v1/audio/voice/list` to confirm the available IDs and then use the correct value in your request.

- **Q: Can custom voices be shared between different accounts?**  
  A: Custom voices can be shared among all sub-accounts under the same organization. They cannot be shared under different accounts.