Transcribe (Pre-recorded)
Transcribe (Pre-recorded)
Transcribe an audio file. The model is chosen via `?model=`:
- `?model=pulse-pro`: English-only, leaderboard-ranked accuracy. Raw bytes only; pass `webhook_url` to receive transcription asynchronously on long files.
- `?model=pulse`: multilingual transcription (38 languages), supports both raw bytes and audio-by-URL.
## When to use this
Use this endpoint when you have a complete audio file (call recording, voicemail, podcast episode) and want the transcript back in one response. For live transcription as audio arrives, use the realtime WebSocket endpoint (`WS /waves/v1/stt/live`) instead.
Pulse Pro has no streaming worker today; calls to `WS /waves/v1/stt/live?model=pulse-pro` return `400` before the WebSocket upgrades.
## Input methods
- **Raw bytes**: `Content-Type: application/octet-stream` with the audio in the body. All knobs are query parameters.
- **URL (`?model=pulse` only)**: `Content-Type: application/json` with `{"url": "..."}` in the body.
## Examples
**cURL**: Pulse Pro, sync
```bash
curl -X POST "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en&word_timestamps=true" \
-H "Authorization: Bearer $SMALLEST_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary "@./call.wav"
```
**cURL**: Pulse Pro, async via webhook
```bash
curl -X POST "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en&webhook_url=https://your.app/cb" \
-H "Authorization: Bearer $SMALLEST_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary "@./call.wav"
```
Returns `200 { "status": "processing", "request_id": "..." }` immediately. The webhook receives the full transcription when ready.
**cURL**: Pulse, audio-by-URL
```bash
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://your-bucket.s3.amazonaws.com/call.wav"}'
```
**Python**
```python
import requests
with open("./call.wav", "rb") as f:
audio = f.read()
r = requests.post(
"https://api.smallest.ai/waves/v1/stt/",
params={"model": "pulse-pro", "language": "en", "word_timestamps": "true"},
headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/octet-stream"},
data=audio,
)
r.raise_for_status()
print(r.json()["transcription"])
```
**JavaScript / TypeScript**
```typescript
import { readFileSync } from "node:fs";
const audio = readFileSync("./call.wav");
const params = new URLSearchParams({ model: "pulse-pro", language: "en", word_timestamps: "true" });
const res = await fetch(`https://api.smallest.ai/waves/v1/stt/?${params}`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SMALLEST_API_KEY}`, "Content-Type": "application/octet-stream" },
body: audio,
});
console.log((await res.json()).transcription);
```
## Common gotchas
- **`model` is required.** Missing or invalid values return `400` with an enum-validation error.
- **Pulse Pro is English only.** Pass `language=en`. Other language codes are accepted at the wire level but produce unpredictable output.
- **Pulse Pro does not support audio-by-URL.** Send raw bytes or use `?model=pulse` for the URL flow.
- **Async (webhook) mode is Pulse Pro only.** Pulse runs sync only on this endpoint.
- **Max payload 250 MB.** Larger requests return `413`. Compress to mono 16 kHz PCM if you are close to the limit; quality is unaffected.