Name: Text-to-Speech API - Clone & Design Voices (Qwen3-TTS)
Brand: magicapi
SKU: api-magicapi-text-to-speech-api-voice-clone-design-qwen-qwen3-tts
Availability: InStock
Author: API Market

Shashank Agarwal

# 📢 Text-to-Speech API - Voice Clone & Design (Qwen3-TTS)

## Overview
The Text-to-Speech API, powered by the Qwen3-TTS model, enables the creation, cloning, and designing of voices with high accuracy and quality. It offers three modes, set with `mode`: `custom_voice` (preset speakers), `voice_clone` (clone a voice from reference audio) and `voice_design` (create a voice from a text description).

## Features
- **Custom Voice Mode:** Generate speech using a variety of preset speaker voices.
- **Voice Cloning Mode:** Clone voices from reference audio.
- **Voice Design Mode:** Create unique voices from descriptive text.
- **High-Quality Audio:** Deliver natural and lifelike speech synthesis.
- **Multilingual Support:** 10 languages (Chinese, English, Japanese, Korean, French, German, Italian, Spanish, Portuguese, Russian), or `auto` to detect the language.

## Use Cases
- **E-learning Industry:** Enhance educational content with natural-sounding voiceovers, catering to different regional accents and languages.
- **Entertainment Industry:** Produce high-quality voiceovers for animations, games, and media productions with custom voice creation.
- **Customer Service:** Develop sophisticated IVR systems with personalized and natural responses using voice cloning.
- **Accessibility:** Create audio versions of text content for visually impaired users in various languages and styles.
- **Marketing and Advertising:** Design unique voice characters for advertisements and brand promotions.

## Visual Examples

### Example Input

```json
{
  "input": {
    "mode": "custom_voice",
    "text": "Hello, I'm Aiden and it's very nice to meet you. Welcome to api.market.",
    "speaker": "Aiden",
    "language": "auto"
  }
}
```

### Example Output

![Example output from Text-to-Speech API - Voice Clone & Design (Qwen3-TTS)](https://blog.api.market/wp-content/uploads/2026/09/qwen3-tts-output-api-market.wav)

This exact request was run through api.market and billed 1 API unit ($0.0025).
## Pricing
- **Pay As You Go (PAYG)** pricing - you only pay for what you use
- **Price:** $0.0025 per API unit.
- **1 API unit** = each started 100 characters of input text.
- Any request of up to 100 characters of `text` bills 1 unit; 101 to 200 characters bills 2 units.
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status are free and do not count toward API unit usage.
- **No monthly subscription fee**.

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```plaintext
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API uses asynchronous processing for predictions. The typical flow is:
1. Submit a prediction request to the POST endpoint.
2. Receive a prediction ID in the response.
3. Poll the GET endpoint with the prediction ID to check status.
4. Continue polling until the prediction is complete.

The processing time varies depending on the complexity of the request. Your code should implement:
- A polling interval of 1 second between status checks.
- A maximum timeout of 600 seconds (10 minutes).
- Status checking logic that continues while status is "starting" or "processing".
- Result handling when status becomes "succeeded".
- Error handling when status becomes "failed" or timeout is reached.

### Endpoints
#### Create Prediction
Create a new speech synthesis prediction.

**Input parameters** (sent inside `input`):

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `text` | string | Yes | none | Text to synthesize into speech. |
| `mode` | string | No | `custom_voice` | `custom_voice` (preset speakers), `voice_clone` (clone a voice from `reference_audio`) or `voice_design` (create a voice from `voice_description`). |
| `language` | string | No | `auto` | `auto`, `Chinese`, `English`, `Japanese`, `Korean`, `French`, `German`, `Italian`, `Spanish`, `Portuguese` or `Russian`. |
| `speaker` | string | No | `Serena` | Preset voice, used only in `custom_voice` mode: `Aiden`, `Dylan`, `Eric`, `Ono_anna`, `Ryan`, `Serena`, `Sohee`, `Uncle_fu` or `Vivian`. |
| `voice_description` | string | No | null | Natural language description of the voice, used only in `voice_design` mode. Example: "A warm, friendly female voice with a slight British accent". |
| `reference_audio` | string (URI) | No | null | Audio file of the voice to clone, used only in `voice_clone` mode. |
| `reference_text` | string | No | null | Transcript of the reference audio, recommended for `voice_clone` mode. |
| `style_instruction` | string | No | null | Optional style or emotion instruction, for example "speak slowly and calmly". |

**Request:** `POST /api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts/predictions`
```bash
# Example for creating a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d490a561cf1171a8dc3d96d1e57efffea7dd34607148bb641f3d9de4e38c472e",
    "input": {
      "mode": "custom_voice",
      "text": "Hello, I'm Aiden and it's very nice to meet you. Welcome to api.market.. Welcome to api.market.",
      "speaker": "Aiden",
      "language": "auto"
    }
  }'
```

**Response Example:**
```json
{
  "id": "abcd1234",
  "status": "starting"
}
```

#### Check Prediction Status
Get the status of an existing prediction.

**Request:** `GET /api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts/predictions/{id}`
```bash
# Example for checking prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example:**
```json
{
  "id": "abcd1234",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/09/qwen3-tts-output-api-market.wav"
}
```

### Status Codes
- **200 OK:** Request successful.
- **201 Created:** Resource successfully created.
- **400 Bad Request:** Invalid input parameters or malformed request.
- **401 Unauthorized:** Missing or invalid API key.
- **403 Forbidden:** Valid API key but insufficient permissions.
- **404 Not Found:** Resource not found.
- **429 Too Many Requests:** Rate limit exceeded.
- **500 Internal Server Error:** Server-side error.
- **503 Service Unavailable:** Service temporarily unavailable.

### Rate Limits
There are no specific rate limits documented for this API. However, it's recommended to handle potential rate limit responses gracefully in your application by implementing backoff mechanisms and retry strategies.

### Error Handling
A 400 response means an input is missing or invalid (`text` is the only required input). Retry 429 and 5xx responses with exponential backoff. A prediction that ends with status `failed` carries an `error` field and is not billed.

**Example Error Response:**
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'text' is required",
    "status": 400
  }
}
```

## Implementation Guide
### Example Code
**JavaScript:**
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify({ version: "d490a561cf1171a8dc3d96d1e57efffea7dd34607148bb641f3d9de4e38c472e", input: inputData })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    // Check prediction status
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    // Handle failure
    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

**Python:**
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "d490a561cf1171a8dc3d96d1e57efffea7dd34607148bb641f3d9de4e38c472e", "input": input_data}
    )
    
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks
    
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()
    
    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers=headers
        )
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()
        
        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        # Handle failure
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")
        
        # Wait before next poll
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

**cURL:**
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d490a561cf1171a8dc3d96d1e57efffea7dd34607148bb641f3d9de4e38c472e",
    "input": {
      "text": "Hello, I'm Aiden and it's very nice to meet you. Welcome to api.market.. Welcome to api.market.",
      "speaker": "Aiden"
    }
  }'

# Response will contain a prediction ID like:
# {"id": "abcd1234", "status": "starting"}

# Step 2: Check prediction status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-speech-api-voice-clone-design-qwen-qwen3-tts/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Note: You need to repeatedly poll this endpoint manually until status is "succeeded"
```

### Performance Optimization
- **Combine Short Texts:** Each request bills at least 1 unit, so joining short snippets into one request costs less than sending them separately. Each request returns one audio file.
- **Cache Responses:** Cache the results of frequently requested text phrases to minimize redundant API calls.
- **Rate Limiting:** Implement an exponential backoff strategy to handle rate limiting.

## FAQ
1. **What are the system requirements for using this API?**
   The API can be accessed via HTTP requests from any system that supports HTTP/HTTPS communication.

2. **How soon can I expect the synthesized speech after sending a request?**
   The response time depends on the complexity of the request. Usually, it ranges from a few seconds to a couple of minutes.

3. **Is there a limit on the number of characters I can send in one request?**
   The model schema does not state a maximum length. Billing is 1 API unit per started 100 characters of `text`, so longer texts bill more units.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

__________________________________________________________________________________________



Text-to-speech API powered by Qwen3-TTS: 9 preset voices, voice cloning from reference audio and voice design from a text description, in 10 languages.