VisionStory Docs
llms.txt Get API key

Voices

View as MarkdownOpen in ClaudeOpen in ChatGPT

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

Method Path What it does
GET /api/v1/voices List public voices and your cloned voices
POST /api/v1/voice Clone a voice from an audio sample
DELETE /api/v1/voice Delete one of your cloned voices

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"]))

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