PvcVoiceService
Get a PVC voice
Reads a Professional Voice Clone's current state, including its uploaded samples. Poll this endpoint after starting training to watch a voice move from PVC_VOICE_STATE_QUEUED through PVC_VOICE_STATE_TRAINING to PVC_VOICE_STATE_READY (or PVC_VOICE_STATE_FAILED).
/voices/v1/pvcVoices/{voiceId}The response's samples array lists every sample currently attached to the voice, including each sample's sampleId — use it to trim or delete that sample.
Polling for training completion. A reasonable poll interval is every 15-30 seconds. If state lands on PVC_VOICE_STATE_FAILED, the failure.message field has a scrubbed description of what went wrong.
A 404 from this endpoint means either the voice doesn't exist, or it belongs to a different workspace than the one resolved from your API key — the two cases are deliberately indistinguishable.
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.
voiceIdstringrequired
Voice ID of the PVC voice to get.
namestring
Resource name. Format: workspaces/{workspace}/pvcVoices/{voice}.
voiceIdstring
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.
displayNamestring
The human-readable name shown anywhere the voice is listed or selected.
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, 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.
messagestring
Human-readable, scrubbed failure message. Never contains uploaded audio, filenames, or transcripts.
incarnationIdstring
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.
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}.
sizeBytesinteger
Size of the uploaded file, in bytes.
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.
trimStartMsinteger
Trim start offset in milliseconds, if set.
trimEndMsinteger
Trim end offset in milliseconds, if set.
createTimestring
updateTimestring