# Text-To-Speech API Reference

{% hint style="info" %}
**Good to know:** A quick start guide can be good to help folks get up and running with your API in a few steps. Some people prefer diving in with the basics rather than meticulously reading every page of documentation!
{% endhint %}

## Get your API keys

Your `API` requests are authenticated using `API` keys. Any request that doesn't include an `API` key will return an `error`.

You can generate an `API` key from your user `dashboard` in [Miragic](https://miragic.ai/) website anytime.

<figure><img src="https://3797193121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2ubAKYPEaJXBQZaRNa5%2Fuploads%2FQRG37HdbiuNEPYckUX7g%2FScreenshot%202025-10-10%20084345.png?alt=media&#x26;token=9b926638-0508-4358-8eee-6a9913c50034" alt=""><figcaption></figcaption></figure>

## Authentication

All requests must include the `X-API-Key` header containing your assigned `API` key.&#x20;

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://backend.miragic.ai/api/v1/text-to-speech/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "text=Say verbatim: A beatiful sunset over the ocean. Where I can make good?" \
  -F "voice=alloy"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const apiKey = "YOUR_API_KEY";
const baseUrl = "https://backend.miragic.ai";

async function tts() {
  const url = `${baseUrl}/api/v1/text-to-speech/generate`;

  const formData = new FormData();
  formData.append("text", "Say verbatim: A beautiful sunset over the ocean. Where I can make good?");
  formData.append("voice", "alloy");

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      ...formData.getHeaders(),
    },
    body: formData,
  });

  const result = await response.text();
  console.log(result);
}

tts();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import time

api_key = 'YOUR_API_KEY'   # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'

def tts():
    url = f'{base_url}/api/v1/text-to-speech/generate'
    data = {
        'text': 'Say verbatim: A beautiful sunset over the ocean. Where I can make good?',
        'voice': 'alloy' # 'alloy', 'amuch', 'ash', 'ballad', 'dan', 'echo', 'onyx', 'verse', 'coral', 'elan', 'fable', 'nova', 'sage', 'shimmer'
    }
 
    headers = {'X-API-Key': api_key}
    response = requests.request("POST", url, headers=headers, data=data)
    print(response.text)

if __name__ == '__main__':
    tts()
```

{% endtab %}
{% endtabs %}

## How To Create Image Generation Task

<mark style="background-color:green;">POST</mark>   `/api/v1/text-to-speech/generate`

This `API` starts the `TTS` process by creating a task that generates an audio file containing speech.

{% hint style="info" %}
Processing Information

* Tasks are processed asynchronously in the background
* Progress can be monitored using the `Get Task Status API`
* The final result will be a high-quality audio
  {% endhint %}

### Request

<table><thead><tr><th width="117">Parameter</th><th width="81">Type</th><th width="111">Required</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Yes</td><td>Input text to generate audio.</td></tr><tr><td>voice</td><td>String</td><td>Yes</td><td>This value can be set to <code>alloy</code>, <code>amuch</code>, <code>ash</code>, <code>ballad</code>, <code>dan</code>, <code>echo</code>, <code>onyx</code>, <code>verse</code>, <code>coral</code>, <code>elan</code>, <code>fable</code>, <code>nova</code>, <code>sage</code>, <code>shimmer</code>, etc.</td></tr></tbody></table>

<mark style="color:green;">**Request Example**</mark>

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://backend.miragic.ai/api/v1/text-to-speech/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "text=Say verbatim: A beatiful sunset over the ocean. Where I can make good?" \
  -F "voice=alloy"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const apiKey = "YOUR_API_KEY";
const baseUrl = "https://backend.miragic.ai";

async function tts() {
  const url = `${baseUrl}/api/v1/text-to-speech/generate`;

  const formData = new FormData();
  formData.append("text", "Say verbatim: A beautiful sunset over the ocean. Where I can make good?");
  formData.append("voice", "alloy");

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      ...formData.getHeaders(),
    },
    body: formData,
  });

  const result = await response.text();
  console.log(result);
}

tts();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import time

api_key = 'YOUR_API_KEY'   # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'

def tts():
    url = f'{base_url}/api/v1/text-to-speech/generate'
    data = {
        'text': 'Say verbatim: A beautiful sunset over the ocean. Where I can make good?',
        'voice': 'alloy' # 'alloy', 'amuch', 'ash', 'ballad', 'dan', 'echo', 'onyx', 'verse', 'coral', 'elan', 'fable', 'nova', 'sage', 'shimmer'
    }
 
    headers = {'X-API-Key': api_key}
    response = requests.request("POST", url, headers=headers, data=data)
    print(response.text)

if __name__ == '__main__':
    tts()
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">**Response**</mark>

```bash
{"success":true,"data":{"jobId":"eddb46cf-ca93-4513-a45d-747a9702c446","status":"PENDING"},"message":"Text-to-speech job created successfully"}
Job ID: eddb46cf-ca93-4513-a45d-747a9702c446
```

**Response Field**

<table><thead><tr><th width="102">Field</th><th width="88">Type</th><th>Description</th></tr></thead><tbody><tr><td>jobId</td><td>String</td><td>A unique identifier used to track task status and retrieve results.</td></tr><tr><td>status</td><td>String</td><td>The initial status will be <code>PENDING</code>. Use the <code>Get Task Status API</code> to track progress.</td></tr><tr><td>success</td><td>Logic</td><td><code>true</code> or <code>false</code> to indicate whether task is successful or not.</td></tr><tr><td>message</td><td>String</td><td>To indicate the status of task</td></tr></tbody></table>

## How To Get Task Status

<mark style="background-color:green;">GET</mark>   `/api/v1/text-to-speech/jobs/:jobId`

This `API` lets you check the status of a `TTS` task and retrieve the final result. Because the `TTS` process runs asynchronously, you’ll need to poll this endpoint until the task is finished.

### Task Status:

<table><thead><tr><th width="103">Status</th><th>Description</th><th width="107">Progress</th><th>Next Action</th></tr></thead><tbody><tr><td><code>PENDING</code></td><td>Task is currently being processed.</td><td><code>0</code>~<code>99</code>%</td><td>Continue polling</td></tr><tr><td><code>COMPLETED</code></td><td>Task has finished successfully.</td><td><code>100</code>%</td><td>Download result using download_signed_url</td></tr><tr><td><code>FAILED</code></td><td>Task processing failed.</td><td>N/A</td><td>Check error details and retry if needed</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:green;">**Progress Tracking:**</mark>

* The `progress` field indicates the percentage of task completion (`0`-`100`)
* Progress updates are available in real-time during the `PENDING` state
* Progress increases as the AI processes different stages of the try-on task
  {% endhint %}

{% hint style="info" %}
**Polling Guidelines:**

* Start polling immediately after creating the task
* Implement exponential backoff to avoid rate limiting
* The download\_signed\_url is temporary and should be used promptly
* Consider implementing a timeout after extended polling
  {% endhint %}

### Request:

<mark style="color:blue;">**URL Parameters**</mark>

<table><thead><tr><th width="117">Parameter</th><th width="83">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>JobId</td><td>String</td><td>Yes</td><td>This value indicates task <code>ID</code> assigned by requesting <code>TTS</code> process <code>API</code></td></tr></tbody></table>

<mark style="color:blue;">**Request Example**</mark>

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET https://backend.miragic.ai/api/v1/text-to-speech/jobs/25331fb2-d0b0-44f6fcc85e3e \
  -H "X-API-Key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const fetch = require("node-fetch"); // for Node.js

const apiKey = "YOUR_API_KEY";
const jobId = "25331fb2-d0b0-44f6fcc85e3e";
const url = `https://backend.miragic.ai/api/v1/text-to-speech/jobs/${jobId}`;

const options = {
  method: "GET",
  headers: {
    "X-API-Key": apiKey
  }
};

fetch(url, options)
  .then(response => response.json())
  .then(data => {
    console.log("Response:", data);
  })
  .catch(error => {
    console.error("Error:", error);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

api_key = "YOUR_API_KEY"
job_id = "25331fb2-d0b0-44f6fcc85e3e"
url = f"https://backend.miragic.ai/api/v1/text-to-speech/jobs/{job_id}"

headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers)

# Print status code and response JSON
print("Status Code:", response.status_code)
print("Response:", response.json())
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">**Response Example**</mark>

#### Completed Status (200):

```bash
{'success': True, 'data': {'id': 'eddb46cf-ca93-4513-a45d-747a9702c446', 'userId': 'eebf31b5-7bec-445e-8b99-51c0311a389d', 'text': 'Say verbatim: A beautiful sunset over the ocean. Where I can make good?', 'voice': 'alloy', 'audioUrl': 'https://backend.miragic.ai/uploads/textToSpeech/processed/eebf31b5-7bec-445e-8b99-51c0311a389d/7caf97b8-f60f-41f5-9b23-5bccdfca67e2.mp3', 'status': 'COMPLETED', 'errorMessage': None, 'metadata': {'apiResponse': {'success': True, 'audio_link': 'https://www.dropbox.com/scl/fi/pyrh623yt9etrjjeqb9m6/bcfd45b6-17e4-4d78-adeb-1eecddaae0c0.mp3?rlkey=soni37e2h7e1gjip74bfodmjw&raw=1'}, 'localAudioPath': 'uploads/textToSpeech/processed/eebf31b5-7bec-445e-8b99-51c0311a389d/7caf97b8-f60f-41f5-9b23-5bccdfca67e2.mp3', 'processingTimeMs': 7082}, 'creditsUsed': 2, 'createdAt': '2025-11-04T14:58:15.547Z', 'updatedAt': '2025-11-04T14:58:22.630Z'}}
```

<mark style="color:blue;">**Response Fields**</mark>

<table><thead><tr><th width="105">Field</th><th width="89">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>Unique identifier of the task</td></tr><tr><td>status</td><td>String</td><td>Current status of the task (<code>PENDING</code>/<code>COMPLETED</code>/<code>FAILED</code>)</td></tr><tr><td>audio_link</td><td>String</td><td><code>URL</code> to result audio file.</td></tr><tr><td>createdAt</td><td>Number</td><td>Unix timestamp when processing is created</td></tr></tbody></table>

## Full Code Example

The following code lines are quick example to use our `API` in multiple languages.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://backend.miragic.ai/api/v1/text-to-speech/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "text=Say verbatim: A beatiful sunset over the ocean. Where I can make good?" \
  -F "voice=alloy"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import axios from "axios";
import fs from "fs";
import FormData from "form-data";

const apiKey = "YOUR_API_KEY";
const baseUrl = "https://devapi.miragic.ai";

async function tts() {
  const url = `${baseUrl}/api/v1/text-to-speech/generate`;

  const formData = new FormData();
  formData.append("text", "Say verbatim: A beautiful sunset over the ocean. Where I can make good?");
  formData.append("voice", "alloy");
  
  const headers = {
    "X-API-Key": apiKey,
    ...form.getHeaders(),
  };

  try {
    // Step 1: Create job
    const response = await axios.post(url, form, { headers });
    console.log(response.data);

    if (response.data.success) {
      const jobId = response.data.data.jobId;
      console.log(`Job ID: ${jobId}`);

      // Step 2: Poll for results
      let status = "PENDING";
      while (status !== "COMPLETED" && status !== "FAILED") {
        await new Promise((r) => setTimeout(r, 2000)); // wait 2 sec
        const result = await axios.get(`${baseUrl}/api/v1/text-to-speech/jobs/${jobId}`, {
          headers: { "X-API-Key": apiKey },
        });

        status = result.data.data.status;

        if (status === "COMPLETED") {
          console.log("Result:", result.data);
          break;
        } else if (status === "FAILED") {
          console.log("Job failed:", result.data);
          break;
        } else {
          console.log(`Current status: ${status}...`);
        }
      }
    } else {
      console.log("Error:", response.data);
    }
  } catch (error) {
    console.error("Request failed:", error.response?.data || error.message);
  }
}

tts();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import time

api_key = 'YOUR_API_KEY'   # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'

def tts():
    url = f'{base_url}/api/v1/text-to-speech/generate'
    data = {
        'text': 'Say verbatim: A beautiful sunset over the ocean. Where I can make good?',
        'voice': 'alloy' # 'alloy', 'amuch', 'ash', 'ballad', 'dan', 'echo', 'onyx', 'verse', 'coral', 'elan', 'fable', 'nova', 'sage', 'shimmer'
    }

    headers = {'X-API-Key': api_key}
    response = requests.request("POST", url, headers=headers, data=data)
    print(response.text)
    
    if response.json()['success']:
        job_id = response.json()['data']['jobId']
        print(f'Job ID: {job_id}')
        
        # Poll for results
        while True:
            result = requests.get(
                f'{base_url}/api/v1/text-to-speech/jobs/{job_id}',
                headers=headers
            )
            
            if result.json()['data']['status'] == 'COMPLETED':
                print('Result:', result.json())
                break
            elif result.json()['data']['status'] == 'FAILED':
                print('Job failed:', result.json())
                break
            
            time.sleep(2)
    else:
        print('Error:', response.json())

if __name__ == '__main__':
    tts()
```

{% endtab %}
{% endtabs %}