# IndexTTS2-API

**Repository Path**: chuangyeba/index-tts2-api

## Basic Information

- **Project Name**: IndexTTS2-API
- **Description**: IndexTTS2-API 语音合成对接仓库，收录完整接口调用文档与多语言配套SDK。项目兼容同步实时语音生成、异步长文本批量合成两种调用模式，覆盖短句即时配音。文档包含接口参数说明、鉴权流程、错误码对照表、示例请求代码，SDK封装底层请求逻辑，简化音频获取、进度查询、结果下载操作。适配业务平台、配音工具、AI助手等各类语音场景开发，开箱即用，快速接入IndexTTS2高质量语音合成能力。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IndexTTS-2 SDK

IndexTTS-2 语音合成服务 SDK，支持 Python 和 PHP。

同步接口和异步接口分别封装为独立客户端，可按需使用。

- 在线调试地址：https://yuntts.apifox.cn/
- 在线体验地址：https://www.yuntts.com/index-tts2

## 项目结构

```
IndexTTS/
├── python/                          # Python SDK
│   ├── indextts/
│   │   ├── __init__.py
│   │   ├── sync_client.py           # 同步语音合成客户端
│   │   └── async_client.py          # 异步语音合成客户端
│   └── examples/
│       ├── sync_example.py          # 同步接口使用示例
│       └── async_example.py         # 异步接口使用示例
├── php/                             # PHP SDK
│   ├── autoload.php                 # 自动加载
│   ├── src/
│   │   ├── SyncClient.php           # 同步语音合成客户端
│   │   └── AsyncClient.php          # 异步语音合成客户端
│   └── examples/
│       ├── sync_example.php         # 同步接口使用示例
│       └── async_example.php        # 异步接口使用示例
└── README.md
```

## 功能特性

- 同步语音合成（支持流式/非流式）
- 异步语音合成（任务队列 + 轮询）
- 四种情感控制模式
  - 基础音色（无情感控制）
  - 音频情感控制
  - 文本情感控制
  - 向量情感控制（8维）
- 任务状态查询与自动等待
- HTTP 错误状态码处理

## 安装

### Python

```bash
pip install requests
```

将 `python/indextts/` 目录复制到你的项目中。

### PHP

确保安装了 cURL 扩展，引入 `php/autoload.php` 即可使用。

```php
require_once 'path/to/php/autoload.php';
```

## 快速开始

### Python - 同步合成

```python
from indextts import IndexTTSSyncClient

client = IndexTTSSyncClient(api_key="your-api-key")

# 非流式（返回JSON，含audio_url）
result = client.synthesize(
    input_text="你好，欢迎使用IndexTTS语音合成",
    prompt_audio_url="https://example.com/voice-sample.wav",
    stream_mode=False,
)
print(result)

# 流式（返回音频二进制数据，推荐）
result = client.synthesize(
    input_text="你好，欢迎使用IndexTTS语音合成",
    prompt_audio_url="https://example.com/voice-sample.wav",
    stream_mode=True,
)
with open("output.wav", "wb") as f:
    f.write(result["audio_data"])
print(f"字符数: {result['char_count']}，费用: {result['cost']}元")

# 便捷方法：合成并保存
result = client.save_audio(
    file_path="output.wav",
    input_text="你好",
    prompt_audio_url="https://example.com/voice.wav",
)
```

### Python - 异步合成

```python
from indextts import IndexTTSAsyncClient

client = IndexTTSAsyncClient(api_key="your-api-key")

# 提交任务
result = client.submit(
    input_text="你好，欢迎使用IndexTTS语音合成",
    prompt_audio_url="https://example.com/voice-sample.wav",
)
task_id = result["data"]["task_id"]

# 查询状态
status = client.query(task_id)
print(status)

# 等待完成（带进度回调）
final = client.wait(task_id, max_wait=120, callback=lambda r: print(r["data"]["status"]))

# 便捷方法：提交并等待
result = client.submit_and_wait(
    input_text="你好",
    prompt_audio_url="https://example.com/voice.wav",
    max_wait=120,
)
```

### PHP - 同步合成

```php
require_once 'path/to/php/autoload.php';

$client = new IndexTTSSyncClient('your-api-key');

// 非流式
$result = $client->synthesize([
    'input_text' => '你好，欢迎使用IndexTTS语音合成',
    'prompt_audio_url' => 'https://example.com/voice-sample.wav',
    'stream_mode' => false,
]);
print_r($result);

// 流式（推荐）
$result = $client->synthesize([
    'input_text' => '你好，欢迎使用IndexTTS语音合成',
    'prompt_audio_url' => 'https://example.com/voice-sample.wav',
    'stream_mode' => true,
]);
file_put_contents('output.wav', $result['audio_data']);

// 便捷方法：合成并保存
$result = $client->saveAudio('output.wav', [
    'input_text' => '你好',
    'prompt_audio_url' => 'https://example.com/voice.wav',
]);
```

### PHP - 异步合成

```php
require_once 'path/to/php/autoload.php';

$client = new IndexTTSAsyncClient('your-api-key');

// 提交任务
$result = $client->submit([
    'input_text' => '你好，欢迎使用IndexTTS语音合成',
    'prompt_audio_url' => 'https://example.com/voice-sample.wav',
]);
$taskId = $result['data']['task_id'];

// 查询状态
$status = $client->query($taskId);
print_r($status);

// 等待完成
$final = $client->wait($taskId, 120, 2, function ($result) {
    echo "状态: " . $result['data']['status'] . "\n";
});

// 便捷方法：提交并等待
$result = $client->submitAndWait([
    'input_text' => '你好',
    'prompt_audio_url' => 'https://example.com/voice.wav',
], 120);
```

## API 参考

### 同步客户端

| 方法 | 说明 |
|------|------|
| `synthesize(params)` | 语音合成，`stream_mode=True` 返回音频数据，`False` 返回JSON |
| `synthesize_stream(params)` | (Python) 流式合成，返回可迭代的 Response 对象 |
| `save_audio(path, params)` | 合成并保存到文件 |

### 异步客户端

| 方法 | 说明 |
|------|------|
| `submit(params)` | 提交异步合成任务，返回 `task_id` |
| `query(task_id)` | 查询任务状态 |
| `wait(task_id, max_wait, poll_interval, callback)` | 轮询等待任务完成 |
| `submit_and_wait(params, max_wait, ...)` | 提交并等待完成（便捷方法） |

### 通用参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `input_text` | 是 | 要合成的文本 |
| `prompt_audio_url` | 是 | 说话人音色参考音频URL |
| `prompt_text` | 否 | 参考音频的文字内容（用于语义对齐） |
| `stream_mode` | 否 | 是否流式输出（仅同步接口，默认True） |
| `failover_enabled` / `failover` | 否 | 是否启用故障转移 |
| `emo_audio_prompt_url` | 否 | 情感参考音频URL（音频模式，优先级最高） |
| `emo_alpha` | 否 | 情感影响强度（0.0~1.0，默认0.5） |
| `use_emo_text` | 否 | 启用文本情感控制 |
| `emo_text` | 否 | 情感文本（文本模式） |
| `emo_vector` | 否 | 8维情感向量（向量模式） |

### 情感向量说明

向量顺序: `[happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]`

每个维度取值 0.0~1.0，步长 0.1。

```python
# 示例：开心 + 惊讶
emo_vector=[0.8, 0.0, 0.0, 0.0, 0.0, 0.0, 0.5, 0.0]
```

## 响应格式

### 同步合成（非流式）

```json
{
    "code": 200,
    "message": "语音合成成功",
    "data": {
        "task_id": "tts_sync_67f8a9b0c1d2e",
        "status": "completed",
        "char_count": 26,
        "cost": 0.01,
        "mode": "none",
        "audio_url": "https://www.yuntts.com/.../speech-xxx.wav",
        "message": "语音合成成功"
    }
}
```

### 同步合成（流式）

响应头包含 `X-Characters`（字符数）和 `X-Cost`（费用），响应体为音频二进制数据。

### 异步提交

```json
{
    "code": 200,
    "message": "任务提交成功",
    "data": {
        "task_id": "b3f7a2e1-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
        "char_count": 26,
        "cost": 0.01,
        "mode": "none",
        "status": "pending"
    }
}
```

### 任务状态

| status | 说明 | progress |
|--------|------|----------|
| `pending` | 排队中 | 0% |
| `processing` | 处理中 | 50% |
| `completed` | 完成 | 100% |
| `failed` | 失败 | 0% |
| `cancelled` | 已取消 | 0% |

## 错误码

| 错误码 | 说明 |
|--------|------|
| 400 | 参数错误 |
| 401 | 认证失败 |
| 402 | 余额不足 |
| 405 | 请求方法不允许 |
| 408 | 等待超时（SDK自定义） |
| 429 | 任务数量达到上限 |
| 500 | 服务器错误 |

## 参考音频要求

| 项目 | 要求 |
|------|------|
| 格式 | WAV、MP3 |
| 大小 | 最大 20MB |
| 时长 | 5秒 ~ 30秒 |
| 采样率 | 不低于 16kHz |

## 许可证

MIT License