> ## Documentation Index
> Fetch the complete documentation index at: https://help.verbosec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /voice/synthesize — Text-to-Speech API

> Convert text to speech and clone voices via the Verbosec API. Select voice, language, and speed. Returns a URL to download the generated audio file.

The Nexus Voice Generation endpoints convert written text into natural-sounding speech and let you create custom cloned voices from audio samples. You submit your text content along with optional parameters to select the voice, output language, and speaking speed. Nexus AI processes your request and returns a URL to an MP3 audio file hosted on the Verbosec CDN, ready to download or stream.

This page covers the following endpoints:

* `POST /voice/synthesize` — Convert text to speech
* `POST /voice/clone` — Clone a voice from an audio sample

***

## Synthesize speech

**Endpoint**

```
POST https://api.verbosec.com/v1/voice/synthesize
```

## Request parameters

<ParamField body="text" type="string" required>
  The text you want to convert to speech. There is no strict character limit, but longer inputs take more time to process and consume more of your plan's quota.
</ParamField>

<ParamField body="voice_id" type="string">
  The identifier of the voice to use for synthesis. If omitted, the API uses the default voice for the specified language.
</ParamField>

<ParamField body="language" type="string">
  The BCP-47 language code for the output speech — for example, `"en"`, `"fr"`, or `"de"`. Defaults to `"en"`. The voice you select must support the language you specify.
</ParamField>

<ParamField body="speed" type="float">
  A multiplier that controls how fast the speech is delivered. Accepts a value between `0.5` (half speed) and `2.0` (double speed). Defaults to `1.0` (normal speed).
</ParamField>

## Example request

```bash synthesize-voice.sh theme={null}
curl -X POST https://api.verbosec.com/v1/voice/synthesize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Verbosec. Your AI-powered content platform.",
    "voice_id": "voice_en_clara",
    "language": "en",
    "speed": 1.1
  }'
```

## Example response

```json response.json theme={null}
{
  "id": "voice_def456",
  "audio_url": "https://cdn.verbosec.com/audio/voice_def456.mp3",
  "duration_seconds": 12.4,
  "created_at": "2025-01-15T10:32:00Z"
}
```

## Response fields

<ResponseField name="id" type="string">
  A unique identifier for this voice synthesis request.
</ResponseField>

<ResponseField name="audio_url" type="string">
  The CDN URL for the generated MP3 audio file. Use this URL to download or stream the audio in your application.
</ResponseField>

<ResponseField name="duration_seconds" type="float">
  The total playback duration of the generated audio file, in seconds.
</ResponseField>

<ResponseField name="created_at" type="string">
  An ISO 8601 timestamp indicating when the audio file was generated.
</ResponseField>

<Note>
  Audio files are available for **24 hours** after generation. Download and store them in your own storage if you need long-term access.
</Note>

***

## Clone a voice

Create a custom cloned voice from an audio sample. Once cloned, the voice receives a unique `voice_id` that you can pass to `POST /voice/synthesize` to generate speech in that voice.

**Endpoint**

```
POST https://api.verbosec.com/v1/voice/clone
```

### Request parameters

<ParamField body="name" type="string" required>
  A display name for the cloned voice — for example, `"My Brand Voice"`. Used to identify the voice in your account.
</ParamField>

<ParamField body="sample_url" type="string" required>
  A publicly accessible URL pointing to an audio file (MP3 or WAV) to use as the voice sample. For best results, provide a clean recording of at least 30 seconds with minimal background noise.
</ParamField>

### Example request

```bash clone-voice.sh theme={null}
curl -X POST https://api.verbosec.com/v1/voice/clone \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Brand Voice",
    "sample_url": "https://example.com/samples/brand-voice.mp3"
  }'
```

### Example response

```json clone-response.json theme={null}
{
  "voice_id": "voice_clone_uvw890",
  "name": "My Brand Voice",
  "status": "processing",
  "created_at": "2025-01-15T10:34:00Z"
}
```

### Response fields

<ResponseField name="voice_id" type="string">
  The unique identifier for the cloned voice. Pass this value as `voice_id` in a `POST /voice/synthesize` request to use this voice for speech synthesis.
</ResponseField>

<ResponseField name="name" type="string">
  The display name you assigned to the cloned voice.
</ResponseField>

<ResponseField name="status" type="string">
  The processing status of the clone. The voice becomes available for synthesis once the status is `"ready"`. Possible values are `"processing"` and `"ready"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  An ISO 8601 timestamp indicating when the cloning request was submitted.
</ResponseField>

<Tip>
  Poll the status field or wait a few minutes after submitting a clone request before attempting synthesis. Voice cloning typically completes within two to five minutes depending on the length of the sample.
</Tip>

***

## Error responses

<Accordion title="400 Bad Request — Missing or invalid parameters">
  Returned when the `text` field is missing from a synthesize request, the `speed` value is outside the accepted range, or a required field is absent from a clone request.

  ```json 400-response.json theme={null}
  {
    "error": {
      "code": "invalid_parameter",
      "message": "The 'speed' parameter must be between 0.5 and 2.0."
    }
  }
  ```
</Accordion>

<Accordion title="401 Unauthorized">
  Returned when your API key is missing or invalid. See the [Authentication guide](/api-reference/authentication) for help.

  ```json 401-response.json theme={null}
  {
    "error": {
      "code": "unauthorized",
      "message": "Invalid or missing API key."
    }
  }
  ```
</Accordion>

<Accordion title="429 Too Many Requests — Rate limited">
  Returned when you have exceeded your plan's rate limit. Wait the number of seconds indicated in the `Retry-After` header before retrying.

  ```json 429-response.json theme={null}
  {
    "error": {
      "code": "rate_limit_exceeded",
      "message": "You have exceeded your plan's rate limit. Please wait before retrying."
    }
  }
  ```
</Accordion>