> ## Documentation Index
> Fetch the complete documentation index at: https://dev.docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a PVC voice
> Creates a new Professional Voice Clone in `PVC_VOICE_STATE_DRAFT`. Upload audio samples with [Upload PVC voice samples](/api-reference/pvcAPI/pvcvoiceservice/upload-pvc-voice-samples), then start training with [Train a PVC voice](/api-reference/pvcAPI/pvcvoiceservice/train-pvc-voice).
**Language.** Only `en-US` is currently supported for Professional Voice Cloning. `languageCode` is immutable after creation.
Each voice claims one of your plan's **PVC voice slots** for as long as it exists. Check your usage with [Resolve upload limits](/api-reference/pvcAPI/pvcvoiceservice/resolve-pvc-upload-limits) (`usedPvcVoiceSlots` / `maxPvcVoiceSlots`); when all slots are taken, creation is refused until a slot is freed or the plan is upgraded. On-Demand accounts also need a payment method on file.
Creates a new voice in `PVC_VOICE_STATE_DRAFT`. A draft voice has no audio yet — build it out with the rest of this API before training:
This endpoint. Returns a `voiceId` derived from `displayName`.
[Upload PVC voice samples](/api-reference/pvcAPI/pvcvoiceservice/upload-pvc-voice-samples) — repeat until you have at least 10 minutes of cumulative audio. Optionally trim individual samples with [Trim a PVC voice sample](/api-reference/pvcAPI/pvcvoiceservice/trim-pvc-voice-sample).
[Train a PVC voice](/api-reference/pvcAPI/pvcvoiceservice/train-pvc-voice) starts training and moves the voice to `PVC_VOICE_STATE_QUEUED`.
[Get a PVC voice](/api-reference/pvcAPI/pvcvoiceservice/get-pvc-voice) to watch `state` progress to `PVC_VOICE_STATE_READY` (or `PVC_VOICE_STATE_FAILED`). Once ready, use the `voiceId` anywhere you'd use a regular voice, e.g. [Synthesize speech](/api-reference/ttsAPI/texttospeech/synthesize-speech).
For recording and preparation tips, see [Voice Cloning best practices](/tts/best-practices/voice-cloning#best-practices-for-professional-voice-cloning).
## OpenAPI
````yaml post /voices/v1/pvcVoices
openapi: 3.0.0
info:
title: Inworld Professional Voice Cloning API
version: v1
contact:
name: Inworld AI
url: https://inworld.ai
email: support@inworld.ai
servers:
- url: https://api.inworld.ai
security:
- inworld_basic: []
tags:
- name: PvcVoiceService
paths:
/voices/v1/pvcVoices:
post:
tags:
- PvcVoiceService
summary: Create a draft PVC voice
description: >-
Creates a new Professional Voice Clone in `PVC_VOICE_STATE_DRAFT`.
Upload audio samples with [Upload PVC voice
samples](/api-reference/pvcAPI/pvcvoiceservice/upload-pvc-voice-samples),
then start training with [Train a PVC
voice](/api-reference/pvcAPI/pvcvoiceservice/train-pvc-voice).
operationId: PvcVoiceService_CreatePvcVoice
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PvcVoiceServiceCreatePvcVoiceBody'
example:
displayName: my-professional-voice
languageCode: en-US
required: true
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/inworldvoicev1PvcVoice'
examples:
draft_voice:
summary: Newly created draft voice
value:
name: >-
workspaces/your_workspace_id/pvcVoices/my-professional-voice
voiceId: my-professional-voice
displayName: my-professional-voice
languageCode: en-US
state: PVC_VOICE_STATE_DRAFT
incarnationId: a1b2c3d4
samples: []
createTime: '2026-08-31T12:00:00Z'
updateTime: '2026-08-31T12:00:00Z'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl --location 'https://api.inworld.ai/voices/v1/pvcVoices' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"displayName": "my-professional-voice",
"languageCode": "en-US"
}'
- lang: python
label: Python
source: |-
import requests
url = "https://api.inworld.ai/voices/v1/pvcVoices"
headers = {
"Authorization": "Basic ",
"Content-Type": "application/json"
}
payload = {
"displayName": "my-professional-voice",
"languageCode": "en-US"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
- lang: javascript
label: JavaScript
source: |-
const url = 'https://api.inworld.ai/voices/v1/pvcVoices';
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': 'Basic ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
displayName: 'my-professional-voice',
languageCode: 'en-US',
}),
});
const data = await response.json();
console.log(data);
components:
schemas:
PvcVoiceServiceCreatePvcVoiceBody:
type: object
properties:
displayName:
type: string
description: >-
The human-readable name shown anywhere the voice is listed or
selected. The voice's `voiceId` is derived from this value; renaming
the voice later does not change its `voiceId`.
languageCode:
type: string
description: >-
The voice's language as a BCP-47-shaped locale string. Currently
only `en-US` is supported for Professional Voice Cloning; defaults
to `en-US` if omitted. Immutable after creation.
description: Request message for CreatePvcVoice.
required:
- displayName
inworldvoicev1PvcVoice:
type: object
properties:
name:
type: string
description: 'Resource name. Format: `workspaces/{workspace}/pvcVoices/{voice}`.'
readOnly: true
voiceId:
type: string
description: >-
Voice ID, derived from `displayName` at creation time. Use this
value as `{voiceId}` on every other PVC endpoint, and as the
`voiceId` in TTS synthesis requests once the voice is
`PVC_VOICE_STATE_READY`.
readOnly: true
displayName:
type: string
description: >-
The human-readable name shown anywhere the voice is listed or
selected.
languageCode:
type: string
description: >-
The voice's language as a BCP-47-shaped locale string, e.g. `en-US`.
Immutable after creation.
state:
$ref: '#/components/schemas/inworldvoicev1PvcVoiceState'
failure:
$ref: '#/components/schemas/inworldvoicev1PvcVoiceFailure'
incarnationId:
type: string
description: >-
Identifier that stays stable across edits to the same voice, and
changes each time it is retrained. Use it to tell two reads of the
same `voiceId` apart across a retrain.
readOnly: true
samples:
type: array
items:
$ref: '#/components/schemas/inworldvoicev1PvcVoiceSample'
description: Audio samples currently attached to the voice.
readOnly: true
createTime:
type: string
format: date-time
readOnly: true
updateTime:
type: string
format: date-time
readOnly: true
description: A Professional Voice Clone resource.
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
description: >-
The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].
message:
type: string
description: >-
A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or
localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
description: >-
A list of messages that carry the error details. There is a common
set of message types for APIs to use.
description: >-
The `Status` type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs.
inworldvoicev1PvcVoiceState:
type: string
enum:
- PVC_VOICE_STATE_UNSPECIFIED
- PVC_VOICE_STATE_DRAFT
- PVC_VOICE_STATE_QUEUED
- PVC_VOICE_STATE_TRAINING
- PVC_VOICE_STATE_READY
- PVC_VOICE_STATE_FAILED
description: >-
Lifecycle state of a PVC voice.
- `PVC_VOICE_STATE_DRAFT`: Editable. Samples can be added, trimmed, or
removed, and metadata can be updated.
- `PVC_VOICE_STATE_QUEUED`: Training requested; waiting for a training
slot.
- `PVC_VOICE_STATE_TRAINING`: Actively training.
- `PVC_VOICE_STATE_READY`: Training succeeded. Usable for TTS synthesis;
permanent — cannot be deleted through this API.
- `PVC_VOICE_STATE_FAILED`: Training failed. Editing the voice (e.g.
renaming it, or adding/removing a sample) returns it to
`PVC_VOICE_STATE_DRAFT` with its remaining samples intact.
inworldvoicev1PvcVoiceFailure:
type: object
properties:
reason:
type: string
description: >-
Machine-readable failure code, e.g. `TRAINING_ERROR`. New values may
be added over time, so don't validate against a hardcoded list —
fall back to displaying `message` for codes you don't recognize.
message:
type: string
description: >-
Human-readable, scrubbed failure message. Never contains uploaded
audio, filenames, or transcripts.
description: Populated on a PVC voice when its `state` is `PVC_VOICE_STATE_FAILED`.
inworldvoicev1PvcVoiceSample:
type: object
properties:
sampleId:
type: string
description: >-
Sample ID. Use this value as `{sampleId}` when trimming or deleting
the sample.
readOnly: true
name:
type: string
description: >-
Resource name. Format:
`workspaces/{workspace}/pvcVoices/{voice}/samples/{sample}`.
readOnly: true
sizeBytes:
type: integer
format: int64
description: Size of the uploaded file, in bytes.
readOnly: true
durationSecs:
type: number
format: float
description: >-
Analyzed duration of the sample, in seconds, before any trim is
applied.
readOnly: true
mimeType:
type: string
enum:
- audio/wav
- audio/webm
- audio/mpeg
description: Detected audio format, sniffed from the file's byte content.
readOnly: true
hash:
type: string
description: >-
Base64-encoded MD5 of the stored object, for verifying upload
integrity against the source file.
readOnly: true
trimStartMs:
type: integer
format: int32
nullable: true
description: Trim start offset in milliseconds, if set.
trimEndMs:
type: integer
format: int32
nullable: true
description: Trim end offset in milliseconds, if set.
description: A single uploaded audio sample belonging to a PVC voice.
protobufAny:
type: object
properties:
'@type':
type: string
description: >-
A URL/resource name that uniquely identifies the type of the
serialized protocol buffer message.
additionalProperties: {}
description: >-
`Any` contains an arbitrary serialized protocol buffer message along
with a URL that describes the type of the serialized message.
securitySchemes:
inworld_basic:
type: apiKey
in: header
name: Authorization
description: >-
Your [API key](../../../api-reference/introduction). Read permissions
are required for GET endpoints. Write permissions are required for POST,
PATCH, and DELETE endpoints.
For Basic authentication, please populate `Basic $INWORLD_API_KEY`. You can create a key in one command with the [Inworld CLI](../../../tts/resources/inworld-cli): `inworld workspace add-key`.
````