> 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. # Transcribe (Pre-recorded) POST https://api.smallest.ai/waves/v1/stt/ Content-Type: application/octet-stream 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 (21 streaming + 26 pre-recorded 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. Reference: https://docs.smallest.ai/models/api-reference/speech-to-text/transcribe ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: waves-v4 version: 1.0.0 paths: /waves/v1/stt/: post: operationId: transcribe summary: Transcribe (Pre-recorded) description: > 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 (21 streaming + 26 pre-recorded 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. tags: - speechToText parameters: - name: model in: query description: > Selects which ASR model handles the request. Required; missing or invalid values return `400`. - `pulse-pro`: English only, leaderboard-ranked accuracy, raw bytes only; supports async via `webhook_url`. - `pulse`: multilingual (39 languages), raw bytes OR URL. required: true schema: $ref: '#/components/schemas/WavesV1SttPostParametersModel' - name: language in: query description: > Language of the audio file. This endpoint is **Pre-Recorded (HTTP)** — for streaming, switch to `WSS /waves/v1/stt/live` (different supported language set). **26 single-language codes:** `en`, `hi`, `de`, `es`, `ru`, `it`, `fr`, `nl`, `pt`, `uk`, `pl`, `cs`, `sk`, `lv`, `et`, `ro`, `fi`, `sv`, `bg`, `hu`, `da`, `lt`, `mt`, `zh`, `ja`, `ko`. **Regional auto-detect aggregators** for unknown audio: - `multi-eu` — auto-detects across all 21 European codes plus `en`. - `multi-asian` — auto-detects across `zh`, `ko`, `ja`, `en`. - `multi-indic`: auto-detects across `en`, `hi`, `gu`, `mr`, `bn`, `or`. India region only. - **Pulse Pro**: pass `en`. - **Pulse**: pass any of the single-language codes above, or use the `multi-eu` / `multi-asian` / `multi-indic` aggregator for unknown audio. See the [Pulse model card](/models/model-cards/speech-to-text/pulse) for the full table with language names. required: true schema: $ref: '#/components/schemas/WavesV1SttPostParametersLanguage' - name: word_timestamps in: query description: >- Include the per-word `words[]` array in the response — each entry carries the recognized `word`, its `start`/`end` timestamps, and a per-word `confidence` score (0.0–1.0). With `diarize=true`, entries also include `speaker`. On Pulse Pro this costs roughly one-third of throughput. required: false schema: type: boolean default: false - name: diarize in: query description: >- Multi-speaker identification; adds per-word and per-utterance speaker labels. required: false schema: type: boolean default: false - name: webhook_url in: query description: > Pulse Pro only. If set, the response is `200` with `{"status": "processing", "request_id": "..."}` immediately, and the full transcription is delivered to this URL when ready. Use for long files where you do not want to hold an HTTP connection open. required: false schema: type: string format: uri - name: webhook_method in: query description: HTTP method to use when calling the webhook. Pulse Pro only. required: false schema: $ref: '#/components/schemas/WavesV1SttPostParametersWebhookMethod' default: POST - name: webhook_extra in: query description: >- Arbitrary metadata returned to the webhook in addition to the transcription payload. Pulse Pro only. required: false schema: type: string - name: redact_pii in: query description: | Redact personally identifiable information from the transcript. Names → `[FIRSTNAME_*]` / `[LASTNAME_*]`, phone numbers → `[PHONENUMBER_*]`, addresses → `[ADDRESS_*]`, etc. The redaction tokens use sequential indices so multiple occurrences of the same entity get distinct labels (`[FIRSTNAME_1]`, `[FIRSTNAME_2]`). **Language support:** currently effective only on `en` and `hi`. Setting `redact_pii=true` on other language codes is accepted but does not redact. required: false schema: $ref: '#/components/schemas/WavesV1SttPostParametersRedactPii' default: 'false' - name: redact_pci in: query description: | Redact payment card information (credit-card numbers, CVV, account numbers, etc.). Replaces matches with `[ACCOUNTNUMBER_*]` tokens. Use alongside `redact_pii=true` for full PCI-compliant transcript handling. **Language support:** currently effective only on `en` and `hi`. Setting `redact_pci=true` on other language codes is accepted but does not redact. required: false schema: $ref: '#/components/schemas/WavesV1SttPostParametersRedactPci' default: 'false' - name: emotion_detection in: query description: | When `true`, the response adds an `emotions` object mapping detected emotion labels to confidence scores. Useful for voice-of-customer analytics on call recordings. required: false schema: $ref: '#/components/schemas/WavesV1SttPostParametersEmotionDetection' default: 'false' - name: gender_detection in: query description: | When `true`, the response adds a `gender` field with the detected speaker gender label. Pulse pre-recorded only. required: false schema: $ref: '#/components/schemas/WavesV1SttPostParametersGenderDetection' default: 'false' - name: Authorization in: header required: true schema: type: string responses: '200': description: > Transcription succeeded. The response body has two shapes: - **Sync**: full `TranscriptionResponse` with `transcription`, `words`, `metadata`, etc. Returned when `webhook_url` is not set (all `?model=pulse` requests, and `?model=pulse-pro` requests without a webhook). - **Async**: `{ "status": "processing", "request_id": "..." }`. Returned when `?model=pulse-pro` is paired with `webhook_url`. The full `TranscriptionResponse` then arrives on the webhook when ready. content: application/json: schema: $ref: '#/components/schemas/Speech to Text_transcribe_Response_200' '400': description: >- Missing or invalid `model` query parameter, invalid params, or unsupported feature combination (e.g. `?model=pulse-pro` on the WS endpoint, audio-by-URL with `?model=pulse-pro`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: API key missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Plan does not include access to the requested model. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: Payload exceeds 250 MB. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: RPM cap exceeded (Standard plan default 25/min per model). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Worker temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: content: application/octet-stream: schema: type: string format: binary servers: - url: https://api.smallest.ai description: waves components: schemas: WavesV1SttPostParametersModel: type: string enum: - pulse-pro - pulse title: WavesV1SttPostParametersModel WavesV1SttPostParametersLanguage: type: string enum: - en - hi - de - es - ru - it - fr - nl - pt - uk - pl - cs - sk - lv - et - ro - fi - sv - bg - hu - da - lt - mt - zh - ja - ko - multi-eu - multi-asian - multi-indic title: WavesV1SttPostParametersLanguage WavesV1SttPostParametersWebhookMethod: type: string enum: - GET - POST default: POST title: WavesV1SttPostParametersWebhookMethod WavesV1SttPostParametersRedactPii: type: string enum: - 'true' - 'false' default: 'false' title: WavesV1SttPostParametersRedactPii WavesV1SttPostParametersRedactPci: type: string enum: - 'true' - 'false' default: 'false' title: WavesV1SttPostParametersRedactPci WavesV1SttPostParametersEmotionDetection: type: string enum: - 'true' - 'false' default: 'false' title: WavesV1SttPostParametersEmotionDetection WavesV1SttPostParametersGenderDetection: type: string enum: - 'true' - 'false' default: 'false' title: WavesV1SttPostParametersGenderDetection Word: type: object properties: word: type: string start: type: number format: double end: type: number format: double confidence: type: number format: double description: Per-word confidence score, from 0.0 to 1.0. speaker: type: string description: Present when `diarize=true`. title: Word Utterance: type: object properties: text: type: string start: type: number format: double end: type: number format: double speaker: type: string title: Utterance TranscriptionResponseMetadata: type: object properties: duration: type: number format: double description: Audio duration in seconds. processing_time_ms: type: number format: double description: Pulse Pro only. rtfx: type: number format: double description: Real-time factor for this request (Pulse Pro only). num_chunks: type: number format: double description: Number of internal chunks the audio was split into (Pulse Pro only). filename: type: string description: Pulse responses include this when sent via URL. fileSize: type: number format: double description: Bytes received (Pulse responses). title: TranscriptionResponseMetadata TranscriptionResponse: type: object properties: status: type: string transcription: type: string words: type: array items: $ref: '#/components/schemas/Word' utterances: type: array items: $ref: '#/components/schemas/Utterance' description: >- Sentence-level segments with optional speaker labels. Returned by `?model=pulse` only; Pulse Pro responses omit this field. language: type: string metadata: $ref: '#/components/schemas/TranscriptionResponseMetadata' request_id: type: string gender: type: string description: >- Detected speaker gender label. Present when `gender_detection=true` was set on the request. emotions: type: object additionalProperties: type: number format: double description: >- Detected emotion labels mapped to confidence scores. Present when `emotion_detection=true` was set on the request. required: - status - transcription title: TranscriptionResponse AsyncAccepted: type: object properties: status: type: string request_id: type: string required: - status - request_id description: >- Returned by Pulse Pro when `webhook_url` is set. The transcription arrives on the webhook when ready. title: AsyncAccepted Speech to Text_transcribe_Response_200: oneOf: - $ref: '#/components/schemas/TranscriptionResponse' - $ref: '#/components/schemas/AsyncAccepted' title: Speech to Text_transcribe_Response_200 ErrorResponseErrorsItems: type: object properties: {} title: ErrorResponseErrorsItems ErrorResponse: type: object properties: status: type: string message: type: string errors: type: array items: $ref: '#/components/schemas/ErrorResponseErrorsItems' required: - status - message title: ErrorResponse securitySchemes: BearerAuth: type: apiKey in: header name: Authorization ``` ## Examples **Response** ```json { "status": "success", "transcription": "Hi, how are you doing? Could you help me reschedule my appointment?", "words": [ { "word": "Hi", "start": 0.32, "end": 0.4, "confidence": 0.96 }, { "word": "how", "start": 0.48, "end": 0.56, "confidence": 0.93 } ], "language": "en", "metadata": { "duration": 5.6, "processing_time_ms": 240.51, "rtfx": 23.3, "num_chunks": 1 }, "request_id": "87dd36c1-4267-472d-96ee-4113e0a770a6" } ``` **SDK Code** ```python Speech to Text_transcribe_example import requests url = "https://api.smallest.ai/waves/v1/stt/" querystring = {"model":"pulse-pro","language":"en"} headers = { "Authorization": "Bearer ", "Content-Type": "application/octet-stream" } response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Speech to Text_transcribe_example const url = 'https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en'; const options = { method: 'POST', headers: { Authorization: 'Bearer ', 'Content-Type': 'application/octet-stream' } }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Speech to Text_transcribe_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/octet-stream") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Speech to Text_transcribe_example require 'uri' require 'net/http' url = URI("https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/octet-stream' response = http.request(request) puts response.read_body ``` ```java Speech to Text_transcribe_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en") .header("Authorization", "Bearer ") .header("Content-Type", "application/octet-stream") .asString(); ``` ```php Speech to Text_transcribe_example request('POST', 'https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en', [ 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/octet-stream', ], ]); echo $response->getBody(); ``` ```csharp Speech to Text_transcribe_example using RestSharp; var client = new RestClient("https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/octet-stream"); IRestResponse response = client.Execute(request); ``` ```swift Speech to Text_transcribe_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/octet-stream" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```