Voice Cloned TTS (REST)

Voice Cloned TTS Inference

curl --request POST \
  --url https://api.vachana.ai/api/v1/tts/inference \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key-ID: <api-key>' \
  --data '
{
  "text": "नमस्ते, आप कैसे हैं?",
  "speaker_embedding": {
    "embedding": "<base64-encoded embedding>",
    "shape": [
      1,
      768
    ],
    "dtype": "torch.bfloat16"
  },
  "audio_config": {
    "sample_rate": 44100,
    "num_channels": 1,
    "sample_width": 2,
    "encoding": "linear_pcm",
    "container": "wav"
  }
}
'

import requests

url = "https://api.vachana.ai/api/v1/tts/inference"

payload = {
    "text": "नमस्ते, आप कैसे हैं?",
    "speaker_embedding": {
        "embedding": "<base64-encoded embedding>",
        "shape": [1, 768],
        "dtype": "torch.bfloat16"
    },
    "audio_config": {
        "sample_rate": 44100,
        "num_channels": 1,
        "sample_width": 2,
        "encoding": "linear_pcm",
        "container": "wav"
    }
}
headers = {
    "X-API-Key-ID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key-ID': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'नमस्ते, आप कैसे हैं?',
    speaker_embedding: {
      embedding: '<base64-encoded embedding>',
      shape: [1, 768],
      dtype: 'torch.bfloat16'
    },
    audio_config: {
      sample_rate: 44100,
      num_channels: 1,
      sample_width: 2,
      encoding: 'linear_pcm',
      container: 'wav'
    }
  })
};

fetch('https://api.vachana.ai/api/v1/tts/inference', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

"<string>"

{
  "success": false,
  "message": "Invalid request: Field required at body -> text",
  "status_code": 400
}

{
  "detail": {
    "error_code": "RATE_LIMITED",
    "message": "Only 1 active request is allowed at a time. Wait for your current request to finish before sending another.",
    "status_code": 429
  }
}

{
  "success": false,
  "message": "We are facing technical difficulties. Please try again later.",
  "status_code": 500
}

{
  "success": false,
  "error": {
    "type": "SERVICE_UNAVAILABLE",
    "message": "Text-to-speech service is temporarily unavailable."
  }
}

POST

api

tts

inference

Voice Cloned TTS Inference

curl --request POST \
  --url https://api.vachana.ai/api/v1/tts/inference \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key-ID: <api-key>' \
  --data '
{
  "text": "नमस्ते, आप कैसे हैं?",
  "speaker_embedding": {
    "embedding": "<base64-encoded embedding>",
    "shape": [
      1,
      768
    ],
    "dtype": "torch.bfloat16"
  },
  "audio_config": {
    "sample_rate": 44100,
    "num_channels": 1,
    "sample_width": 2,
    "encoding": "linear_pcm",
    "container": "wav"
  }
}
'

import requests

url = "https://api.vachana.ai/api/v1/tts/inference"

payload = {
    "text": "नमस्ते, आप कैसे हैं?",
    "speaker_embedding": {
        "embedding": "<base64-encoded embedding>",
        "shape": [1, 768],
        "dtype": "torch.bfloat16"
    },
    "audio_config": {
        "sample_rate": 44100,
        "num_channels": 1,
        "sample_width": 2,
        "encoding": "linear_pcm",
        "container": "wav"
    }
}
headers = {
    "X-API-Key-ID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key-ID': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'नमस्ते, आप कैसे हैं?',
    speaker_embedding: {
      embedding: '<base64-encoded embedding>',
      shape: [1, 768],
      dtype: 'torch.bfloat16'
    },
    audio_config: {
      sample_rate: 44100,
      num_channels: 1,
      sample_width: 2,
      encoding: 'linear_pcm',
      container: 'wav'
    }
  })
};

fetch('https://api.vachana.ai/api/v1/tts/inference', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

"<string>"

{
  "success": false,
  "message": "Invalid request: Field required at body -> text",
  "status_code": 400
}

{
  "detail": {
    "error_code": "RATE_LIMITED",
    "message": "Only 1 active request is allowed at a time. Wait for your current request to finish before sending another.",
    "status_code": 429
  }
}

{
  "success": false,
  "message": "We are facing technical difficulties. Please try again later.",
  "status_code": 500
}

{
  "success": false,
  "error": {
    "type": "SERVICE_UNAVAILABLE",
    "message": "Text-to-speech service is temporarily unavailable."
  }
}

Overview

Step 1 — Generate a voice embedding

Upload a reference audio clip to get a speaker_embedding. See Voice Clone Embeddings.

Step 2 — Synthesize with your cloned voice — this page

Pass the speaker_embedding from Step 1 to this endpoint to synthesize audio in your cloned voice.

Synthesize audio using your cloned voice. Pass the speaker_embedding obtained from Voice Clone Embeddings along with your text. The full audio is returned in one response. For streaming playback, see Voice Cloning Streaming or Voice Cloning Realtime.

Endpoint

POST https://api.vachana.ai/api/v1/tts/inference

Authentication

Header	Required	Description	Example
`X-API-Key-ID`	Yes	Your API key for authentication	`your-api-key-id`
`Content-Type`	Yes	Must be `application/json`	`application/json`

Request Body

string

required

The text to synthesize into speech

string

Voice cloning model. Use vachana-vc-v1. Automatically set when speaker_embedding is provided — you may omit this field.

object

required

Audio output configuration

Show properties

integer

Sample rate in Hz (8000-44100)

integer

Number of audio channels (1-8)

integer

Sample width in bytes (1-4)

string

Audio encoding format.

Value	Meaning
`linear_pcm`	Uncompressed PCM audio
`oggopus`	OGG Opus

string

Audio container format.

Value	Output
`wav`	WAV file
`raw`	Raw audio with no header
`mp3`	MP3 file. `bitrate` applies.
`ogg`	OGG Opus file
`mulaw`	G.711 µ-law

string

MP3 bitrate. Only used when container is mp3.

Value	Trade-off
`96k`	Smallest file of the three
`128k`	Standard quality
`192k`	Highest quality, largest file

object

required

Voice clone embedding obtained from the Voice Clone Embeddings endpoint

Show properties

string

required

The voice clone embedding string

array

required

Shape of the embedding tensor, e.g., [1, 768]

string

required

Data type of the embedding, e.g., torch.bfloat16

Response

Returns binary audio data in the format specified by audio_config.container:

audio/wav for WAV files
audio/mpeg for MP3 files
audio/ogg for OGG files

Example Request

curl -X POST https://api.vachana.ai/api/v1/tts/inference \
  -H "X-API-Key-ID: your-api-key-id" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "नमस्ते, आप कैसे हैं?",
    "model": "vachana-vc-v1",
    "audio_config": {
      "sample_rate": 44100,
      "encoding": "linear_pcm",
      "container": "wav"
    },
    "speaker_embedding": {
      "embedding": "your-embedding-string",
      "shape": [1, 768],
      "dtype": "torch.bfloat16"
    }
  }' \
  --output audio.wav

import requests

url = "https://api.vachana.ai/api/v1/tts/inference"
headers = {
    "X-API-Key-ID": "your-api-key-id",
    "Content-Type": "application/json"
}
payload = {
    "text": "नमस्ते, आप कैसे हैं?",
    "model": "vachana-vc-v1",
    "audio_config": {
        "sample_rate": 44100,
        "encoding": "linear_pcm",
        "container": "wav"
    },
    "speaker_embedding": {
        "embedding": "your-embedding-string",
        "shape": [1, 768],
        "dtype": "torch.bfloat16"
    }
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    with open("audio.wav", "wb") as f:
        f.write(response.content)
    print("Audio saved successfully")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

const url = "https://api.vachana.ai/api/v1/tts/inference";
const headers = {
  "X-API-Key-ID": "your-api-key-id",
  "Content-Type": "application/json"
};
const payload = {
  text: "नमस्ते, आप कैसे हैं?",
  model: "vachana-vc-v1",
  audio_config: {
    sample_rate: 44100,
    encoding: "linear_pcm",
    container: "wav"
  },
  speaker_embedding: {
    embedding: "your-embedding-string",
    shape: [1, 768],
    dtype: "torch.bfloat16"
  }
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.blob())
  .then(blob => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "audio.wav";
    a.click();
  })
  .catch(error => console.error("Error:", error));

Error Responses

Text-to-Speech and Voice Cloning (REST and SSE) return errors in a flat body, not the error.type envelope used by Speech-to-Text:

{"success": false, "message": "Invalid request: Field required at body -> text", "status_code": 400}

HTTP	When	Example `message`
`400`	A parameter is missing or invalid: `text`, `voice`, `model`, `speed` (the allowed range depends on the model), or a value in `audio_config`	`Invalid request: Value error, sample_rate must be one of [8000, 16000, 22050, 24000, 44100, 48000], got 12345 at body -> audio_config -> sample_rate`
`400`	Unknown `model`, or `vachana-vc-v1` without a `speaker_embedding`	`Model 'bogus' is not supported. The supported models are "timbre-v2.5", "timbre-v3.0". …`
`400`	Empty audio sent to the embeddings endpoint	`Audio file is empty`
`500`	Unexpected failure, including text that is too long and an invalid `speaker_embedding` or reference audio	`We are facing technical difficulties. Please try again later.`

Authentication and rate-limit errors use the shape shown below. Some validation failures on the embeddings endpoint can also return 422 with a {"detail": [...]} body. Authentication and rate-limit errors do not use the success / error envelope. They look like this:

{"detail": {"error_code": "RATE_LIMITED", "message": "Only 1 active request is allowed at a time. Wait for your current request to finish before sending another.", "status_code": 429}}

HTTP	`detail.error_code`	Typical cause
`401`	`MISSING_API_KEY`	The `X-API-Key-ID` header is missing or empty.
`401`	`INVALID_API_KEY`	The key is not valid (`"message": "Unauthorized"`).
`402`	not verified	Insufficient credit
`403`	`SCOPE_NOT_ALLOWED`	The key lacks the scope for this service (for example `Service 'STT' not in allowed scopes`).
`429`	`RATE_LIMITED`	Too many requests for your account. For example, an account limited to one active request at a time returns `429` while a request is still running. The response has no `Retry-After` header: wait a moment, then retry with backoff.

The same shapes are returned by REST, Batch, Text-to-Speech, Voice Cloning and the Realtime handshake (as an HTTP response before the WebSocket opens). See Error Reference for all Speech API errors.

Authorizations

X-API-Key-ID

string

header

required

Headers

X-API-Key-ID

string

required

Body

application/json

Request body for voice cloned TTS inference.

text

string

required

The text to synthesize into speech.

speaker_embedding

SpeakerEmbedding · object

required

Voice clone embedding from the Voice Clone Embeddings endpoint.

Show child attributes

audio_config

AudioConfig · object

required

Audio output configuration.

Show child attributes

model

enum<string>

Voice cloning model. Automatically set to vachana-vc-v1 when speaker_embedding is provided.

Available options:

vachana-vc-v1

Response

Successful audio synthesis

The response is of type file.

Gnani APIs

APIs

Use Cases

Reference

Overview

Endpoint

Authentication

Request Body

Response

Example Request

Error Responses

Authorizations

Headers

Body

Response

​Overview

​Endpoint

​Authentication

​Request Body

​Response

​Example Request

​Error Responses

Authorizations

Headers

Body

Response

Overview

Endpoint

Authentication

Request Body

Response

Example Request

Error Responses