Realtime TTS-2 is live. Built for realtime conversation that feels human. Learn more

PvcVoiceService

Update a PVC voice

Updates editable metadata on a PVC voice. Editing a PVC_VOICE_STATE_FAILED voice returns it to PVC_VOICE_STATE_DRAFT and preserves its samples, so you can fix the issue and retrain. A voice that is queued, training, or ready cannot be updated. Retry after it finishes, or after re-editing brings a failed voice back to draft.

PATCH/voices/v1/pvcVoices/{voiceId}

Currently, displayName is the only editable field. The updateMask query parameter is required and uses snake_case field paths (for example: ?updateMask=display_name) — an empty or missing mask returns 400.

Editing a failed voice. Add or remove samples and retrain without re-uploading everything.

Returns 409 while the voice is queued, training, or ready.

Authorizations

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.

Path Parameters

voiceIdstringrequired

Voice ID of the PVC voice to update.

Query Parameters

updateMaskstringrequired

Comma-separated list of fields to update. Required. An empty or missing mask returns 400. Fields present in the body but omitted from the mask are ignored.

Mask paths use snake_case field names, even though the request body uses camelCase. Supported paths: display_name.

Body

application/json

displayNamestring

The voice's new display name. Include display_name (snake_case) in updateMask to apply this field.

Response

200 - application/json

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 to PVC_VOICE_STATE_DRAFT with 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