Model APIs / Text-to-speech

# Text-to-speech

Turn text into audio. The body is the audio; the request id, provider, model and charge come back as headers.

`POST` `/v1/audio/speech` `inference:invoke`[Browse text-to-speech models →](https://yelno.ai/catalog?type=speech)

## Request

| Field | Required | Notes |
| --- | --- | --- |
| model | required | A text-to-speech model's id. |
| input | required | The text to speak. |
| voice | optional | One of the model's voices. They are listed as `voices` on `GET /v1/models/{id}` (the list may be empty) and on the model's catalog page. |
| response_format | optional | `"mp3"` · `"wav"` · `"pcm"` · `"opus"` · `"flac"` · `"aac"` |
| speed | optional | Speaking rate. |

Request

```
curl https://yelno.ai/v1/audio/speech \
  -H "Authorization: Bearer $YELNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL",
    "input": "Your order has shipped and arrives on Thursday.",
    "response_format": "mp3"
  }' \
  --output speech.mp3 --dump-header headers.txt
```

## Response

200 with the audio bytes, `Content-Type` as the provider returned it (some models only produce `pcm`; the model's own 400 says so). Because the body is audio, the evidence travels in headers: `X-Request-Id`, `Yelno-Provider`, `Yelno-Model`, `Yelno-Cost-State` (`pending` until the provider reports the cost) and `Yelno-Charge-Nanos` once it is known.

200 · audio

```
HTTP/1.1 200 OK
Content-Type: audio/mpeg            # as the provider returned it
X-Request-Id: req_…
Yelno-Provider: …
Yelno-Model: …
Yelno-Cost-State: pending          # until the provider reports this response's cost
Yelno-Charge-Nanos: …              # once the cost is known

<audio bytes>
```

## Notes

No streaming yet, and no `Idempotency-Key` replay on this route — the audio bytes are not stored. Voice cloning is not offered: any field this route does not list is refused with `400` `code: "unsupported_parameter"`. Speech returns bare audio, so the charge settles when the provider publishes that response's cost.

Sending a model to a route it is not served on answers `422` `capability_unsupported` with `code: "operation_unsupported"` and a message naming the route that serves it. Every model in the [catalog](https://yelno.ai/catalog?type=speech) shows its type and route.

Source: https://yelno.ai/docs/speech