# Text to Speech API

Turn text into spoken audio with the voice model of your choice, and get each recording as a file link with its length, the voice, the exact model version, its maker and the exact cost of the call. You pay exactly what each text costs at the model's own rates.

**Pricing:** Metered: you pay exactly each call's cost at the selected model's rates (default ElevenLabs: Eleven Flash v2.5: $40.00 per 1M characters). Each model's rates are listed with the `model` parameter's options in the API schema.

**Endpoint:** `POST /v1/data/ai/speech/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `texts` | array | Yes | The texts to speak, one per line, up to 5,000 characters each. Each text is one call and one audio file. |
| `model` | string | No | The text-to-speech model. Pick from the list (popular models first). Each model shows its own rate, mostly per 1M characters, and that is exactly what each text costs. |
| `voice` | string | No | The voice, from the selected model's own voices. Leave blank for the model's first listed voice. |
| `format` | string | No | mp3 or wav. A model that only produces raw audio returns wav, and the row's Format says so. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/ai/speech/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"texts":["..."]}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/ai/speech/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "texts": [
        "..."
    ]
}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `id` | ID | text |
| `text` | Text | text |
| `fileUrl` | File URL | text |
| `mimeType` | MIME Type | text |
| `durationSeconds` | Duration (Seconds) | number |
| `characters` | Characters | number |
| `model` | Model | text |
| `provider` | Provider | text |
| `voice` | Voice | text |
| `format` | Format | text |
| `costUsd` | Cost (USD) | number |
| `error` | Error | text |
| `createdAt` | Created At | datetime |
