# Clone voice (TTS)

> `POST /job/add/paperoffice_voice___tts` · Section: Media AI — Voice · PaperOffice AI API, release `R20261020.2258`.

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

## Overview
Clone a **custom voice** from a short audio sample and speak new text with PaperOffice neural TTS.

Use this endpoint when you need a voice that is **not** in the catalog (`POST /voice/voices`). Upload `voice_sample` instead of setting `voice`.

**Pipeline:** `paperoffice_voice___tts` (same URL as catalog TTS — body differs).

**Tier requirement:** `quality` must be **`premium`** or **`ultra`**. `basic` is rejected for voice cloning.

## Prerequisites
1. Prepare a **clean voice sample**: **minimum 10 seconds**, recommended **15–30 seconds** of continuous single-speaker speech (max 10 MB).
2. Do **not** set catalog `voice` — clone mode is triggered by `voice_sample`.
3. Optional: `language` (`en`, `de`, …) or `auto` — omit or use `auto` for detection from the sample.
4. **Strongly recommended:** `reference_text` — transcript of what is spoken in `voice_sample` (improves clone quality).

## Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `text` | yes | — | Up to 50,000 characters. Emotion markers: `[chuckle]`, `[laugh]`, `[sigh]`, `[whisper]`, `[happy]`, `[excited]`. |
| `voice_sample` | yes | — | Multipart audio (min. **10 s**, recommended 15–30 s). WAV, MP3, OGG, FLAC, M4A, WebM, AAC. |
| `reference_text` | no | — | Transcript of `voice_sample` (max 2,000 chars). **Strongly recommended.** Alias: `voice_sample_text`. |
| `quality` | no | `premium` | **`premium`** or **`ultra` only**. |
| `output_format` | no | `mp3` | `mp3`, `wav`, `ogg`. |
| `output` | no | `inline` | `inline` (audio in HTTP body), `base64`, or `url`. |
| `language` | no | `auto` | Optional. Omit or `auto` to detect from the **text to speak**; or set `en`, `de`, etc. for explicit output language. |

## Connection hold & polling (about 5 minute limit)

- Default: wait on this request up to **about 295 seconds**, then result or **HTTP 202**.
- Poll `GET /job/get/{job_id}` after **202** until `job_status` is `completed` or `failed`.

## Start-SLA / processing_lane — Voice

Omit `processing_lane` → workspace default / fair-use `no_sla`. Lanes: no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant.

## Related endpoints

| Use case | Postman item |
|----------|----------------|
| Catalog voice | List available TTS voices → Generate speech (single voice) |
| Multi-speaker | Generate multi-speaker TTS | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to speak (max 50,000 characters). Inline emotion markers: [chuckle] [laugh] [sigh] [breath] [whisper] [happy] [excited]. Default demo after voice_sample upload. (default: "[happy] This is your cloned voice on PaperOffice neural TTS. [breath] Support ticket TCK-88421 is now marked resolved. [excited] Record one clean sample, then narrate any new script with emotions like [sigh] or [whisper] — no extra studio session required.") |
| `voice_sample` | string | Yes | Voice sample audio file (required). Minimum 10 seconds, recommended 15–30 s, clean single-speaker speech, max 10 MB. WAV, MP3, OGG, FLAC, M4A, WebM, AAC. |
| `reference_text` | string | No | Transcript of the spoken content in voice_sample (strongly recommended for clone quality). Max 2,000 characters. Alias: voice_sample_text. (default: "Welcome to PaperOffice. This is the spoken content of my voice sample for cloning.") |
| `quality` | string | No | Quality tier: premium (balanced) or ultra (best). Basic is NOT supported for cloning. (allowed: premium, ultra) (default: "premium") |
| `output_format` | string | No | Audio format: mp3, wav, ogg. Default: mp3. (allowed: mp3, wav, ogg) (default: "mp3") |
| `output` | string | No | Response: inline (audio stream in HTTP body, default), base64 (JSON), or url (download link in JSON). (allowed: inline, base64, url) (default: "inline") |
| `language` | string | No | Language of the output text (optional). Omit or use auto to detect from the text to speak — not from the voice sample. (default: "auto") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`, `file_1`, or `files` (all accepted) or pass `files` as a JSON array of HTTPS URLs / `source_url` / `file_url`. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

## Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`; after poll read `result ?? job_result`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

## Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Completed payload key:** After polling, OCR pipelines return the payload in `job_result`; workflow/IDP (`POST /job/add/workflow`) return it in `result`. Always read `result ?? job_result`. See **Job result schema**.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

## Essentials (all endpoints)

- **Base URL:** `https://api.paperoffice.ai/latest` · **Auth:** `Authorization: Bearer po_sk_…` or `po_ut_…` (server-side only); browser code uses `po_pk_…` with an allowlisted `Origin`. No Bearer at all on a product API returns HTTP 403 `TIER_RESTRICTED`.
- **Errors:** HTTP 4xx/5xx with `status: "error"`, `code` and `message`. Retry 429 (`Retry-After`) and 5xx with exponential backoff; do not retry validation errors.
- **Jobs:** `client_wait=true` (default) holds the connection. HTTP 202 means the job is still running — poll `GET /job/get/{job_id}` every 5–10 s until `job_status` is `completed`, then read `result ?? job_result`. `processing_lane` sets the Start-SLA; legacy `priority` is not part of the public contract.
- **Billing:** every billable product call costs at least 5 credits; read `_billing.job.credits_billed` on billed responses.
- **Mutations** use `POST` with action paths (e.g. `POST /documents/document-delete`), not HTTP `DELETE`.

---

All endpoints: [llms.txt](https://api.paperoffice.ai/latest/docs/llms.txt) · Everything in one file: [llms-full.txt](https://api.paperoffice.ai/latest/docs/llms-full.txt) · [OpenAPI 3.1](https://api.paperoffice.ai/latest/docs/openapi.json) · This page: https://api.paperoffice.ai/latest/docs/endpoints/po-tts-voice-cloning.md

*Generated 2026-10-20 from live API documentation (release `R20261020.2258`).*