Create Speech — VisionStory API

Convert text to speech with VisionStory smart TTS. Pick a voice from GET /api/v1/voices (public or your cloned voices). The service automatically selects the best synthesis strategy for the voice and the text language. Billing: 2 credits per 1000 characters (rounded up), only charged on success.

Synchronous — the response body is the MP3 audio itself (audio/mpeg). Duration and billing are returned in the X-Audio-Duration-Sec, X-Usage-Characters and X-Cost-Credit headers. The audio is not stored on our side, so save the response body; a repeat call regenerates and bills again. Per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Request body

application/jsonrequired

localestring | nullnullable

Optional BCP 47 locale (e.g. en-GB, zh-TW) steering pronunciation and accent for multilingual voices, applied best-effort per voice engine. Defaults to the voice's native locale.

speech_ratestring | nullnullable

Relative speaking pace: slow / normal / fast; defaults to normal. Same vocabulary as text_script.speech_rate in POST /api/v1/video. Applied by the voice engine where it supports pacing natively, otherwise by a ~10% time-stretch of the audio (pitch preserved); the exact duration change varies by voice, so read X-Audio-Duration-Sec.

Values: slownormalfast

textstringrequired

Text to synthesize, up to 3000 characters

voice_idstringrequired

Public or cloned voice id, check GET /api/v1/voices

Responses

200MP3 audio (44.1kHz). Usage metadata is returned in response headers. The example text is a binary-body placeholder, not playable audio or JSON.

audio/mpeg

Headers

X-Audio-Duration-Secnumber

Actual generated duration in seconds.

X-Audio-Idstring

Identifier of the generated audio.

X-Cost-Creditinteger

Credits charged. This example is illustrative, not a quote.

X-Usage-Charactersinteger

Number of characters billed.

defaultError response. All failures share one envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (useful for AI agents).

application/json

errorErrorDetailrequired

codeintegerrequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

detailsstring | nullnullable

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullnullable

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.