> ## Documentation Index > Fetch the complete documentation index at: https://docs.modulate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Speech-to-Text Transcription Batch English VFast > Fast English-only batch transcription with optional word-level timings and speaker diarization. Trades enrichment features for the lowest possible turnaround. ## OpenAPI ````yaml api/velma_2_stt_batch_english_vfast.yaml POST /api/velma-2-stt-batch-english-vfast openapi: 3.1.0 info: title: Velma 2 English STT Batch API version: 0.1.0 description: | Fast, accurate English speech-to-text via HTTP POST. Submit an audio file, get back a single JSON response with the full transcript (cased and punctuated) and the audio duration. No emotion detection, accent detection, or PII/PHI tagging. Two optional per-request flags extend the response, and they are independent of one another: - `time_stamps` adds `words`, a start and end time for every word. - `speaker_diarization` adds `utterances`, speaker-attributed turns. Enabling both adds `words` at the top level and again inside each utterance, with all times relative to the start of the file. ## Response Shape Optional fields are **absent, never null**. A response never gains a key set to `null` because a flag was left off, so a client's schema does not change when a flag is toggled. With both flags false the response is exactly `text` and `duration_ms`. A requested field never disappears without an explanation. If `time_stamps` is enabled and `words` is absent, the response carries `words_unavailable` instead, with a stable machine-readable `reason`. Exactly one of `words` and `words_unavailable` is present on a `time_stamps=true` request; neither is present otherwise. ## Word Coverage `words` covers every whitespace-separated token of `text`, exactly once, in document order. Each entry carries a required `timing` field saying how its span was obtained - `aligned`, `partial`, or `estimated` - so a word whose characters are outside the aligner's vocabulary (digits, hyphens) is still returned with a bracketing span rather than dropped. See `WordTime`. ## Performance Notes - With `speaker_diarization` off, `time_stamps` adds latency that grows with audio length. Benchmark it at the file lengths you expect in production. - With `speaker_diarization` on, `time_stamps` adds no measurable latency at any file length. - `speaker_diarization` transcribes each speaker turn separately, so it is slower than the default path and its transcript can differ from the same audio submitted without the flag. - With speaker diarization enabled, quiet background speech on far-field or multi-party audio can surface as additional utterances. - Overlapping speech (multiple people talking at once) is attributed to a single speaker per time span. servers: - url: https://platform.modulate.ai description: Modulate English STT Batch Server security: - ApiKeyAuth: [] paths: /api/velma-2-stt-batch-english-vfast: post: summary: Transcribe an English audio file description: > Accepts a single audio file and returns its full transcript as a synchronous JSON response. | `time_stamps` | `speaker_diarization` | response keys | | ------------- | --------------------- | ------------------------------------------------------ | | false | false | `text`, `duration_ms` | | true | false | `+ words`, or `+ words_unavailable` | | false | true | `+ utterances` | | true | true | `+ words` and `words` in each utterance, or `+ words_unavailable` | When `words_unavailable` is returned, the transcript and any speaker turns are unaffected - only the timings are missing. operationId: transcribeEnglishVfast2 requestBody: required: true content: multipart/form-data: schema: type: object required: - upload_file properties: upload_file: type: string format: binary description: > Audio file to transcribe. Must be non-empty. Supported formats: `.3g2`, `.3ga`, `.3gp`, `.3gpp`, `.8svx`, `.aa3`, `.aac`, `.ac3`, `.act`, `.adts`, `.aif`, `.aifc`, `.aiff`, `.alac`, `.amb`, `.amr`, `.ape`, `.asf`, `.at3`, `.au`, `.avi`, `.avr`, `.awb`, `.bwf`, `.c2`, `.caf`, `.dss`, `.dts`, `.dtshd`, `.eac3`, `.ec3`, `.f4a`, `.f4b`, `.flac`, `.flv`, `.gsm`, `.iff`, `.m2a`, `.m2ts`, `.m4a`, `.m4b`, `.m4r`, `.m4v`, `.mka`, `.mkv`, `.mlp`, `.mmf`, `.mov`, `.mp+`, `.mp1`, `.mp2`, `.mp3`, `.mp4`, `.mpa`, `.mpc`, `.mpeg`, `.mpg`, `.mpga`, `.mpp`, `.mts`, `.mxf`, `.nist`, `.oga`, `.ogg`, `.ogx`, `.oma`, `.omg`, `.opus`, `.paf`, `.pvf`, `.qcp`, `.ra`, `.rf64`, `.rka`, `.rm`, `.rmvb`, `.sf`, `.shn`, `.snd`, `.sph`, `.svx`, `.tak`, `.thd`, `.ts`, `.tta`, `.vob`, `.voc`, `.vqf`, `.w64`, `.wav`, `.wave`, `.weba`, `.webm`, `.wma`, `.wmv`, `.wv`. Maximum file size: 100 MB. `.aac`, `.aiff`, `.flac`, `.mov`, `.mp3`, `.mp4`, `.ogg`, `.opus`, `.wav`, `.webm`. Maximum file size: 100 MB. time_stamps: type: boolean default: false description: | When enabled, the response includes a `words` array giving the start and end time of every word in `text`, in seconds from the start of the file, with an alignment confidence where one was measured. Timestamps are produced by aligning the final transcript against the audio, so the words always match `text` exactly. Every whitespace-separated token of `text` appears in `words` exactly once, in order; the per-word `timing` field says whether the span was fully measured, measured over a prefix, or bracketed between neighbours. On the non-diarized path, word timings are available up to a maximum audio length configured per deployment (default one hour). Above it the transcript is returned normally and `words_unavailable` carries the `audio_too_long_for_alignment` reason. Treat the exact ceiling as environment-specific: read `max_audio_seconds` from that response rather than hard-coding a value. Setting `speaker_diarization=true` removes the ceiling entirely, because each speaker turn is aligned separately. speaker_diarization: type: boolean default: false description: | Speaker diarization identifies different speakers in the audio. When enabled, the response includes an `utterances` array of time-ordered speaker turns with non-empty transcripts, each attributed to a speaker (e.g., 1, 2) with its timing, and `text` is the time-ordered concatenation of the utterance texts. The array may be empty when no transcribable speech is found. responses: '200': description: Transcription completed successfully. content: application/json: schema: $ref: '#/components/schemas/TranscriptionResponse' examples: short_audio: summary: Short audio transcription value: text: Hello, how are you doing today? duration_ms: 2000 longer_audio: summary: Longer audio with multiple sentences value: text: >- Welcome to today's meeting. We'll be discussing the quarterly results and planning for next quarter. duration_ms: 14253 timestamped_audio: summary: Audio with time_stamps enabled value: text: Hello, how are you? duration_ms: 2000 words: - word: Hello, start: 0.12 end: 0.48 timing: aligned confidence: 0.9912 - word: how start: 0.62 end: 0.78 timing: aligned confidence: 0.9873 - word: are start: 0.8 end: 0.94 timing: aligned confidence: 0.9765 - word: you? start: 0.96 end: 1.24 timing: aligned confidence: 0.9698 mixed_timing: summary: Words the aligner cannot fully place - partial and estimated value: text: COVID-19 cases fell in 2024. duration_ms: 3400 words: - word: COVID-19 start: 0.21 end: 0.94 timing: partial confidence: 0.9614 - word: cases start: 0.97 end: 1.36 timing: aligned confidence: 0.9807 - word: fell start: 1.39 end: 1.68 timing: aligned confidence: 0.9752 - word: in start: 1.7 end: 1.82 timing: aligned confidence: 0.9689 - word: '2024.' start: 1.82 end: 2.61 timing: estimated words_unavailable_too_long: summary: time_stamps requested above the alignment ceiling value: text: Welcome to today's meeting... duration_ms: 5400000 words_unavailable: reason: audio_too_long_for_alignment message: >- Word timings are available up to 3600s of audio; this file is 5400s. The transcript is unaffected. audio_seconds: 5400 max_audio_seconds: 3600 alternative: >- Set speaker_diarization=true to receive word timings on audio of any length. That path aligns each speaker turn separately, so it has no length ceiling; it is slower and its transcript is produced per turn. words_unavailable_empty: summary: time_stamps requested on audio with no transcribable speech value: text: '' duration_ms: 4000 words_unavailable: reason: empty_transcript message: >- No speech was transcribed, so there are no words to time. audio_seconds: 4 max_audio_seconds: 3600 alternative: '' diarized_audio: summary: Two-speaker audio with speaker_diarization enabled value: text: >- Thanks for calling, how can I help? Hi, my account got locked. duration_ms: 9000 utterances: - utterance_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 text: Thanks for calling, how can I help? start_ms: 0 duration_ms: 3800 speaker: 1 - utterance_uuid: b2c3d4e5-f6a7-8901-bcde-f23456789012 text: Hi, my account got locked. start_ms: 4400 duration_ms: 2900 speaker: 2 diarized_with_timestamps: summary: Both flags enabled - word times are file-relative value: text: Thanks for calling. My account got locked. duration_ms: 9000 words: - word: Thanks start: 0.2 end: 0.61 timing: aligned confidence: 0.9881 - word: for start: 0.64 end: 0.79 timing: aligned confidence: 0.9799 - word: calling. start: 0.82 end: 1.35 timing: aligned confidence: 0.9744 - word: My start: 4.51 end: 4.68 timing: aligned confidence: 0.9702 - word: account start: 4.7 end: 5.18 timing: aligned confidence: 0.9835 - word: got start: 5.2 end: 5.39 timing: aligned confidence: 0.9781 - word: locked. start: 5.42 end: 5.94 timing: aligned confidence: 0.9668 utterances: - utterance_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 text: Thanks for calling. start_ms: 0 duration_ms: 1500 speaker: 1 words: - word: Thanks start: 0.2 end: 0.61 timing: aligned confidence: 0.9881 - word: for start: 0.64 end: 0.79 timing: aligned confidence: 0.9799 - word: calling. start: 0.82 end: 1.35 timing: aligned confidence: 0.9744 - utterance_uuid: b2c3d4e5-f6a7-8901-bcde-f23456789012 text: My account got locked. start_ms: 4400 duration_ms: 1700 speaker: 2 words: - word: My start: 4.51 end: 4.68 timing: aligned confidence: 0.9702 - word: account start: 4.7 end: 5.18 timing: aligned confidence: 0.9835 - word: got start: 5.2 end: 5.39 timing: aligned confidence: 0.9781 - word: locked. start: 5.42 end: 5.94 timing: aligned confidence: 0.9668 '400': description: > Bad request - the uploaded file is empty, its format is not supported, or the audio could not be decoded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_format: summary: Invalid file format value: detail: >- Unsupported file format. Supported formats: .3g2, .3ga, .3gp, .3gpp, .8svx, .aa3, .aac, .ac3, .act, .adts, .aif, .aifc, .aiff, .alac, .amb, .amr, .ape, .asf, .at3, .au, .avi, .avr, .awb, .bwf, .c2, .caf, .dss, .dts, .dtshd, .eac3, .ec3, .f4a, .f4b, .flac, .flv, .gsm, .iff, .m2a, .m2ts, .m4a, .m4b, .m4r, .m4v, .mka, .mkv, .mlp, .mmf, .mov, .mp+, .mp1, .mp2, .mp3, .mp4, .mpa, .mpc, .mpeg, .mpg, .mpga, .mpp, .mts, .mxf, .nist, .oga, .ogg, .ogx, .oma, .omg, .opus, .paf, .pvf, .qcp, .ra, .rf64, .rka, .rm, .rmvb, .sf, .shn, .snd, .sph, .svx, .tak, .thd, .ts, .tta, .vob, .voc, .vqf, .w64, .wav, .wave, .weba, .webm, .wma, .wmv, .wv. empty_file: summary: Empty file value: detail: The uploaded file is empty. no_audio_stream: summary: No decodable audio stream value: detail: No decodable audio stream was found in the file. unsupported_codec: summary: Unsupported audio codec value: detail: The audio codec is not supported. corrupt_file: summary: Corrupted or truncated audio file value: detail: The audio file appears to be corrupted or truncated. unprocessable: summary: Audio could not be decoded value: detail: >- The audio could not be processed. It may be corrupted or in an unsupported format. bad_value: summary: Malformed request value value: detail: Invalid request. '401': description: Unauthorized - the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: summary: Missing API key value: detail: Missing API key. invalid_api_key: summary: Invalid API key value: detail: Invalid API key. '403': description: > Forbidden - the request is not permitted, or the API key does not have access to this model. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_permitted: summary: Request not permitted value: detail: This request is not permitted. model_access_denied: summary: No access to this model value: detail: This API key does not have access to this model. '413': description: Payload too large - the uploaded file exceeds the maximum file size. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: The uploaded file is too large. '422': description: > Unprocessable entity - a required request parameter is missing or invalid (for example, the `upload_file` field). content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: > Too many requests - the request was denied due to insufficient credits, a concurrent request limit, or a monthly usage limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_credits: summary: Insufficient credits value: detail: Insufficient credits. concurrency_limit: summary: Concurrent request limit reached value: detail: >- Concurrent request limit reached. Please retry after your in-flight requests complete. monthly_limit: summary: Monthly usage limit reached value: detail: Monthly usage limit reached. '500': description: Internal server error during processing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Internal server error '502': description: Bad gateway - the request could not be completed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Unable to complete the request. Please try again. '503': description: > Service unavailable - the service is temporarily unavailable, or `speaker_diarization` was requested while diarization is disabled on this deployment. Note that `time_stamps` behaves differently: when word timings are disabled on a deployment the request still succeeds, and `words_unavailable` carries the `alignment_disabled` reason. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: >- The service is temporarily unavailable. Please try again later. '504': description: Gateway timeout - processing timed out. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: The request timed out. Please try again. security: - ApiKeyAuth: [] components: schemas: TranscriptionResponse: type: object required: - text - duration_ms properties: text: type: string description: | The complete transcribed text from the audio file. Text includes automatic capitalization and punctuation. May be an empty string if no speech was recognized. example: Hello, how are you doing today? duration_ms: type: integer minimum: 0 description: | The total duration of the processed audio in milliseconds. example: 14253 words: type: array description: | Word-level timings covering `text`, in document order. Present only when `time_stamps` is enabled and timings were produced; when they were not, `words_unavailable` is present instead. Absent otherwise, never null. Every whitespace-separated token of `text` appears here exactly once, so `words` and `text.split()` have the same length and the same order. A word the aligner could not place fully is still returned, marked `partial` or `estimated` - see `WordTime.timing`. Times are seconds from the start of the file, including when `speaker_diarization` is also enabled. Note this differs from `utterances`, whose `start_ms` and `duration_ms` are integer milliseconds. items: $ref: '#/components/schemas/WordTime' words_unavailable: allOf: - $ref: '#/components/schemas/WordsUnavailable' description: | Why `words` is absent. Present only when `time_stamps` is enabled and `words` is absent; absent otherwise, never null. Exactly one of `words` and `words_unavailable` appears on a `time_stamps=true` request. utterances: type: array description: | Time-ordered speaker turns with non-empty transcripts. Present only when `speaker_diarization` is enabled; may be an empty array when no transcribable speech is found. items: $ref: '#/components/schemas/Utterance' ErrorResponse: type: object required: - detail properties: detail: type: string description: Human-readable error message. HTTPValidationError: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationError' WordTime: type: object required: - word - start - end - timing properties: word: type: string description: | The word as it appears in `text`, including any attached punctuation and capitalization. example: Hello, start: type: number format: double minimum: 0 description: | Start time of this word in seconds from the beginning of the file, rounded to three decimal places. example: 0.12 end: type: number format: double minimum: 0 description: | End time of this word in seconds from the beginning of the file, rounded to three decimal places. example: 0.48 timing: type: string enum: - aligned - partial - estimated description: | How this word's span was obtained. Always present. - `aligned` - every audio-carrying character was placed by the aligner. `start` and `end` are measured. - `partial` - some characters are outside the aligner's vocabulary (for example the digits in "COVID-19"), so the measured span covers a prefix of the word. `end` is extended in proportion to the untimed characters and clamped to the next word's start; treat it as approximate at the tail. `confidence` is the measured value over the characters that were timed. - `estimated` - no character could be placed (for example "2024"). `start` and `end` bracket the interval between the timed neighbours, within which the word occurs; `confidence` is omitted because nothing was measured. example: aligned confidence: type: number format: double minimum: 0 maximum: 1 description: | Alignment confidence for this word in the range 0-1, rounded to four decimal places. Higher is more confident. Present whenever a confidence was measured; absent on an `estimated` word, never null. This scores how well the word was located in the audio, not whether the word is correct. Replaces `score`, which is no longer returned: a client reading `score` gets a missing key, not a value on a different scale. example: 0.9912 WordsUnavailable: type: object description: | Why word timings are absent from a response that requested them. The transcript, and any speaker turns, are unaffected. required: - reason - message - audio_seconds - max_audio_seconds - alternative properties: reason: type: string enum: - audio_too_long_for_alignment - alignment_disabled - alignment_failed - empty_transcript description: | Stable machine-readable token. Branch on this, never on `message`. - `audio_too_long_for_alignment` - the audio is longer than `max_audio_seconds`. Checked before any alignment work begins. Cannot occur when `speaker_diarization` is enabled, since that path aligns per turn and carries no length ceiling. - `alignment_disabled` - word timings are turned off on this deployment. - `alignment_failed` - the alignment pass did not produce timings for this file. Retryable. - `empty_transcript` - no speech was transcribed, so there are no words to time. example: audio_too_long_for_alignment message: type: string description: | One human-readable sentence, safe to surface in a UI. Wording may change; do not parse it. example: >- Word timings are available up to 3600s of audio; this file is 5400s. The transcript is unaffected. audio_seconds: type: number format: double minimum: 0 description: | Duration of the submitted audio in seconds, rounded to one decimal place. example: 5400 max_audio_seconds: type: number format: double minimum: 0 description: | The maximum audio length in seconds for which this deployment produces word timings on the non-diarized path, rounded to one decimal place. Configured per deployment; the default is 3600. Read this value rather than hard-coding a ceiling. example: 3600 alternative: type: string description: | What to do instead, or an empty string when there is nothing to offer. Empty is a normal value, not an error. example: >- Set speaker_diarization=true to receive word timings on audio of any length. That path aligns each speaker turn separately, so it has no length ceiling; it is slower and its transcript is produced per turn. Utterance: type: object required: - utterance_uuid - text - start_ms - duration_ms - speaker properties: utterance_uuid: type: string format: uuid description: | Unique identifier for this utterance. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 text: type: string description: | The transcribed text of this utterance, with automatic capitalization and punctuation. example: Thanks for calling, how can I help? start_ms: type: integer minimum: 0 description: | Start time of this utterance within the audio, in milliseconds. example: 0 duration_ms: type: integer minimum: 0 description: | Duration of this utterance in milliseconds. example: 3800 speaker: type: integer minimum: 1 description: | Speaker number for this utterance (1-indexed). Speaker numbers are consistent within a single audio file but may vary between different files. example: 1 words: type: array description: | Word-level timings for this utterance only. Present when both `time_stamps` and `speaker_diarization` are enabled and timings were produced for the file; absent otherwise, never null. Times are seconds from the start of the FILE, not from the start of the utterance, so they can be compared directly against the top-level `words` array. items: $ref: '#/components/schemas/WordTime' ValidationError: type: object required: - loc - msg - type properties: loc: type: array items: anyOf: - type: string - type: integer msg: type: string type: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key used for authentication and usage tracking. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.