Authentication

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

1

Open the API Keys page

Go to API Keys in the Smallest AI console.

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.

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.

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/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.

Content expiry (Enterprise)

Enterprise plans can add one more header to any TTS, STT or LLM request so that its content is not retained:

x-expire-content: true

That request’s content is expired within 7 days and the usage record is kept. Organizations can also have zero retention or a retention window set on every request, with no header. On other plans the header is ignored and the request is processed normally. See Zero Data Retention.

Security

• 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

For rate limits and concurrency, see Concurrency and Limits.