API References

Authentication

View as Markdown

Every request to the Smallest AI API requires an API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Create your API key

1

Open the API Keys page

Go to API Keys in the Smallest AI console.

Smallest AI console with API Keys section open
2

Create a new key

Click Create API Key in the top-right corner, enter a name (e.g., my-tts-app), and click Create API Key to confirm.

API Keys page showing the Create API Key buttonCreate New API Key dialog with API Name field and Create API Key button
3

Copy the key

The new key appears in your dashboard. Click the copy icon — it’s shown only once at creation, so copy it now.

API Keys dashboard showing the newly created key with copy icon highlighted
4

Set it in your environment

$export SMALLEST_API_KEY="your-api-key-here"

Add this to your .bashrc or .zshrc to persist across sessions.

Test your key

Confirm the key works by hitting two endpoints — one for TTS, one for STT — directly from your terminal. No install required.

Generate speech (Lightning TTS)

$curl -X POST "https://api.smallest.ai/waves/v1/tts" \
>  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>  -H "Content-Type: application/json" \
>  -H "Accept: audio/wav" \
>  -d '{"text": "Hello from Smallest AI.", "voice_id": "meher", "model": "lightning_v3.1_pro", "sample_rate": 24000, "output_format": "wav"}' \
>  --output hello.wav

Play hello.wav — you should hear the generated audio.

Transcribe audio (Pulse STT)

$curl -X POST "https://api.smallest.ai/waves/v1/pulse/get_text?language=en" \
>  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"url": "https://github.com/smallest-inc/cookbook/raw/main/speech-to-text/getting-started/samples/audio.wav"}'

You’ll get back:

1{
2  "transcription": "This is a sample audio file for testing speech to text transcription with the Pulse API."
3}

Use your key in code

Include the Authorization: Bearer YOUR_API_KEY header on every request.

$curl -X POST "https://api.smallest.ai/waves/v1/tts" \
>  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>  -H "Content-Type: application/json" \
>  -H "Accept: audio/wav" \
>  -d '{"text": "Authentication test", "voice_id": "meher", "model": "lightning_v3.1_pro", "output_format": "wav"}' \
>  --output test.wav

Security

Your API key is a secret. Never expose it in client-side code, public repositories, or browser applications.

  • Store keys in environment variables, not in source code
  • Use .env files locally and add .env to .gitignore
  • Rotate keys periodically from the API Keys page
  • Each key tracks usage against your account quota — see Concurrency and Limits

Error responses

StatusMeaning
401 UnauthorizedMissing or invalid API key
403 ForbiddenKey doesn’t have access to this resource
429 Too Many RequestsRate limit exceeded — wait and retry

For rate limits and concurrency, see Concurrency and Limits.