Voice Cloning API

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

List public and cloned voices

The list response has two groups: public_voices and my_voices. Each voice includes a machine-readable BCP 47 locale, a human-readable language, and structured provider, gender, age, accent, and use_cases fields plus a preview URL. The legacy tags field remains available for compatibility.

Filter the public library by locale and provider, then paginate with limit and the returned next_cursor. A base locale such as es matches every Spanish regional variant; a full locale such as es-MX, en-GB, zh-TW, or zh-HK matches that region:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \
  "https://openapi.visionstory.ai/api/v1/voices?locale=es-MX&provider=minimax&limit=50"

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,
    params={"locale": "es-MX", "provider": "minimax", "limit": 50},
    timeout=10,
)
resp_data = response.json()
print(len(resp_data["data"]["public_voices"]))
print(len(resp_data["data"]["my_voices"]))
print(resp_data["data"]["next_cursor"])

Without limit, the endpoint keeps the original behavior and returns the complete filtered library. During pagination, my_voices appears on the first page only. locale and provider matching is case-insensitive. Always use a returned voice_id instead of inventing 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:

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:

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
voice = response.json()["data"]
print(voice["voice_id"], voice["locale"], voice["gender"], voice["preview_audio_url"])

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:

{
  "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:

{
  "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:

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

Related VisionStory API guides

• Avatars — the character that speaks with your voice.
• Quick start — generate your first video.
• Text to Speech — steer multilingual pronunciation with locale.
• API reference — full request and response schemas.