Skip to navigation
HeyReach APIVoice

CreateCustomVoice

View as Markdown

Clone a custom voice from a recorded or uploaded audio sample of 15–30 seconds, sent as a multipart file part whose own Content-Type is the audio’s MIME type (audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/mp4, audio/m4a, audio/x-m4a, audio/ogg, audio/webm, audio/aac or audio/flac). The file may be at most 25 MiB; a request body over 26 MiB is refused with a bare 413.

When the sample raises soft warnings, the call returns 200 with a null voice and the warnings; re-submit the same audio with ignoreSoftWarnings = true to clone anyway.

Pass a clientRequestId: one GUID per recording, reused for the re-submit and for any retry. A token that already produced a voice returns that voice, because a clone can outlive the caller’s timeout.

Errors

  • 400 VOICE_AUDIO_MISSING, VOICE_AUDIO_TOO_LARGE, VOICE_AUDIO_UNSUPPORTED, VOICE_AUDIO_DURATION_OUT_OF_RANGE, VOICE_AUDIO_UNINTELLIGIBLE or CLIENT_REQUEST_ID_CONFLICT: change the request.
  • 403 NO_ACTIVE_SUBSCRIPTION or VOICE_NOTES_NOT_ENABLED.
  • 404 CUSTOM_VOICE_NOT_FOUND: the voice was deleted while it was being created.
  • 502 VOICE_PROVIDER_UNAVAILABLE, and 503 VOICE_ENGINE_BUSY, VOICE_TRANSCRIPTION_UNAVAILABLE or VOICE_AUDIO_PROCESSING_UNAVAILABLE: transient, so retry with the same clientRequestId.

Headers

X-API-KEYstringOptional

API key header using this scheme. Example: “X-API-KEY: {API_KEY}”

Request

This endpoint expects a multipart form containing a file.
filefileRequired

The audio sample, 15–30 seconds, at most 25 MiB. The part’s own Content-Type must be the audio’s MIME type.

namestringOptional
genderenumOptional
Defaults to MALE.
Allowed values:
sourceenumOptional
Defaults to RECORDED.
Allowed values:
ignoreSoftWarningsbooleanOptional
Set to true to clone despite the soft warnings a previous call returned for the same audio.
clientRequestIdstringOptionalformat: "uuid"

One GUID per recording, reused for the re-submit and for any retry.

consentConfirmedbooleanOptional

Optional; not required through the API.

Response

OK
voicemap from strings to any or null

The cloned voice, in the shape of a GetVoices item. Null when the sample raised soft warnings and ignoreSoftWarnings was not set.

warningslist of objects

Soft findings on the sample: SCRIPT_MISMATCH or LOW_QUALITY.

Errors

400
Create Custom Voice Voice Request Bad Request Error
403
Create Custom Voice Voice Request Forbidden Error
404
Create Custom Voice Voice Request Not Found Error
502
Create Custom Voice Voice Request Bad Gateway Error
503
Create Custom Voice Voice Request Service Unavailable Error