Search VisionStory documentation

No documentation matched “”.

Try a feature or resource name such as , , or .

VisionStoryDevelopers
Get API key

Guide

Voice Cloning API

List public voices, clone a custom AI voice from an audio sample, and use its voice_id for text-to-speech or talking avatar video generation.

The VisionStory Voice Cloning API turns an audio sample into a reusable voice_id. Choose a public voice or clone your own, then use it for text-to-speech and lip-synced talking-avatar video generation.

Voice cloning API endpoints

MethodPathWhat it does
GET/api/v1/voicesList public voices and your cloned voices
POST/api/v1/voiceClone a voice from an audio sample
DELETE/api/v1/voiceDelete one of your cloned voices

List public and cloned voices

The list response has two groups: public_voices (ready to use, like Alice) and my_voices (cloned by you):

Shell
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/voices
Python
import os
import requests

headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
response = requests.get("https://openapi.visionstory.ai/api/v1/voices", headers=headers, timeout=10)
resp_data = response.json()
print(len(resp_data["data"]["public_voices"]))
print(len(resp_data["data"]["my_voices"]))

Always use a voice_id returned by this endpoint — never invent one.

Clone an AI voice from audio

Send an audio sample of the voice, get back a voice_id. Provide the audio as either a public HTTPS URL or base64 inline_data — exactly one of the two. The optional preview_text is synthesized with the new voice so you can hear the result immediately. The request is synchronous and takes about 15 seconds:

Shell
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"audio_url": "https://your.site/sample.mp3", "preview_text": "How are you doing guys, this is my voice"}' https://openapi.visionstory.ai/api/v1/voice

With a local file, base64-encode it into inline_data:

Python
import base64
import os
import requests

headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}

with open("/path/to/audio.mp3", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "inline_data": {"mime_type": "audio/mp3", "data": encoded},
    "preview_text": "How are you doing guys, this is my voice"
}
response = requests.post("https://openapi.visionstory.ai/api/v1/voice", json=payload, headers=headers)  # takes ~15 s
print(response.json()["data"]["voice_id"])

Sample requirements: provide a clean recording of a single speaker. Supported formats are AVI, MP3, MP4, M4A, and WAV, up to 30 MB. How many cloned voices you can keep at once depends on your subscription plan.

Use a cloned voice in a video

Two places a voice applies when creating a video:

Text script — the voice reads your text:

JSON
{
  "model_id": "vs_character_v4",
  "avatar_id": "YOUR_AVATAR_ID",
  "text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID", "speech_rate": "normal" }
}

Audio script with voice change — you supply the audio, and voice_change: true re-voices it with the selected voice_id:

JSON
{
  "model_id": "vs_character_v4",
  "avatar_id": "YOUR_AVATAR_ID",
  "audio_script": { "audio_url": "https://your.site/narration.mp3", "voice_change": true, "voice_id": "YOUR_VOICE_ID", "denoise": true }
}

Delete a custom voice

Deleting only affects your own cloned voices; videos already generated with it are unaffected:

Shell
curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/voice?voice_id=YOUR_VOICE_ID"