# Models speech create

`POST /models/v1/audio/speech` · Rivier · models

Text spoken in a voice of the voice catalogue (the voices live sessions use), through a speech route: 16-bit 24 kHz PCM, a WAV file, 8 kHz mu-law for a telephone line, or Ogg Opus where the deployment has the encoder. Spoken a sentence at a time: stream to hear the first sentence before the rest is made, or ask for the sentences apart with their text to cache and reorder them. Each sentence is a call under the project's limits.

- Scope: models:write
- Sdk: models.speech.create
- Cli: models speech create

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9._-]{0,39}$",
      "description": "A speech route this project can call (GET /models/v1/models, kind speech)"
    },
    "input": {
      "type": "string",
      "minLength": 1,
      "maxLength": 5000
    },
    "voice": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40,
      "description": "A voice id from GET /voice/catalogue, the same voices live sessions use"
    },
    "language": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$"
    },
    "style": {
      "type": "string",
      "maxLength": 200,
      "description": "How to say it, in words: \"warmly\", \"slowly and clearly\""
    },
    "format": {
      "type": "string",
      "enum": [
        "pcm",
        "wav",
        "mulaw",
        "opus"
      ],
      "default": "wav",
      "description": "pcm: 16-bit 24 kHz mono; wav: the same in a WAV file; mulaw: 8 kHz for a telephone line; opus: Ogg Opus"
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Send the sound as each sentence is spoken"
    },
    "sentences": {
      "type": "boolean",
      "default": false,
      "description": "Answer each sentence apart, as JSON with its text and its sound, so it can be cached and reordered"
    },
    "purpose": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9._-]{0,39}$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "model",
    "input",
    "voice"
  ],
  "additionalProperties": false
}
```

## Responses

- `200`: Success
- `400`: The request was malformed
- `401`: No valid credential
- `403`: The credential lacks the scope, origin or address
- `429`: Over the key's rate limit; see Retry-After

## Example

```sh
curl -X POST 'https://api.rivier.ai/models/v1/audio/speech' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "string",
  "input": "string",
  "voice": "string"
}'
```