Clone voice — VisionStory API

Clone a voice from a clean audio sample (AVI/MP3/MP4/M4A/WAV, up to 30MB) and get a reusable voice_id. Cloning runs synchronously and can take a while, so set a generous request timeout. The number of active cloned voices allowed depends on your plan.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Request body

application/jsonrequired

audio_urlstring | nullnullable

Publicly reachable URL of a clean voice sample. Provide either this or inline_data. Formats: AVI/MP3/MP4/M4A/WAV, up to 30MB.

inline_dataInlineDataModel | nullnullable

Voice sample as inline base64 data. Provide either this or audio_url.

datastringrequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

mime_typestringrequired

MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

preview_textstring | nullnullable

Text spoken in the generated preview clip for the cloned voice. Defaults to a built-in phrase. Max 100 characters.

Responses

200Successful Response

application/json

dataCloneVoiceResponse | nullrequirednullable

The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete.

voice_idstringrequired

Unique identifier of the cloned voice. Pass it as voice_id in a text script to speak with this voice.

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-side timestamp when the response was produced, in ISO 8601 format (UTC).

defaultError response. All failures share one envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (useful for AI agents).

application/json

errorErrorDetailrequired

codeintegerrequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

detailsstring | nullnullable

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullnullable

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.