Smallest AI

SmallestTools enable an Agent to generate natural speech and list available voices using Smallest AI Lightning text-to-speech.

Prerequisites

Get a Smallest AI key from the Smallest AI dashboard under Developer > API Keys. SmallestTools uses Agno's built-in HTTP client. The example uses Gemini as its agent model.

uv pip install -U "agno[google]"

Set both API keys:

export SMALLEST_API_KEY="your_smallest_api_key_here"
export GOOGLE_API_KEY="your_google_api_key_here"

Example

The following agent will use Smallest AI to generate audio based on a user prompt.

cookbook/91_tools/smallest_tools.py

import base64

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.smallest import SmallestTools
from agno.utils.media import save_base64_data

audio_agent = Agent(
    model=Gemini(id="gemini-pro-latest"),
    tools=[
        SmallestTools(
            voice_id="magnus",
            model="lightning_v3.1",
        )
    ],
    description="You are an AI agent that can generate audio using the Smallest AI API.",
    instructions=[
        "Use the `text_to_speech` tool to convert text into natural voice audio.",
        "Use the `get_voices` tool to list the available voices.",
    ],
    markdown=True,
)

response = audio_agent.run(
    "Generate a short audio welcoming listeners to a podcast about the history of aviation."
)

if response.audio:
    print("Agent response:", response.content)
    base64_audio = base64.b64encode(response.audio[0].content).decode("utf-8")
    save_base64_data(base64_audio, "tmp/podcast_welcome.wav")

Advanced Example: Premium Voices with Lightning v3.1 Pro

For broadcast-quality voices across American, British, and Indian accents, switch to the Pro voice pool:

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.smallest import SmallestTools

pro_audio_agent = Agent(
    model=Gemini(id="gemini-pro-latest"),
    tools=[
        SmallestTools(
            voice_id="meher",
            model="lightning_v3.1_pro",
        )
    ],
    description="You are an AI agent that can generate premium audio using the Smallest AI API.",
    markdown=True,
)

response = pro_audio_agent.run("Generate a short audio narrating a movie trailer.")

Pair voices with the right model: Pro voices (e.g. meher) require model="lightning_v3.1_pro"; standard voices (e.g. magnus) use the default lightning_v3.1. Cloned voices are only available on lightning_v3.1.

Toolkit Params

Parameter	Type	Default	Description
`voice_id`	`str`	`magnus`	Default voice to use for synthesis.
`api_key`	`Optional[str]`	`None`	The Smallest AI API key for authentication. If not provided, uses the `SMALLEST_API_KEY` env variable.
`model`	`str`	`lightning_v3.1`	TTS model. One of `lightning_v3.1`, `lightning_v3.1_pro`. An invalid value raises a `ValueError` up front.
`language`	`str`	`en`	ISO 639-1 language code for synthesis.
`sample_rate`	`int`	`24000`	Output sample rate in Hz.
`speed`	`float`	`1.0`	Speech speed multiplier.
`output_format`	`str`	`wav`	Audio output format. One of `wav`, `mp3`, `pcm`, `ulaw`, `alaw`.
`target_directory`	`Optional[str]`	`None`	If set, generated audio is also saved to this directory.
`base_url`	`str`	Smallest AI TTS endpoint	Override the TTS endpoint — useful for self-hosted or region-pinned deployments.
`enable_get_voices`	`bool`	`True`	Enable the get_voices functionality.
`enable_text_to_speech`	`bool`	`True`	Enable the text_to_speech functionality.
`all`	`bool`	`False`	Enable all functionality.
`timeout`	`float`	`30`	HTTP request timeout in seconds.

Toolkit Functions

Function	Description
`text_to_speech`	Convert text to speech. Detects non-audio responses (e.g. a JSON error body on an HTTP 200) and surfaces them as a tool error instead of saving corrupt audio.
`get_voices`	Get the list of voices available for the configured model. Normalizes the response to `{id, name, gender, accent, languages}` regardless of the API's raw shape.

Models

Model	Languages	Notes
`lightning_v3.1`	model card	Default. Supports cloned voices.
`lightning_v3.1_pro`	model card	Premium voice pool. No voice cloning.