Skip to content
Vidsly
Developer APIRESTMP3

AI narration, one POST away.

A plain REST text-to-speech endpoint — 51 voices, including 13 multilingual OpenAI voices, MP3 out. Pay per character from your plan's credit balance, with no separate API subscription.

Get an API keyTry a voice
01Start

Quick start

  1. Create an account and pick a plan (from $4/month — every plan includes monthly credits).
  2. Create an API key on your dashboard. It starts with ksk_live_.
  3. Make a request — POST your text, get an MP3 back.
curl https://vidsly.ai/api/v1/tts \
  -H "Authorization: Bearer ksk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Three numbers came out this morning, and every one of them moved the market.",
    "voice": "azure-aria",
    "speed": "normal"
  }' \
  --output story.mp3
02Playground

Try it

Hear any voice before you integrate. This uses your account's character allowance — no API key needed here.

Voice sample

76/300
"voice": "azure-aria"
03Reference

Request reference

POST/api/v1/tts

Send a JSON body with a Bearer API key. The default response is audio/mpeg, with X-Characters and X-Credits-Charged headers.

NameDescription
textstring · requiredUp to 1,000,000 characters per request. Up to ~20,000 returns audio directly; longer texts return 202 + a jobId to poll for the MP3 URL.
voicestring · optionalVoice id. Default azure-aria. See Voices or GET /api/v1/voices.
speedstring · optionalslow | normal | gentle. Default normal.
formatstring · optionalmp3 (binary, default) or json (base64 in audio, plus characters and credits_charged).

Long texts

Above ~20,000 characters the request returns 202 with a jobId. Poll it until status is completed and read audioUrl.

Poll a long job
curl "https://vidsly.ai/api/v1/tts?jobId=JOB_ID" \
  -H "Authorization: Bearer ksk_live_YOUR_KEY"
04Reference

Errors

Errors are JSON: { "error": { "code", "message" } }. You are never charged for a failed request.

StatusCode
400invalid_request

The body isn't JSON, or text is missing.

400text_too_long

text is over 1,000,000 characters.

400invalid_voice

Unknown voice id — GET /api/v1/voices lists them.

400invalid_speed

speed isn't slow, normal or gentle.

400content_rejected

The text falls outside the content policy (see Content safety).

401unauthorized

Missing or invalid API key.

402insufficient_credits

Not enough credits in your balance for this request.

402key_cap_exceeded

The request would pass this key's monthly character cap.

404not_found

Unknown jobId when polling a long job.

429rate_limited

Too many requests — wait a minute and retry.

502synthesis_failed

Speech synthesis failed. Retry.

502unavailable

The long-text narration service couldn't be reached. Retry.

503moderation_unavailable

Content screening is briefly down, so the request fails closed. Retry.

503unavailable

Long-text narration is briefly unavailable. Retry.

05Catalog

Voices (51)

Pass the id as voice. Tap an id to copy it, or fetch the list from GET /api/v1/voices.

OpenAI Voices (13)

  • Alloy · Neutral
  • Ash · Confident
  • Ballad · Expressive
  • Coral · Bright
  • Echo · Calm
  • Fable · Warm
  • Onyx · Deep
  • Nova · Energetic
  • Sage · Thoughtful
  • Shimmer · Light
  • Verse · Dynamic
  • Marin · Smooth
  • Cedar · Resonant

Storytelling Voices (12)

  • Aria · English (US)
  • Jenny · English (US)
  • Michelle · English (US)
  • Monica · English (US)
  • Sara · English (US)
  • Guy · English (US)
  • Davis · English (US)
  • Tony · English (US)
  • Freya · English (AU)
  • William · English (AU)
  • Neerja · English (IN)
  • Emily · English (IE)

Narration Voices (10)

  • Calm Guide · English (US)
  • Clear Explainer · English (US)
  • Sunny Friend · English (US)
  • Soft Whisper · English (US)
  • Lively · English (US)
  • Friendly Host · English (US)
  • Steady Narrator · English (US)
  • Mellow · English (US)
  • Gentle Giant · English (US)
  • Seasoned Narrator · English (US)

Language Voices (16)

  • Dalia · Spanish (Mexico)
  • Jorge · Spanish (Mexico)
  • Elena · Spanish (Spain)
  • Denise · French
  • Henri · French
  • Vivienne · French
  • Katja · German
  • Konrad · German
  • Amala · German
  • Francisca · Portuguese (Brazil)
  • Antonio · Portuguese (Brazil)
  • Thalita · Portuguese (Brazil)
  • Isabella · Italian
  • Giuseppe · Italian
  • Sun Hi · Korean
  • InJoon · Korean
06Billing

Pricing

1 credit per 10 characters (minimum 1 credit per request), from the same credit balance as the rest of Vidsly. Every plan includes monthly credits — from 5,000 on Basic ($4/month) up to 200,000 on Studio — so roughly $0.045–0.08 per 1,000 characters. Unused credits bank for 90 days.

API billing

Credits
Per 1,000 characters
$0.045–0.08, depending on plan
Separate API subscription
None — every plan's credits cover it
Max characters per request
1,000,000 (long jobs return a jobId to poll)
07Policy

Content safety

Every request is screened by an AI moderation layer before synthesis. Text that falls outside our content policy is rejected (HTTP 400 content_rejected, no charge): sexual content, hate speech, threats against real people, instructions for violent wrongdoing, and graphic gore. Reporting on a difficult subject is fine — depicting it explicitly is not, so true crime, war, hard news and politics all pass. If the moderation provider is unreachable the request fails closed with a 503 rather than being synthesised unchecked.

08MCP · works with Claude

Use the same key from inside Claude

Add the MCP server to Claude Code or Claude Desktop and ask in plain words — the MP3 or a watch link comes back in the chat.

  • create_audio_story — narrates a script to a voiceover MP3
  • create_talking_storybook — renders a presenter video
  • get_storybook_status — checks a render and returns the watch link
  • list_characters — lists the presenter characters
Set up MCP vidsly-mcp on npm

Questions? Contact us — we reply within 24 hours.