# Speech and transcription

V1 exposes separate endpoints for text-to-speech and file transcription. They share API-key authentication with chat but use different input formats and billing units.

> These are the mappings and validations in the current V1 implementation. Audio service availability is separate from the chat model list; these documentation examples are not evidence of a live audio test.

## Generate speech

Send JSON to `POST /v1/audio/speech` and save the returned audio bytes:

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/audio/speech \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Welcome to SimpleLLM.",
    "voice": "alloy",
    "response_format": "mp3",
    "speed": 1
  }' \
  --output speech.mp3
~~~

| Field | Default | V1 behavior |
| --- | --- | --- |
| `input` | Required | Nonempty, at most 4096 UTF-8 bytes |
| `model` | `tts-1` | Forwarded to the configured speech service |
| `voice` | `alloy` | alloy, echo, fable, onyx, nova, shimmer |
| `response_format` | `mp3` | mp3, opus, aac, flac, wav, pcm |
| `speed` | 1 | 0.25 to 4; zero is normalized to the default |

The response is binary audio, not JSON containing an audio URL. Check HTTP status before treating the saved body as a valid audio file; an error body can contain JSON instead.

UTF-8 bytes are not the same as characters. Non-ASCII text can reach the input limit with fewer than 4096 characters.

## Transcribe a file

Send multipart form data to `POST /v1/audio/transcriptions`:

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/audio/transcriptions \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY" \
  -F 'file=@recording.wav' \
  -F 'model=whisper-large-v3-turbo' \
  -F 'language=en' \
  -F 'response_format=json'
~~~

Do not manually set a multipart Content-Type header when using cURL or a form-data library: the client must include its generated boundary.

The two explicit V1 model mappings are:

| Model ID | Mapping | Configured SC/min |
| --- | --- | --- |
| `whisper-large-v3-turbo` | Turbo transcription | 0.5 |
| `whisper-large-v3` | Large-v3 transcription | 1.5 |

The compatibility name `whisper-1` maps to `whisper-large-v3-turbo`; it is not another model. Omitting the model selects this alias, but explicit IDs are clearer for new integrations.

## Optional transcription fields

`language`, `prompt`, `response_format`, and `temperature` are forwarded to the transcription service. For language, use a two-letter code such as `de` or `en`; omit it when automatic detection is desired instead of sending a UI label.

JSON responses contain text, for example:

~~~json
{"text": "Welcome to SimpleLLM."}
~~~

Other output formats depend on the upstream service. Inspect Content-Type and do not force every returned body through a JSON parser.

## Audio billing and limitations

Current V1 speech billing is 3 SC per 1000 input UTF-8 bytes. Transcription uses the configured per-minute rate and an estimated duration derived from file size and extension; it is not guaranteed to be an exact measured duration.

These implementation rates were checked on 2026-09-14 and are distinct from chat's per-million-token pricing. Confirm current account pricing before budgeting a larger workload.

The direct GPU-host voice catalogue, voice design, and voice cloning features are not part of this public V1 interface. See the [speech reference](/docs/reference/createSpeech.html) and [transcription reference](/docs/reference/createTranscription.html).