A text-to-speech request. Layer A serializable data.

iex> req = ALLM.SpeechRequest.new(input: "Hello.", voice: "alloy", format: :mp3)
iex> ALLM.Validate.speech_request(req)
:ok

Fields

• :input: the text to speak. "" is constructible, and ALLM.Validate.speech_request/1 is what rejects it.
• :model: nil means late-resolved (the engine's speech model, then the adapter's default).
• :voice: a provider-shaped voice name, forwarded as given. ALLM keeps no voice catalogue, because valid names differ per provider and per model. nil lets the adapter choose.
• :format: the audio file format to produce, one of formats/0, or nil for the provider's default. The atoms name file formats, not any one provider's parameter. A provider that cannot produce a format refuses the request, and the atoms are protocol-legal rather than a promise that every provider accepts every one. The response reports the format that actually arrived (ALLM.SpeechResponse's :format). :ulaw and :alaw are headerless G.711 µ-law and A-law telephony audio, 8,000 Hz mono; of the bundled adapters only ALLM.Providers.ElevenLabs.Speech produces them, and ALLM.Providers.OpenAI.Speech refuses them with :unsupported_feature.
• :instructions: optional delivery guidance for models that accept it.
• :sample_rate: the sample rate in Hz of the audio to produce, or nil for the adapter's default for the format. It matters most for :pcm, which is headerless: the bytes cannot be played without knowing the rate. The cross-provider default for :pcm is 24,000 Hz, so switching providers does not silently change the playback rate. The adapter contract is to accept its own set of rates per format, refuse any other with :unsupported_feature, and report the rate that arrived in ALLM.SpeechResponse's :sample_rate (nil when the adapter cannot tell).
• :speed: optional playback speed. Only "a number greater than zero" is checked here, and each provider enforces its own range.
• :options: a raw provider-body passthrough for fields ALLM does not model. An adapter merges it under the fields it sets itself, so an option can never override :input, :model or any other structural field, and fields that would change the response shape are dropped.
• :metadata: caller-owned. Use string keys when it will round-trip through JSON.

There is no :stream field. Streaming is a separate call, not a request flag: the same request goes to ALLM.stream_synthesize/3, and ALLM.stream_synthesize_input/3 takes one whose :input is ignored.

Construction

new/1 is a bare struct!/2 pass-through: unknown keys raise KeyError, and nothing else is checked. new(sample_rate: -1) constructs, and ALLM.Validate.speech_request/1 is what rejects it.