# Text to speech API

A line spoken in a voice, as an MP3, with the time of every word (words: [{word, start, end}] in seconds) for lip sync and captions. A character keeps its voice by voice id: give every line of that character the same voice. Priced per 50 characters.

Tool id `text-to-speech` on the REST API (`POST https://3dvalley.com/api/v1/jobs`); MCP tool `generate_speech` on https://3dvalley.com/mcp. Paid in credits (1 credit = $0.01), taken when the job starts and given back if it fails. The general rules (keys, idempotency, waiting, webhooks) are in [the API docs](https://3dvalley.com/docs/api).

## Models and prices

| Model | Name | Price | Time | What it is |
|---|---|---|---|---|
| `eleven-v4` (default) | ElevenLabs v4 | 1 credit per 50 characters | about 5 s | Natural speech in 70 languages from any of the voices, with word timings for lip sync and captions. Takes audio tags such as [whispering] or [laughs]. |
| `eleven-v3` | ElevenLabs v3 | 1 credit per 50 characters | about 5 s | ElevenLabs' previous expressive model, the same voices and word timings. |

## Input

| Field | Required | |
|---|---|---|
| `text` | yes | What to say: "Hold the gate! The dragon is coming." eleven-v4 also takes audio tags such as [whispering] or [laughs]. Up to 5,000 characters. |

## Options

| Option | Type | Values | |
|---|---|---|---|
| `voice` | text | up to 40 characters | One of the voices by name or id (Eldrin: Crisp British baritone; Darian: Warm, grounded storyteller; Kaelen: Amateur warrior; Sawyer: Midnight storyteller; Wyatt: Seasoned mentor; Callum: Husky trickster; Baxter: Dry, calm Australian; Warren: Effortless and cool; Eddie: Natural and helpful; Caleb: Trusted guide; Lawrence: Bright and informative; Finley: Articulate anchor; Talia: Warm, soft guide; Florence: Atmospheric storyteller; Elara: Crisp professional narrator; Elowen: Upbeat modern narrator; Alicia: Polished global anchor; Maisie: Friendly, casual neighbour; Jade: Upbeat and natural), or any ElevenLabs voice_id. GET /api/v1/voices lists them with samples. Default `Eldrin`. |
| `stability` | number | from 0 to 1 | 0 to 1: lower is more expressive, higher steadier across lines. ElevenLabs' default is 0.5. |
| `language` | text | up to 2 characters | ISO 639-1 code (en, de, ja...), when the language should not be guessed from the words. |

## Output

Files: `audio`, `words`. `audio` is the MP3. `words` is a JSON file, `{ "words": [{ "word": "Hold", "start": 0, "end": 0.2 }, ...] }`, times in seconds from the start: line up captions or a mouth with it. `stats.seconds` is the length.

## Example

```
curl -X POST https://3dvalley.com/api/v1/jobs \
  -H "Authorization: Bearer $THREEDVALLEY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=50" \
  -H "Content-Type: application/json" \
  -d '{"tool":"text-to-speech","input":{"text":"Hold the gate! The dragon is coming."},"options":{"voice":"Eldrin"}}'
```

From an MCP client:

```
generate_speech({"text":"Hold the gate! The dragon is coming.","voice":"Eldrin"})
```

## Limits

- `max_text`: 5,000