--ref-text "Original transcript of the reference audio"
```
### 3. Using curl
```bash
# Simple TTS request
curl -X POST http://localhost:8000/v1/audio/speech \
-H "Content-Type: application/json"\
-d '{
"input": "Hello, how are you?",
"voice": "Vivian",
"language": "English"
}' --output output.wav
# With style instruction
curl -X POST http://localhost:8000/v1/audio/speech \
-H "Content-Type: application/json"\
-d '{
"input": "I am so excited!",
"voice": "Vivian",
"instructions": "Speak with great enthusiasm"
}' --output excited.wav
```
## API Reference
### Endpoint
```
POST /v1/audio/speech
```
This endpoint follows the [OpenAI Audio Speech API](https://platform.openai.com/docs/api-reference/audio/createSpeech) format with additional Qwen3-TTS parameters.
### Request Body
```json
{
"input":"Text to synthesize",
"voice":"Vivian",
"response_format":"wav",
"task_type":"CustomVoice",
"language":"Auto",
"instructions":"Optional style instructions",
"ref_audio":"URL or base64 for voice cloning",
"ref_text":"Reference audio transcript",
"x_vector_only_mode":false,
"max_new_tokens":2048
}
```
> **Note:** The `model` field is optional when serving a single model, as the server already knows which model is loaded.
### Response
Returns audio data in the requested format (default: WAV).
## Parameters
### Standard OpenAI Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `input` | string | required | Text to synthesize |
| `voice` | string | "Vivian" | Speaker/voice name |
| `ref_text` | string | No | Transcript of reference audio (for ICL mode) |
| `x_vector_only_mode` | bool | false | Use speaker embedding only (no ICL) |
## Python Usage
```python
importhttpx
# Simple request
response=httpx.post(
"http://localhost:8000/v1/audio/speech",
json={
"model":"Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
"input":"Hello world",
"voice":"Vivian",
},
timeout=300.0,
)
withopen("output.wav","wb")asf:
f.write(response.content)
```
## Limitations
- **No streaming**: Audio is generated completely before being returned. Streaming will be supported after the pipeline is disaggregated (see RFC #938).
- **Single request**: Batch processing is not yet optimized for online serving.
## Troubleshooting
1.**Connection refused**: Make sure the server is running on the correct port
2.**Out of memory**: Reduce `--gpu-memory-utilization` in run_server.sh
3.**Unsupported speaker**: Check supported speakers via model documentation
4.**Voice clone fails**: Ensure you're using the Base model variant for voice cloning