> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`).
The response's `samples` array lists every sample currently attached to the voice. Each entry includes a `sampleId` you can use to [trim](https://docs.inworld.ai/api-reference/pvcAPI/pvcvoiceservice/trim-pvc-voice-sample.md) or [delete](https://docs.inworld.ai/api-reference/pvcAPI/pvcvoiceservice/delete-pvc-voice-sample.md) the sample.
**Polling for training completion.** A reasonable polling interval is 15-30 seconds. If `state` reaches `PVC_VOICE_STATE_FAILED`, read `failure.message` for a scrubbed description of what went wrong.
A `404` means the voice doesn't exist or belongs to a different workspace than the one resolved from your API key. The response deliberately does not distinguish these cases.
## API reference
**Endpoint:** `GET https://api.inworld.ai/voices/v1/pvcVoices/{pvcVoiceId}`
### Authorization
- `Authorization` (string; required) — 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](../../../developer-tools/inworld-cli): `inworld workspace add-key`.
### Path parameters
- `pvcVoiceId` (string; required) — `pvcVoiceId` of the PVC voice to get.
### Response
Status: `200`. Content type: `application/json`.
- `name` (string) — Resource name. Format: `workspaces/{workspace}/pvcVoices/{voice}`.
- `pvcVoiceId` (string) — 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`.
- `displayName` (string) — The human-readable name shown anywhere the voice is listed or selected.
- `description` (string) — Description of the voice.
- `tags` (string[]) — User-defined tags.
- `langCode` (enum; options: "EN_US", "ZH_CN", "KO_KR", "JA_JP", "RU_RU", "AUTO", "IT_IT", "ES_ES", "PT_BR", "DE_DE", "FR_FR", "AR_SA", "PL_PL", "NL_NL", "HI_IN", "HE_IL") — Legacy enum form of the voice's language, such as `EN_US`. Returned alongside `languageCode`. Immutable after creation.
- `languageCode` (string) — The voice's language as a BCP-47-shaped locale string, e.g. `en-US`. Immutable after creation.
- `state` (enum; options: "PVC_VOICE_STATE_UNSPECIFIED", "PVC_VOICE_STATE_DRAFT", "PVC_VOICE_STATE_QUEUED", "PVC_VOICE_STATE_TRAINING", "PVC_VOICE_STATE_READY", "PVC_VOICE_STATE_FAILED") — 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.
- `failure` (object) — Populated on a PVC voice when its `state` is `PVC_VOICE_STATE_FAILED`.
- `reason` (string) — 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.
- `message` (string) — Human-readable, scrubbed failure message. Never contains uploaded audio, filenames, or transcripts.
- `customVoice` (string) — 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.
- `samples` (object[]) — Audio samples currently attached to the voice.
- `sampleId` (string) — Sample ID. Use this value as `{sampleId}` when trimming or deleting the sample.
- `name` (string) — Resource name. Format: `workspaces/{workspace}/pvcVoices/{voice}/samples/{sample}`.
- `fileName` (string) — Original file name of the uploaded audio.
- `sizeBytes` (string) — Size of the uploaded file, in bytes. Encoded as a string, like other 64-bit integers in this API.
- `durationSecs` (number) — Analyzed duration of the sample, in seconds, before any trim is applied.
- `mimeType` (enum; options: "audio/wav", "audio/webm", "audio/mpeg") — Detected audio format, sniffed from the file's byte content.
- `hash` (string) — Base64-encoded MD5 of the stored object, for verifying upload integrity against the source file.
- `removeBackgroundNoise` (boolean) — Whether background-noise removal is applied to this sample during training, as set by `remove_background_noise` on upload.
- `trimStartMs` (integer) — Trim start offset in milliseconds, if set.
- `trimEndMs` (integer) — Trim end offset in milliseconds, if set.
- `role` (enum; options: "PVC_SAMPLE_ROLE_UNSPECIFIED", "PVC_SAMPLE_ROLE_TRAINING", "PVC_SAMPLE_ROLE_GOLDEN", "PVC_SAMPLE_ROLE_AVOID") — 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.
- `createTime` (string)
- `updateTime` (string)
### Response examples
#### 200: training_voice
```json
{
"name": "workspaces/your_workspace_id/pvcVoices/my-professional-voice",
"pvcVoiceId": "my-professional-voice",
"displayName": "my-professional-voice",
"langCode": "EN_US",
"languageCode": "en-US",
"state": "PVC_VOICE_STATE_TRAINING",
"samples": [
{
"sampleId": "s_9f1c2e",
"name": "workspaces/your_workspace_id/pvcVoices/my-professional-voice/samples/s_9f1c2e",
"fileName": "sample-01.wav",
"sizeBytes": "24883220",
"durationSecs": 312.4,
"mimeType": "audio/wav",
"hash": "",
"removeBackgroundNoise": false,
"role": "PVC_SAMPLE_ROLE_UNSPECIFIED"
}
],
"createTime": "2026-08-31T12:00:00Z",
"updateTime": "2026-08-31T12:15:00Z"
}
```
#### 200: failed_voice
```json
{
"name": "workspaces/your_workspace_id/pvcVoices/my-professional-voice",
"pvcVoiceId": "my-professional-voice",
"displayName": "my-professional-voice",
"langCode": "EN_US",
"languageCode": "en-US",
"state": "PVC_VOICE_STATE_FAILED",
"failure": {
"reason": "PVC_VOICE_FAILURE_REASON_INTERNAL",
"message": "PVC voice training failed"
},
"samples": [],
"createTime": "2026-08-31T12:00:00Z",
"updateTime": "2026-08-31T12:24:00Z"
}
```
#### 404: not_found
```json
{
"code": 5,
"message": "PVC voice has not been found",
"details": []
}
```
#### default: default_response
```json
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
```
### Code examples
#### cURL
```bash
curl --location 'https://api.inworld.ai/voices/v1/pvcVoices/' \
--header "Authorization: Basic $INWORLD_API_KEY"
```
#### Python
```python
import requests
pvc_voice_id = ""
url = f"https://api.inworld.ai/voices/v1/pvcVoices/{pvc_voice_id}"
headers = {"Authorization": "Basic "}
response = requests.get(url, headers=headers)
print(response.json())
```
#### JavaScript
```javascript
const pvcVoiceId = '';
const url = `https://api.inworld.ai/voices/v1/pvcVoices/${pvcVoiceId}`;
const response = await fetch(url, {
headers: { 'Authorization': 'Basic ' },
});
const data = await response.json();
console.log(data);
```