---
title: "Generate speech"
method: POST
path: "/ai/speech"
tags: ["Generation"]
---

# Generate speech

`POST /ai/speech`

## Request

- Base URL: `https://api.vidmoat.com/v1`
- URL: `https://api.vidmoat.com/v1/ai/speech`
- Auth: HTTP bearer

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.

## Request body

- object
  - `text` string, required: What to say. Over 1,000 characters is cut, and `truncated` reports it.
  - `provider` 'auto' | 'grok' | 'openai': Who generates it. Auto picks the cheapest that can.
  - `voiceId` string: 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: `auto` or a language code.
  - `speed` number: 0.7 to 1.5.
  - `instructions` string: OpenAI only, up to 500 characters: how to deliver the line.
  - `maxCredits` number: Never spend more than this. Routes above it are excluded.
  - `quoteOnly` boolean: `true` returns the route and price without generating or charging.

## Response `200`

Generate speech

- object
  - `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.

## Other responses

- `402`: `plan_required`: The plan has no speech generation. `insufficient_credits`: The balance cannot cover the call. Nothing ran. `remaining` is the balance.
- `422`: `prompt_rejected`: The prompt failed the safety check. Nothing was charged. `field` names the field.
- `502`: `provider_error`: The generation provider failed. The charge is refunded.

---

[API](https://skmtc.dev/vidmoat/apis/vidmoat-api.md) · [All operations](https://skmtc.dev/vidmoat/apis/vidmoat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vidmoat/apis/vidmoat-api/revisions/23e24e25c756?raw)