---
title: "Turn text into speech"
method: POST
path: "/v1/audio/speech"
tags: ["Audio"]
---

# Turn text into speech

`POST /v1/audio/speech`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/audio/speech`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Speaks the text with the chosen voice and stores the audio as a new file in your library.
SYNCHRONOUS: the response carries the file. Billed per 1,000 characters of the trimmed text
(price per quality from `GET /v1/audio/speech/quote`); nothing is charged when the voice
cannot be generated. The language follows the text.
Qualities: `standard` (OpenAI gpt-4o-mini-tts, takes `instructions`), `studio` (ElevenLabs Multilingual v2).

## Request body

- object
  - `text` string, required: What to say, up to 4000 characters.
  - `quality` 'standard' | 'studio'
  - `voice` string: A voice id of the quality (see the quote). Default: its first voice.
  - `instructions` string: standard only: how to deliver the text, e.g. "calm and friendly".
  - `title` string: Used for the file name. Default: the first words of the text.
  - `client_ref` string: Idempotency key: a repeat within 24 h returns the first response and is not charged again.

## Response `201`

The stored audio file.

- object
  - `success` boolean
  - `data` object
    - `file_uuid` string, uuid
    - `file_name` string
    - `mime_type` string
    - `duration_ms` integer, nullable
    - `size_bytes` integer, nullable
    - `characters` integer
    - `credits` number, float: Credits charged.
    - `quality` string
    - `voice` string
  - `timestamp` string, date-time

## Other responses

- `400`: Missing text, or an unknown quality or voice.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits.
- `403`: The token does not hold audio:write.
- `409`: A request with this client_ref is still running.
- `413`: The text is too long.
- `502`: The voice could not be generated; nothing was charged.
- `503`: This quality is not available right now.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)