---
title: "Create a reusable cloned voice"
method: POST
path: "/api/v1/voices"
tags: ["Public API v1"]
---

# Create a reusable cloned voice

`POST /api/v1/voices`

Clones a voice from a short reference clip and SAVES it, returning a persistent `voiceId` (clone_…). The voice then appears in GET /v1/voices (when you send your key) and is usable as `voiceId` in POST /v1/tts like any catalog voice. Pass `engine` to enrol on "v3" (default) or "v4"; the reference-clip duration limits differ per engine. A flat per-clone token cost is charged on create (independent of clip/text length, × the engine multiplier); subsequent generation bills per character at that engine's rate. Subject to your plan’s cloned-voice limit — delete unused voices with DELETE /v1/voices/{voiceId}.

## Response `201`

The saved voice. Use `voiceId` in any later generation call.

- PublicClonedVoiceDto
  - `voiceId` string, required — Persistent voice id — pass as `voiceId` to POST /v1/tts.
  - `name` string, required
  - `engine` 'v3' | 'v4', required — The engine this voice was enrolled for, and the only one it renders on. Pass it as `engine` alongside this `voiceId` in POST /v1/tts.
  - `sampleAudioUrl` string, nullable — Preview sample, rendered best-effort after the voice is saved — expect null for a short while after create, and treat null as "no preview yet", not as a failed clone. A HOST-RELATIVE path outside `/api/v1`: it is served by the application, is not part of this versioned contract, and may change or disappear without a version bump. Do not build against it — re-synthesize with the `voiceId` if you need a durable sample.
  - `createdAt` string, required

## Other responses

- `400` — Missing reference clip, missing/incorrect `refText`, clip outside the engine's duration window, or `consent` not given.
- `401` — API key missing, malformed, or revoked.
- `403` — Your plan does not include cloning, does not include this engine, you have reached its cloned-voice limit, or the grant is out of tokens / expired.
- `413` — Reference clip larger than 10 MB.
- `429` — Rate limit or token quota exceeded. When the limit came from the application the response carries `Retry-After` (seconds) and the `X-RateLimit-*` headers and is counted against your API key; a 429 with none of those headers came from the edge proxy and is counted against your source address, shared with every other key calling from it. Back off on either.

---

[API](https://skmtc.dev/vieneu/apis/vieneu-api.md) · [All operations](https://skmtc.dev/vieneu/apis/vieneu-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vieneu/vieneu-api/revisions/11c8166a6c4d/schema)