Authentication | Smallest AI Docs

Every request to the Smallest AI API requires an API key in the Authorization header. Server-side code uses the key directly. Browser and mobile clients use a short-lived access token minted from the key.

Authorization: Bearer YOUR_API_KEY

Create your API key

Open the API Keys page

Go to API Keys in the Smallest AI console.

Smallest AI console with API Keys section open

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 button

Create New API Key dialog with API Name field and Create API Key button

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

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/stt/?model=pulse&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:

{
  "status": "success",
  "transcription": "This is a sample audio file for testing speech-to-text transcription with the pulse api.",
  "words": [],
  "utterances": [],
  "metadata": { "duration": 5.6, "fileSize": 268844 }
}

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

Browser and mobile clients

Never ship the API key to a browser or mobile app. Mint a short-lived access token on your server and let the client authenticate TTS, STT and speech-to-speech calls with it. See Token-Based Authentication.

Security

Your API key is a secret. Never expose it in client-side code, public repositories, or browser applications. For browser and mobile clients, mint a short-lived access token on your server, or proxy the call through your backend.

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

Status	Meaning
`401 Unauthorized`	Missing or invalid API key, or an expired access token
`403 Forbidden`	Key doesn’t have access to this resource, an access token was used on a route outside its allowed list, or an access token was used to mint another token
`429 Too Many Requests`	Rate limit exceeded - wait and retry

For rate limits and concurrency, see Concurrency and Limits.