PvcVoiceService
Create a PVC voice
Create a draft professional voice clone (PVC) with the Inworld Voice API. Upload audio samples next, then start training.
/voices/v1/pvcVoicesLanguage. Support for multiple languages is experimental. languageCode defaults to en-US and cannot change after creation.
A draft voice has no audio yet. Follow these steps to add samples and train it:
Upload audio samples
Use Upload PVC voice samples until you have at least 10 minutes of audio in total. To trim individual samples, use Trim a PVC voice sample.
Train
Train a PVC voice starts training and moves the voice to PVC_VOICE_STATE_QUEUED.
Poll until ready
Poll Get a PVC voice until state reaches PVC_VOICE_STATE_READY or PVC_VOICE_STATE_FAILED. Once ready, customVoice names the trained voice. Find its voiceId with List voices, and use it anywhere you'd use a regular voice, such as Synthesize speech.
Each voice uses one of your plan's PVC voice slots for as long as it exists. Check usedPvcVoiceSlots and maxPvcVoiceSlots with Resolve upload limits. If all slots are taken, you must free a slot or upgrade your plan before creating another voice. On-Demand accounts also need a payment method on file. See Plan limits for each plan's slot and training allowances.
For recording and preparation tips, see Voice Cloning best practices.
Authorizationstringrequired
Your API key. 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: inworld workspace add-key.
displayNamestringrequired
The human-readable name shown anywhere the voice is listed or selected. The voice's pvcVoiceId is derived from this value; renaming the voice later does not change its pvcVoiceId.
languageCodestring
The voice's language as a BCP-47-style locale string, such as en-US. Send this or langCode; if you send both, they must name the same language. Multi-language support is experimental; defaults to en-US if both are omitted. Immutable after creation.
langCodeenum<string>
Legacy enum form of the language, such as EN_US. Send this or languageCode, not a different language in each.
Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL
descriptionstring
Description of the voice.
tagsstring[]
User-defined tags.
namestring
Resource name. Format: workspaces/{workspace}/pvcVoices/{voice}.
pvcVoiceIdstring
PVC voice ID, derived from displayName at creation time. Use this value as {pvcVoiceId} on every other PVC endpoint. It is not the voice ID used for synthesis; see customVoice.
displayNamestring
The human-readable name shown anywhere the voice is listed or selected.
descriptionstring
Description of the voice.
tagsstring[]
User-defined tags.
langCodeenum<string>
Legacy enum form of the voice's language, such as EN_US. Returned alongside languageCode. Immutable after creation.
Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL
languageCodestring
The voice's language as a BCP-47-shaped locale string, e.g. en-US. Immutable after creation.
stateenum<string>
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. It's permanent and 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 toPVC_VOICE_STATE_DRAFTwith its remaining samples intact.
Available options:PVC_VOICE_STATE_UNSPECIFIEDPVC_VOICE_STATE_DRAFTPVC_VOICE_STATE_QUEUEDPVC_VOICE_STATE_TRAININGPVC_VOICE_STATE_READYPVC_VOICE_STATE_FAILED
failureobject
Populated on a PVC voice when its state is PVC_VOICE_STATE_FAILED.
Show child attributes
reasonstring
Machine-readable failure code, such as PVC_VOICE_FAILURE_REASON_INVALID_SAMPLES. 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.
messagestring
Human-readable, scrubbed failure message. Never contains uploaded audio, filenames, or transcripts.
customVoicestring
Resource name of the trained voice, in the format workspaces/{workspace}/voices/{voice}. Set once the voice is PVC_VOICE_STATE_READY. Manage and use the trained voice through the Voices API.
samplesobject[]
Audio samples currently attached to the voice.
Show child attributes
sampleIdstring
Sample ID. Use this value as {sampleId} when trimming or deleting the sample.
namestring
Resource name. Format: workspaces/{workspace}/pvcVoices/{voice}/samples/{sample}.
fileNamestring
Original file name of the uploaded audio.
sizeBytesstring
Size of the uploaded file, in bytes. Encoded as a string, like other 64-bit integers in this API.
durationSecsnumber
Analyzed duration of the sample, in seconds, before any trim is applied.
mimeTypeenum<string>
Detected audio format, sniffed from the file's byte content.
Available options:audio/wavaudio/webmaudio/mpeg
hashstring
Base64-encoded MD5 of the stored object, for verifying upload integrity against the source file.
removeBackgroundNoiseboolean
Whether background-noise removal is applied to this sample during training, as set by remove_background_noise on upload.
trimStartMsinteger
Trim start offset in milliseconds, if set.
trimEndMsinteger
Trim end offset in milliseconds, if set.
roleenum<string>
How the sample is used in training. PVC_SAMPLE_ROLE_UNSPECIFIED is treated as PVC_SAMPLE_ROLE_TRAINING (ordinary training material). PVC_SAMPLE_ROLE_GOLDEN marks a positive reference whose character training should prefer; PVC_SAMPLE_ROLE_AVOID marks an advisory negative reference. New values may be added over time.
Available options:PVC_SAMPLE_ROLE_UNSPECIFIEDPVC_SAMPLE_ROLE_TRAININGPVC_SAMPLE_ROLE_GOLDENPVC_SAMPLE_ROLE_AVOID
createTimestring
updateTimestring