Text-to-Speech API

The VisionStory Text-to-Speech API converts text into natural MP3 audio with any public or cloned voice. The request is synchronous: a successful response returns the generated audio bytes directly.

Beta access. This endpoint is allowlisted during beta. If a request returns 403 / not enabled, contact your VisionStory representative. An active subscription is required.

Text-to-speech API endpoint

Method	Path	What it does
`POST`	`/api/v1/tts`	Synthesize speech from text; returns MP3 audio

Generate MP3 speech from text

Send text and a voice_id (from GET /api/v1/voices — a public or your own cloned voice). The service automatically picks the best synthesis strategy for the voice and the text language.

Shell

curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"text": "Hello from VisionStory.", "voice_id": "YOUR_VOICE_ID"}' https://openapi.visionstory.ai/api/v1/tts --output speech.mp3

The response body is the raw MP3 (audio/mpeg, 44.1 kHz). Usage and billing come back in response headers, not the body:

Header	Meaning
`X-Audio-Duration-Sec`	Length of the generated audio, in seconds
`X-Usage-Characters`	Characters billed
`X-Cost-Credit`	Credits charged for this call

Python

import requests, os

resp = requests.post(
    "https://openapi.visionstory.ai/api/v1/tts",
    headers={"X-API-Key": os.environ["VISIONSTORY_API_KEY"]},
    json={"text": "Hello from VisionStory.", "voice_id": "YOUR_VOICE_ID"},
    timeout=240,
)
resp.raise_for_status()
with open("speech.mp3", "wb") as f:
    f.write(resp.content)
print("credits charged:", resp.headers.get("X-Cost-Credit"))

Billing, limits, and storage

Synchronous & not stored. The audio is returned inline and is not saved on our side — persist the bytes yourself; a repeat call regenerates and bills again.
Billing: 2 credits per 1,000 characters (rounded up), charged only on success. There is no free allowance.
Character limit: long text is supported up to a per-request cap; exceeding it returns 400.
Concurrency: synchronous generation is capped at a few concurrent requests per key during beta; excess requests are rejected rather than queued.

Voices — pick or clone the voice_id to speak with.
API reference — full request schema and error codes.