API Reference

Text to speech

Narration on its own, without a video. This is the AI voice generator from the app behind an endpoint, so a script read here sounds the same as one read in a video.

POST/v1/text-to-speech

Speak a script

Speaks the text and returns an mp3 url. The audio is generated while the request is open, so expect a few seconds per sentence rather than an immediate answer.

Body

textrequired

string

What to say, up to 5000 characters. Longer scripts have to be split and stitched on your side.

voiceId

string

ElevenLabs voice to narrate with. Left out, the script is read by Adam, the same voice the video templates fall back to. List the ids with Voices.

default: pNInz6obpgDQGcFmaJgB

voiceStyle

object

Fine tunes the narration. Every field is a percentage, matching the voice sliders in the editor. Pass only the ones you want to change, see voiceStyle fields.

voiceStyle fields

voiceStyle.stability

number, 0 to 100

Lower values let the voice vary more between takes, higher values keep it flat and predictable.

default: 38

voiceStyle.similarityBoost

number, 0 to 100

How closely the output sticks to the original voice.

default: 75

voiceStyle.style

number, 0 to 100

Style exaggeration. Higher values push the delivery harder, at some cost to stability.

default: 0

voiceStyle.speed

number, 70 to 120

Speaking rate as a percentage of the voice’s natural pace.

default: 100

Response fields

urlrequired

string

Where the mp3 lives. No authentication needed, so it can be handed straight to a player or downloaded.

idrequired

string

Id of the audio in your workspace library, where it also shows up under the AI voice generator.

charactersrequired

number

How many characters were spoken, which is what the credits are based on.

expiresAtrequired

string

When the url stops resolving. Copy the mp3 to your own storage if you need it for longer.

Request

curl -X POST "https://api.vsub.io/v1/text-to-speech" \
  -H "Authorization: Bearer vp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Three things nobody tells you about your first year of freelancing.",
    "voiceId": "pNInz6obpgDQGcFmaJgB",
    "voiceStyle": { "speed": 105 }
  }'

Response 200

{
  "id": "8f0a1e52-3f4b-4f0e-9c7a-1d5b6e2c9a10",
  "url": "https://files.vsub.io/expire-30-ai-voice-8f0a1e52-3f4b-4f0e-9c7a-1d5b6e2c9a10.mp3",
  "characters": 66,
  "expiresAt": "2026-09-06T09:12:44.000Z"
}

Speaking costs 100 credits per 1000 characters, charged once the audio is stored, and the request fails with a 400 when the workspace has no credits left. The mp3 stays available for 30 days.

Voice ids come from Voices. To narrate a whole video instead, every template takes the same voiceId and voiceStyle fields.