---
title: "Clone Voice Assisted"
method: POST
path: "/voices/assisted"
---

# Clone Voice Assisted

`POST /voices/assisted`

## Request

- Base URL: `https://api.neuphonic.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.neuphonic.com/voices/assisted`
- Auth: none declared

Clone a voice from a full recording of a known script, and speak one clip back.

Where `POST /voices` takes a reference the caller already cut and trusts ASR to say what is
in it, this takes the whole enrollment recording and cuts the reference itself: the script
is force-aligned to the audio, every run of whole sentences between 4 and 13 seconds is
scored, the best is cut, and its punctuation is rewritten to the pauses the speaker actually
left. See `api.services.enrollment`.

Args:
    voice_name: The desired name for the cloned voice.
    voice_tags: Comma-separated tags for the voice.
    lang_code: Language of the voice.
    script: The text the speaker read. Defaults to the built-in script for `lang_code`,
        which is what `GET /voices/assisted/script` returns.
    preview_text: Line to speak back with the new voice. Defaults to a fixed sentence;
        pass an empty string to skip the preview.
    fast: Use our own enhancer (~10 s for a typical take) instead of the external one
        (typically 20-30 s, up to ~40 s). The external one handles clipping and uneven
        levels better, so clipped takes are likelier to be rejected with `fast`.
        Without `fast` our enhancer runs alongside the external one, and its clone is
        returned when the external one is unavailable or its side rejects the recording.
        `reference.enhancer` says which ran.
    candidates: Offer several voices to choose between instead of one (see Returns). The
        recording is enhanced once by each enhancer either way.
    voice_file: The enrollment recording, the whole script in one take, 15-60 seconds.

Returns:
    dict: the new `voice_id`, a `reference` report describing what was chosen and why, and
        a `preview` clip unless one was not requested or could not be produced. The voice is
        stored with `assisted` true and the report in `assisted_report`.

        With `candidates`: a candidate set, a voice per usable pair of consecutive
        sentences (up to MAX_SEGMENTS, the best if there are more, or the single clone's
        passage if none is usable), cut from the external enhancer's output and named
        `<voice_name>_slow_<first sentence>`, plus, without `fast`, the best pair cut from our
        own as `<voice_name>_fast_<n>`; when the external enhancer gives none, the pairs come
        from our own. Every voice is tagged `candidates:<set id>`. `candidates` lists them
        best first, each with its `rank`, `candidate` id, `reference` report and `preview`;
        each enhancer's best also comes as a `top_k` 10 variant (`<id>_top_k_10`, the same
        voice, the same rank), whose preview is that voice synthesised with exactly its
        `top_k` and `temperature` (null leaves the default). Every voice is kept, with
        `assisted` true, `selected` false and its offer, rank, sampling variants and
        reference report in `assisted_report`; POST /voices/assisted/choose records which
        one the user picked.

## Query parameters

- `voice_name` string, required
- `voice_tags` string
- `lang_code` string
- `script` string
- `preview_text` string
- `fast` boolean
- `candidates` boolean
- `api_key` string, nullable
- `jwt_token` string, nullable

## Headers

- `X-API-KEY` string, nullable
- `authorization` string, nullable

## Request body `multipart/form-data`

- BodyCloneVoiceAssistedVoicesAssistedPost
  - `voice_file` string, binary, required

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-10** `fe945b7061a6`: 1 info
  - added the new optional `query` request parameter `candidates`
- **2026-09-25** `7d337df58e2c`: 1 info
  - added the new optional `query` request parameter `fast`
- **2026-09-23** `488903dca48b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/neuphonic/apis/neuphonic-api/changes/voices/assisted/post.md)

---

[API](https://skmtc.dev/neuphonic/apis/neuphonic-api.md) - [All operations](https://skmtc.dev/neuphonic/apis/neuphonic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/neuphonic/apis/neuphonic-api/revisions/941fd29844c9?raw)