# Convert speech to a target voice

- **Method:** `POST`
- **Path:** `/api/v1/conversion/convert`
- **Operation ID:** `start_voice_conversion_api_v1_conversion_convert_post`
- **Tags:** Conversion

Convert the speaker identity of source audio to a target voice.

Keeps the words, timing, and prosody of the source recording while
re-rendering it in the target speaker's voice (zero-shot, via the
Chatterbox S3Gen stack). Provide either `target_voice_id` (saved
library voice) or `target_audio_base64` (6-10s of clean speech).

Use `?sync=true` to block until audio is ready. Otherwise poll
`GET /api/v1/conversion/progress` and `GET /api/v1/conversion/result`.

## Effective servers

- `http://127.0.0.1:8100`

  Voice Creator Pro on this computer

## Query parameters

- **`sync`**: `boolean`, default: `false`

  Wait for conversion to complete and return audio directly

## Request body

**Required:** `true`

**Content type:** `application/json`

schema: `ConvertVoiceRequest`

- **`source_audio_base64` (required)**: `string`

  Base64-encoded source audio (WAV) whose speech will be converted
- **`cfg_rate`**

  Classifier-free guidance strength for the S3Gen flow. Higher pushes harder toward the target voice. Defaults to 0.7.

  **Any of:**
  - `number`, minimum: `0`, maximum: `1`
  - `null`
- **`model_family`**: `string | null`

  Voice conversion model. Query GET /api/v1/conversion/models for options. Defaults to chatterbox.
- **`steps`**

  Flow-matching diffusion steps. More steps can sound smoother but take longer. Defaults to 10.

  **Any of:**
  - `integer`, minimum: `1`, maximum: `50`
  - `null`
- **`target_audio_base64`**: `string | null`

  Base64-encoded target reference audio (WAV), 6-10 seconds of clean speech
- **`target_voice_id`**: `string | null`

  Saved library voice to convert to. Either this or target\_audio\_base64 is required.

**Example:**

```json
{
  "source_audio_base64": "UklGRi4AAABXQVZFZm10IBAAAA...",
  "target_voice_id": "a1b2c3d4",
  "target_audio_base64": "UklGRi4AAABXQVZFZm10IBAAAA...",
  "model_family": "chatterbox",
  "cfg_rate": 0.7,
  "steps": 10
}
```

## Responses

### 200 Conversion started (async) or completed result (sync).

**Content type:** `application/json`

**Any of:**

- `object`, schema: `GenerationStartedResponse`
  - **`queue_position` (required)**: `integer`

    Position in the generation queue (0 = next to run)
  - **`started` (required)**: `boolean`

    Whether the generation job was enqueued
- `object`, schema: `GenerationResult`
  - **`status` (required)**: `string`

    Human-readable status message
  - **`success` (required)**: `boolean`

    Whether generation completed successfully
  - **`audio_base64`**: `string | null`

    Base64-encoded audio output (WAV format)
  - **`error_code`**: `string | null`

    Machine-readable failure code when success is false
  - **`error_detail`**: `string | null`

    Extra detail for the failure code

**One of:**

- *Schema `GenerationStartedResponse` is shown above.*
- *Schema `GenerationResult` is shown above.*

**Example:**

```json
{
  "started": true,
  "queue_position": 0
}
```

### 400 Invalid voice\_id format.

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

### 504 Sync conversion timed out (600s limit).

## Schemas

- `ConvertVoiceRequest` — shown above.
- `GenerationResult` — shown above.
- `GenerationStartedResponse` — shown above.
- `HTTPValidationError` — shown above.
- `ValidationError` — shown above.