# Generate speech

`POST https://api.vidmoat.com/v1/ai/speech`

- Scope: `ai.speech`
- Cost: 15 credits Grok; 30 credits OpenAI

AI-generated speech, up to 1,000 characters (longer text is cut and the response says where). provider:auto/grok/openai; optional voiceId, language, speed, and OpenAI instructions for delivery. quoteOnly:true quotes without spending. Auto may fall back after a confirmed quota rejection within maxCredits; a named voice stays pinned. Creator and Studio.

### Body

- `text` (string, required): What to say. Over 1,000 characters is cut, and `truncated` reports it.
- `provider` (enum, optional, default `auto`): Who generates it. Auto picks the cheapest that can. One of `auto`, `grok`, `openai`.
- `voiceId` (string, optional): OpenAI: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse, marin (default), cedar. Grok: eve (default), ara, leo, rex, sal. A voice only one provider has pins that provider.
- `language` (string, optional): `auto` or a language code.
- `speed` (number, optional, default `1`): 0.7 to 1.5.
- `instructions` (string, optional): OpenAI only, up to 500 characters: how to deliver the line.
- `maxCredits` (number, optional): Never spend more than this. Routes above it are excluded.
- `quoteOnly` (boolean, optional): `true` returns the route and price without generating or charging.

## Response

Returns `200`.

### Response fields

- `url` (string): The audio file. Use as a clip `src`.
- `route` (object): The provider route chosen: `provider`, `model`, `credits`, `maxCredits`, `reason` and `policy` (and `voiceId` for speech).
- `aiGenerated` (boolean): Always `true`.
- `credits` (object): `{ charged, remaining }`: what this call cost and the balance after it.
- `truncated` (object): Present when the text was cut: `{ at, droppedChars, note }`.
- `hint` (string): What to do with it.

> **Tip: With a test key.** Test keys return a sample audio file and spend nothing. `quoteOnly` is ignored on test keys.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 402 | [`plan_required`](https://developer.vidmoat.com/developer/docs/errors#plan_required) | The plan has no speech generation. |
| 402 | [`insufficient_credits`](https://developer.vidmoat.com/developer/docs/errors#insufficient_credits) | The balance cannot cover the call. Nothing ran. `remaining` is the balance. |
| 422 | [`prompt_rejected`](https://developer.vidmoat.com/developer/docs/errors#prompt_rejected) | The prompt failed the safety check. Nothing was charged. `field` names the field. |
| 502 | [`provider_error`](https://developer.vidmoat.com/developer/docs/errors#provider_error) | The generation provider failed. The charge is refunded. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/ai/speech \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Ship it.","provider":"openai","voiceId":"nova","maxCredits":30}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/ai/speech', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Ship it.',
    provider: 'openai',
    voiceId: 'nova',
    maxCredits: 30,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.post(
    "https://api.vidmoat.com/v1/ai/speech",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "text": "Ship it.",
      "provider": "openai",
      "voiceId": "nova",
      "maxCredits": 30,
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "url": "https://api.vidmoat.com/uploads/ai-speech-1.mp3",
  "route": { "provider": "openai", "model": "gpt-4o-mini-tts", "credits": 30, "maxCredits": 30, "voiceId": "nova", "reason": "…", "policy": "2026-09-20.2" },
  "aiGenerated": true,
  "credits": { "charged": 30, "remaining": 4470 },
  "hint": "…"
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/generation/create-speech
Previous: [Transcribe media](https://developer.vidmoat.com/developer/docs/api/generation/create-transcription.md)
Next: [Generate an image](https://developer.vidmoat.com/developer/docs/api/generation/create-image.md)
All documentation: https://developer.vidmoat.com/llms-full.txt