Realtime, low-latency text-to-speech delivered as base64 audio chunks over HTTP Server-Sent Events (POST /lightning-v2/get_speech/stream) and over a bidirectional WebSocket (wss://.../lightning-v2/get_speech/stream).
openapi: 3.0.1
info:
title: Smallest AI Waves API
description: >-
The Smallest AI Waves text-to-speech API. Generates natural speech from text
using the Lightning family of models with sub-100ms latency, streams audio in
realtime over Server-Sent Events, lists prebuilt voices, and clones custom
voices from short audio samples. All endpoints are authenticated with a Bearer
API key. The realtime bidirectional WebSocket transport for streaming TTS is
modeled in the companion AsyncAPI document
(asyncapi/smallest-ai-asyncapi.yml).
termsOfService: https://smallest.ai/terms
contact:
name: Smallest AI Support
url: https://smallest.ai/
email: support@smallest.ai
version: '1.0'
servers:
- url: https://waves-api.smallest.ai/api/v1
description: Waves production API
security:
- bearerAuth: []
tags:
- name: Text to Speech
description: Synthesize speech from text.
- name: Streaming
description: Realtime streaming speech synthesis.
- name: Voices
description: List prebuilt voices and manage cloned voices.
paths:
/lightning/get_speech:
post:
operationId: getSpeech
tags:
- Text to Speech
summary: Synthesize speech from text.
description: >-
Generates an audio file from the input text using a Lightning TTS model
and the specified voice. Returns the synthesized audio as a binary
response.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetSpeechRequest'
responses:
'200':
description: Synthesized audio.
content:
audio/wav:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimited'
/lightning-v2/get_speech/stream:
post:
operationId: streamSpeech
tags:
- Streaming
summary: Stream synthesized speech (SSE).
description: >-
Streams synthesized speech in realtime using the Lightning v2 model. The
response is an HTTP Server-Sent Events stream whose `data:` frames each
carry a JSON object containing a base64-encoded audio chunk; a final
frame signals completion. The same path is also available as a
bidirectional WebSocket (wss) endpoint - see the AsyncAPI document.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StreamSpeechRequest'
responses:
'200':
description: Server-Sent Events stream of base64 audio chunks.
content:
text/event-stream:
schema:
$ref: '#/components/schemas/AudioStreamChunk'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimited'
/lightning/get_voices:
get:
operationId: getVoices
tags:
- Voices
summary: List available voices.
description: >-
Returns the catalog of prebuilt voices available for synthesis, including
each voice's identifier and metadata such as language, gender, and accent.
responses:
'200':
description: A list of available voices.
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceList'
'401':
$ref: '#/components/responses/Unauthorized'
/lightning/add_voice:
post:
operationId: addVoice
tags:
- Voices
summary: Clone a voice.
description: >-
Creates a new cloned voice from a short reference audio sample. The
resulting voice identifier can be used as the `voice_id` in synthesis
requests.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/AddVoiceRequest'
responses:
'200':
description: The created cloned voice.
content:
application/json:
schema:
$ref: '#/components/schemas/Voice'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/lightning/get_cloned_voices:
get:
operationId: getClonedVoices
tags:
- Voices
summary: List cloned voices.
description: Returns the voices that the authenticated account has cloned.
responses:
'200':
description: A list of cloned voices.
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceList'
'401':
$ref: '#/components/responses/Unauthorized'
/lightning/delete_voice/{voiceId}:
delete:
operationId: deleteVoice
tags:
- Voices
summary: Delete a cloned voice.
description: Permanently deletes a previously cloned voice owned by the account.
parameters:
- name: voiceId
in: path
required: true
description: Identifier of the cloned voice to delete.
schema:
type: string
responses:
'200':
description: The voice was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: The voice was not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Pass your Waves API key as a Bearer token in the Authorization header:
`Authorization: Bearer <SMALLEST_API_KEY>`.
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: The request body failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Too many requests; the account rate limit was exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
GetSpeechRequest:
type: object
required:
- text
- voice_id
properties:
text:
type: string
description: The text to convert to speech.
example: Modern problems require modern solutions.
voice_id:
type: string
description: Identifier of the voice to synthesize with.
example: meher
model:
type: string
description: The Lightning TTS model pool to use.
default: lightning
example: lightning-v2
sample_rate:
type: integer
description: Output audio sample rate in Hz.
default: 24000
example: 24000
speed:
type: number
format: float
description: Speech rate multiplier; 1.0 is normal speed.
default: 1.0
minimum: 0.5
maximum: 2.0
language:
type: string
description: Language code for synthesis.
default: en
example: en
output_format:
type: string
description: Encoding of the returned audio.
default: wav
enum:
- wav
- pcm
- mp3
add_wav_header:
type: boolean
description: >-
Whether to prepend a WAV header to the returned audio. Set false to
receive raw PCM.
default: true
StreamSpeechRequest:
type: object
required:
- text
- voice_id
properties:
text:
type: string
description: The text to stream as speech.
voice_id:
type: string
description: Identifier of the voice to synthesize with.
example: meher
model:
type: string
description: The Lightning streaming model pool.
default: lightning-v2
sample_rate:
type: integer
description: Output audio sample rate in Hz.
default: 24000
speed:
type: number
format: float
description: Speech rate multiplier; 1.0 is normal speed.
default: 1.0
language:
type: string
description: Language code for synthesis.
default: en
AudioStreamChunk:
type: object
description: >-
JSON payload carried in each SSE `data:` frame. Frames carry a base64
audio chunk until a final frame sets `done` to true.
properties:
audio:
type: string
format: byte
description: Base64-encoded raw PCM audio chunk.
done:
type: boolean
description: True on the final frame to indicate the stream has completed.
AddVoiceRequest:
type: object
required:
- displayName
- file
properties:
displayName:
type: string
description: Human-readable name for the cloned voice.
example: My Brand Voice
file:
type: string
format: binary
description: Reference audio sample (e.g. WAV/MP3) to clone the voice from.
Voice:
type: object
properties:
voiceId:
type: string
description: Unique identifier used as `voice_id` in synthesis requests.
displayName:
type: string
description: Human-readable voice name.
language:
type: string
description: Primary language of the voice.
gender:
type: string
description: Voice gender, when available.
accent:
type: string
description: Voice accent, when available.
tags:
type: array
description: Descriptive tags for the voice.
items:
type: string
VoiceList:
type: object
properties:
voices:
type: array
items:
$ref: '#/components/schemas/Voice'
DeleteResponse:
type: object
properties:
status:
type: string
example: success
message:
type: string
Error:
type: object
properties:
status:
type: string
description: Error status indicator.
message:
type: string
description: Human-readable error message.
error:
type: string
description: Error code or detail, when present.