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

# Clone a voice and generate speech with the Percify API

> Clone a voice from a short sample with zonos2, or use a preset text to speech voice, through POST /v1/run. Inputs, pricing and example code.

The Percify API clones a voice with the `zonos2` model: send the text to speak and a URL of a short recording of the voice, and the generation returns an audio file of that voice saying your text. For a ready-made voice instead of a clone, the same `POST /v1/run` endpoint runs text to speech models such as `speech-02-hd` and `chatterbox-turbo`. The REST API does not store voices, so you send the voice sample, or pick the preset voice, on each call.

## Clone a voice with zonos2

```http theme={"system"}
POST https://api.percify.io/v3/playground/v1/run
```

<ParamField body="modelId" type="string" required>
  `zonos2`
</ParamField>

<ParamField body="input.text" type="string" required>
  What the cloned voice should say.
</ParamField>

<ParamField body="input.audio" type="string" required>
  Public `https` URL of a short `.mp3` or `.wav` recording of the voice to clone. Clean speech with little background noise works best.
</ParamField>

<ParamField body="input.clean_speaker_background" type="boolean" default="false">
  Remove background noise from the recording before cloning.
</ParamField>

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -s -X POST https://api.percify.io/v3/playground/v1/run \
    -H "Authorization: Bearer $PERCIFY_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: welcome-line-de" \
    -d '{
      "modelId": "zonos2",
      "input": {
        "text": "Guten Tag und willkommen bei unserem Kurs.",
        "audio": "https://example.com/voice-sample.wav",
        "clean_speaker_background": true
      }
    }'
  ```

  ```javascript Node.js theme={"system"}
  const res = await fetch("https://api.percify.io/v3/playground/v1/run", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PERCIFY_API_TOKEN}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "welcome-line-de",
    },
    body: JSON.stringify({
      modelId: "zonos2",
      input: {
        text: "Guten Tag und willkommen bei unserem Kurs.",
        audio: "https://example.com/voice-sample.wav",
        clean_speaker_background: true,
      },
    }),
  });
  const { data } = await res.json();
  console.log(data.id);
  ```

  ```python Python theme={"system"}
  import os, requests

  data = requests.post(
      "https://api.percify.io/v3/playground/v1/run",
      headers={
          "Authorization": f"Bearer {os.environ['PERCIFY_API_TOKEN']}",
          "Idempotency-Key": "welcome-line-de",
      },
      json={
          "modelId": "zonos2",
          "input": {
              "text": "Guten Tag und willkommen bei unserem Kurs.",
              "audio": "https://example.com/voice-sample.wav",
              "clean_speaker_background": True,
          },
      },
  ).json()["data"]
  print(data["id"])
  ```
</CodeGroup>

Wait for the result with [`GET /v1/generations/{id}?wait=45`](/api-reference/generations/get). The audio file URL is in `output.urls[0]`, with `output.type` set to `audio`.

### How is voice cloning priced?

`zonos2` is priced by the length of the voice sample you pass in `audio`, not by the length of the text, so a longer sample can cost more. Percify measures the file itself, so call [`POST /v1/estimate`](/api-reference/generations/estimate) with the same input for the exact credits.

## Other voice models

The catalog has more speech models. Each takes its own inputs, listed in `input_schema` from [`GET /v1/models/{id}`](/api-reference/models).

| Model id            | How you choose the voice                      | Notes from its schema                                                    | Credits per run on 16 Sep 2026 |
| ------------------- | --------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------ |
| `chatterbox-turbo`  | `voice` preset, or `reference_audio` to clone | Text up to 500 characters; reference audio must be longer than 5 seconds | 5                              |
| `xtts-v2`           | `speaker`: an audio sample to clone           | `language` option                                                        | 10                             |
| `speech-02-hd`      | `voice_id` system voice                       | Text up to 10,000 characters; `emotion`, `speed`, `pitch`                | 5                              |
| `speech-02-turbo`   | `voice_id` system voice                       | Same inputs as `speech-02-hd`                                            | 5                              |
| `gemini-tts`        | `voice` preset                                | `style_instructions` for delivery; priced by text length                 | Varies                         |
| `qwen3-tts-flash`   | `voice` preset                                | `language_type` option                                                   | 2                              |
| `seed-speech-tts-2` | `voice` preset                                | `voice_instruction` for tone and pace                                    | 3                              |

Models without a `pricing` object in the catalog charge the same credits for every run. Check `GET /v1/models` for current prices.

## Use the audio in a talking avatar

A generated voice track can go straight into lip-sync: pass `output.urls[0]` as `input.audio` to `infinitetalk-fast` or `infinitetalk`. See [Make a talking avatar video](/api-reference/avatars/overview).

## Tips

* **Reuse one sample** for a consistent voice across many clips.
* **Only clone voices you have permission to use.**
* **Host samples on a public `https` URL.** If Percify cannot download the `zonos2` sample, the run stops with `audio URL is not reachable` before anything is charged.

## Related

<CardGroup cols={2}>
  <Card title="Talking avatar pipeline" href="/api-reference/avatars/overview">
    Turn the voice into a lip-synced video.
  </Card>

  <Card title="Estimate cost" href="/api-reference/generations/estimate">
    Price a clone before you run it.
  </Card>

  <Card title="Voice cloning in the app" href="/percify/voice-cloning">
    Clone and use a voice without code.
  </Card>

  <Card title="Voice clone troubleshooting" href="/troubleshooting/voice-clone-issues">
    Fixes when a cloned voice sounds wrong.
  </Card>
</CardGroup>