PvcVoiceService
Upload PVC voice samples
Upload audio samples to a draft professional voice clone (PVC). Each request is all-or-nothing: if one file is rejected, none are saved.
/voices/v1/pvcVoices/{pvcVoiceId}/samplesYou can upload samples in several requests. They accumulate on the voice until you train it.
If an upload is rejected, for example because a file's format is unsupported or it is too large, the entire batch is dropped, including valid files. Split the batch and retry with only the accepted files.
The API detects the format from the file's bytes, not its declared MIME type or extension. Renaming a file to .wav does not make it a WAV file.
Accepted audio
| Format | Notes |
|---|---|
| WAV | PCM (8/16/24/32-bit), 32-bit float, or WAVE_FORMAT_EXTENSIBLE |
| MP3 | — |
| WEBM | Must include a Duration element in its metadata |
Rejected: A-law WAV, 12-bit WAV, .m4a, zero-byte files, truncated WAV files, and WEBM files missing Duration metadata.
Limits
| Limit | Value |
|---|---|
| Files per request | 10 |
| Size per file | 1 GB |
| Combined sample storage per voice | 1 GB (1,000,000,000 bytes) |
| Samples per voice | 50 |
| Concurrent uploads per account | plan-dependent |
Exceeding a per-request, per-file, or per-voice limit returns HTTP error code 400. Too many concurrent uploads returns 429.
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.
pvcVoiceIdstringrequired
pvcVoiceId of the draft PVC voice to add samples to.
files[]string[]required
Audio files to upload, up to 10 per request. Repeat the files[] form field once per file (e.g. files[]=@"sample-01.wav", files[]=@"sample-02.wav"). It is not a single field containing a list. Accepted formats: WAV, WEBM, MP3. The actual byte content is sniffed to determine format, not the declared MIME type or file extension. Each file is capped at 1,000,000,000 bytes (1 GB); the voice's combined sample storage is capped at 1,000,000,000 bytes (1 GB) and 50 samples total.
remove_background_noiseboolean
Whether to run an audio isolation model over the uploaded samples to remove background noise before training. Can degrade quality on already-clean recordings. Defaults to false.
samplesobject[]
The samples accepted by this request, in the order they were uploaded.
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