terminalDevelopers

API Reference

Generate speech programmatically with your secret key.

keyGet your API key

keyAuthentication

Every request is authenticated with a secret API key sent as a Bearer token. Generate and manage your key in Settings → API access.

Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxx
warningKeep your key secret — it grants full access to your account. If it leaks, regenerate it from Settings.

linkBase URL

https://velluto.io/api/v1

speedRate limits

Limits are per plan, counted per UTC day. A request counts as ceil(characters / 5,000) toward your daily limit — so a 40,000-character text uses 8 of your 1,000 requests/day. The API is available on paid plans only.

PlanAPI accessRequests / day
FreelockNo access—
PersonallockNo access—
Procheck_circleIncluded1 000
Custom Voicecheck_circleIncluded1 000

graphic_eqGenerate speech

POST/api/v1/tts

Submit text and a voice; the API returns an MP3. Send up to 100,000 characters in a single request — long text is automatically split into blocks and stitched into ONE audio file (you do not split it yourself). Voices and their IDs are the ones in your Studio library.

Body parameters

voice_idstring· required

Voice ID (see your library / Studio).

textstring· required

The text to synthesize. Up to 100,000 characters per request — automatically split into blocks and combined into one MP3. Counts as ceil(characters / 5,000) requests.

modelstring· optional

"ru" (Russian) or "multilang". Defaults to the voice language.

formatstring· optional

Output format: "mp3" (default).

Example request

curl -X POST https://velluto.io/api/v1/tts \
  -H "Authorization: Bearer vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "luna",
    "text": "Hello from Velluto.",
    "model": "multilang"
  }' --output speech.mp3

Response

Small requests (≤ 5,000 chars) return the MP3 inline (Content-Type: audio/mpeg). Larger requests are processed asynchronously: you get 202 JSON { "status": "processing", "generation_id": "…", "poll_url": "/api/v1/tts/<id>" } — poll that URL with GET and the same Bearer key until it returns the audio (202 while running, 200 audio/mpeg when ready). On error the API returns JSON:

{
  "error": "api_not_in_plan",
  "detail": "Your plan does not include API access."
}

errorErrors

401Missing or invalid API key.
403Your plan does not include API access.
429Daily request limit reached (a request costs ceil(chars / 5,000)) — try again tomorrow or upgrade.
info

Keep your secret key safe — it grants full access to your account. Need higher limits or a dedicated voice? Get in touch and we’ll set you up.

keyGet your API key