Skip to content
ShapelessAI← Back
Media

Turn text into speech

Read up to 2,000 characters aloud into a WAV in the media library, for $0.03 a call.

View as Markdown

Pick one of six narrator voices (Sulafat, Charon, Kore, Achird, Erinome, Schedar) or pass a character from GET /api/characters to speak in that actor's designed voice. Energy is calm, confident, energetic or hype, and a style line adds direction in plain words. The WAV key goes into a video edit or a post.

Ask in plain words

  • "read this script aloud in a calm female voice"
  • "text to speech API for my videos"
  • "make a voiceover for the launch clip"

From an agent host (MCP)

Server: https://shapelessai.com/mcp (add it to your host).

  • speak: Read up to 2000 characters aloud into a WAV in the media library, in a preset voice (Sulafat, Charon, Kore, Achird, Erinome, Schedar) or a character's own voice id from characters_list, with an energy and a style line. Returns its media key. SPENDS CREDIT: about $0.03 of engine cost a default call, billed with the plan's margin; budgetUsd caps it (default 2, max 10) and chargedUsd says what it cost. Needs the write scope.

From code (REST)

Bearer API key with the scope each call names (auth, OpenAPI).

  • POST /api/speech (write scope): Text to speech (tool speak): {text (<= 2000 chars), voice? (Sulafat, Charon, Kore, Achird, Erinome, Schedar), character? (id or slug, reads in its voice), energy? (calm|confident|energetic|hype), style?, name?, budgetUsd?}. Output mediaKey is a WAV.

The body

  • text string, required: What to say, exactly as it should be read. At most 2000 characters.
  • voice string: A roster name or a character voice id. Default Charon.
  • energy string (calm, confident, energetic, hype): How the read moves: calm (measured and reassuring - explainers, anything serious or reflective); confident (the default: brisk, warm, matter-of-fact - product and brand video); energetic (bright and driving - launches, feature reveals, anything with momentum); hype (creator-loud - short-form hooks, reaction and meme-adjacent posts). Default confident.
  • style string: Extra direction in plain words, e.g. "smile on the last line". Gemini voices only.
  • name string: File name stem. Default: the voice name.
  • budgetUsd number: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

From a terminal (CLI)

  • shapeless tools run speak --input '<json>' (tools show speak prints the schema)

Example

curl -s https://shapelessai.com/api/speech -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"text":"We ship on Friday. Here is what changed.","voice":"Kore","energy":"energetic"}'

Refusals

StatusMeaning
400The input does not match the tool's schema; the message names the field.
402Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
404No such tool on this deployment.
422The tool refused this input; nothing was charged.
502The tool failed; nothing was charged.

Where else

More in Media

Generate an image · Generate AI video · Edit a video · Record a product demo · Render a carousel · Render a thumbnail · Make subtitle files · Call any agent tool

Every capability · Docs · /llms.txt