curl --location --request PATCH 'https://api.inworld.ai/voices/v1/pvcVoices/<voice-id>?updateMask=display_name' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"displayName": "renamed-professional-voice"
}'import requests
voice_id = "<voice-id>"
url = f"https://api.inworld.ai/voices/v1/pvcVoices/{voice_id}"
headers = {
"Authorization": "Basic <api-key>",
"Content-Type": "application/json"
}
params = {"updateMask": "display_name"}
payload = {"displayName": "renamed-professional-voice"}
response = requests.patch(url, headers=headers, params=params, json=payload)
print(response.json())const voiceId = '<voice-id>';
const url = `https://api.inworld.ai/voices/v1/pvcVoices/${voiceId}?updateMask=display_name`;
const response = await fetch(url, {
method: 'PATCH',
headers: {
'Authorization': 'Basic <api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({ displayName: 'renamed-professional-voice' }),
});
const data = await response.json();
console.log(data);{
"name": "<string>",
"voiceId": "<string>",
"displayName": "<string>",
"languageCode": "<string>",
"state": "PVC_VOICE_STATE_UNSPECIFIED",
"failure": {
"reason": "<string>",
"message": "<string>"
},
"incarnationId": "<string>",
"samples": [
{
"sampleId": "<string>",
"name": "<string>",
"sizeBytes": 123,
"durationSecs": 123,
"mimeType": "audio/wav",
"hash": "<string>",
"trimStartMs": 123,
"trimEndMs": 123
}
],
"createTime": "2023-11-07T05:31:56Z",
"updateTime": "2023-11-07T05:31:56Z"
}{
"code": 3,
"message": "invalid request: updateMask must not be empty",
"details": []
}{
"code": 9,
"message": "pvc voice 'my-professional-voice' cannot be modified while in state PVC_VOICE_STATE_TRAINING",
"details": []
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}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.
curl --location --request PATCH 'https://api.inworld.ai/voices/v1/pvcVoices/<voice-id>?updateMask=display_name' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"displayName": "renamed-professional-voice"
}'import requests
voice_id = "<voice-id>"
url = f"https://api.inworld.ai/voices/v1/pvcVoices/{voice_id}"
headers = {
"Authorization": "Basic <api-key>",
"Content-Type": "application/json"
}
params = {"updateMask": "display_name"}
payload = {"displayName": "renamed-professional-voice"}
response = requests.patch(url, headers=headers, params=params, json=payload)
print(response.json())const voiceId = '<voice-id>';
const url = `https://api.inworld.ai/voices/v1/pvcVoices/${voiceId}?updateMask=display_name`;
const response = await fetch(url, {
method: 'PATCH',
headers: {
'Authorization': 'Basic <api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({ displayName: 'renamed-professional-voice' }),
});
const data = await response.json();
console.log(data);{
"name": "<string>",
"voiceId": "<string>",
"displayName": "<string>",
"languageCode": "<string>",
"state": "PVC_VOICE_STATE_UNSPECIFIED",
"failure": {
"reason": "<string>",
"message": "<string>"
},
"incarnationId": "<string>",
"samples": [
{
"sampleId": "<string>",
"name": "<string>",
"sizeBytes": 123,
"durationSecs": 123,
"mimeType": "audio/wav",
"hash": "<string>",
"trimStartMs": 123,
"trimEndMs": 123
}
],
"createTime": "2023-11-07T05:31:56Z",
"updateTime": "2023-11-07T05:31:56Z"
}{
"code": 3,
"message": "invalid request: updateMask must not be empty",
"details": []
}{
"code": 9,
"message": "pvc voice 'my-professional-voice' cannot be modified while in state PVC_VOICE_STATE_TRAINING",
"details": []
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}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.
PVC_VOICE_STATE_FAILED returns it to PVC_VOICE_STATE_DRAFT and preserves its existing samples, so you can add or remove samples and retrain without re-uploading everything.409 until the voice finishes (or, for a failed voice, until you next edit it).Authorizations
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
Voice ID of the PVC voice to update.
Query Parameters
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.
"display_name"
Body
Request message for UpdatePvcVoice. updateMask is required.
The voice's new display name. Include display_name (snake_case) in updateMask to apply this field.
Response
A successful response.
A Professional Voice Clone resource.
Resource name. Format: workspaces/{workspace}/pvcVoices/{voice}.
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.
The human-readable name shown anywhere the voice is listed or selected.
The voice's language as a BCP-47-shaped locale string, e.g. en-US. Immutable after creation.
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 toPVC_VOICE_STATE_DRAFTwith its remaining samples intact.
PVC_VOICE_STATE_UNSPECIFIED, PVC_VOICE_STATE_DRAFT, PVC_VOICE_STATE_QUEUED, PVC_VOICE_STATE_TRAINING, PVC_VOICE_STATE_READY, PVC_VOICE_STATE_FAILED Populated on a PVC voice when its state is PVC_VOICE_STATE_FAILED.
Show child attributes
Show child attributes
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.
Audio samples currently attached to the voice.
Show child attributes
Show child attributes