> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.
# Authentication
> Create an API key, authenticate your requests, and verify the key works.
Every request to the Smallest AI API requires an API key in the `Authorization` header.
```
Authorization: Bearer YOUR_API_KEY
```
## Create your API key
#### Open the API Keys page
Go to [API Keys](https://app.smallest.ai/dashboard/api-keys?utm_source=documentation\&utm_medium=authentication) in the [Smallest AI console](https://app.smallest.ai/dashboard).
#### 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.
#### 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.
#### Set it in your environment
```bash
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)
```bash
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)
```bash
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:
```json
{
"transcription": "This is a sample audio file for testing speech to text transcription with the Pulse API."
}
```
## Use your key in code
Include the `Authorization: Bearer YOUR_API_KEY` header on every request.
```bash cURL
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
```
```python Python
import os
import requests
response = requests.post(
"https://api.smallest.ai/waves/v1/tts",
headers={
"Authorization": f"Bearer {os.environ['SMALLEST_API_KEY']}",
"Content-Type": "application/json",
"Accept": "audio/wav",
},
json={"text": "Authentication test", "voice_id": "meher", "model": "lightning_v3.1_pro", "output_format": "wav"},
)
```
```javascript JavaScript
const response = await fetch(
"https://api.smallest.ai/waves/v1/tts",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SMALLEST_API_KEY}`,
"Content-Type": "application/json",
Accept: "audio/wav",
},
body: JSON.stringify({
text: "Authentication test",
voice_id: "meher",
model: "lightning_v3.1_pro",
output_format: "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](https://app.smallest.ai/dashboard/api-keys)
* Each key tracks usage against your account quota — see [Concurrency and Limits](/models/api-reference/concurrency-and-limits)
## Error responses
| Status | Meaning |
| ----------------------- | ---------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key |
| `403 Forbidden` | Key doesn't have access to this resource |
| `429 Too Many Requests` | Rate limit exceeded — wait and retry |
For rate limits and concurrency, see [Concurrency and Limits](/models/api-reference/concurrency-and-limits).