Voices

A voice is the voice_id that turns your text into speech inside a video. Use a voice from the public library, or clone a voice from an audio sample and make every video speak with it.

Endpoints

List voices

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

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

import requests

headers = {"X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx"}
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"]))

Each voice carries structured fields — locale (BCP 47, e.g. en-US / en-GB / zh-TW / zh-HK), language, provider (elevenlabs / seed / gemini / minimax), gender, age, accent, and use_cases — so you can pick by more than name. locale uses the same values as the locale parameter of POST /api/v1/tts, so what you filter by is what you can pin at synthesis time.

Filter and paginate. The public library holds 1000+ voices. Narrow it with locale and/or provider (both case-insensitive), and page the rest with limit plus the returned next_cursor (passed back as cursor). Without limit the full list comes back in one response. A bare language code matches every regional variant (es → Spain, Mexico, Latin America…); add the region to pin one (es-MX). Prompt-driven gemini voices have no fixed locale, so list them with provider=gemini instead.

# British English voices, first 20
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \
  "https://openapi.visionstory.ai/api/v1/voices?locale=en-GB&limit=20"

# Cantonese voices from the minimax engine
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \
  "https://openapi.visionstory.ai/api/v1/voices?locale=zh-HK&provider=minimax"

my_voices is returned in full on the first page (cursor=0) and is subject to the same filters.

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

Clone a voice

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 requests
import base64

headers = {"X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx"}

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 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": "4321918387609092991",
  "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": "4321918387609092991",
  "audio_script": { "audio_url": "https://your.site/narration.mp3", "voice_change": true, "voice_id": "YOUR_VOICE_ID", "denoise": true }
}

Delete a cloned 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"

Next steps

• Avatars — the character that speaks with your voice.
• Quick start — generate your first video.
• API reference — full request and response schemas.