---
title: "Voiced speech segments with timestamps"
method: POST
path: "/v1/voicelab/segments"
tags: ["VoiceLab"]
---

# Voiced speech segments with timestamps

`POST /v1/voicelab/segments`

## Request

- Base URL: `https://audiolab.tools`
- URL: `https://audiolab.tools/v1/voicelab/segments`
- Auth: HTTP bearer

List voiced speech regions with start/end timestamps and per-segment RMS level.
For auto-trim and chapter generation. RMS-based voice-activity detection:
when speech happens, not who is speaking, and not where the speaker changes.

## Request body

- object
  - `url` string, uri
  - `objectPath` string: Path returned by /api/upload-url, for audio that has no public URL. Readable only by the key that uploaded it, and kept for about an hour so a follow-up question about the same file does not need a re-upload.
  - `speechDetector` 'v1' | 'k2': Which speech detector finds the segments. v1 is the first detector and is the default until 15 January 2027; k2 lets a phrase run on into its soft word starts and endings (by at most 100 ms per side), so neighbouring segments sometimes merge into fewer, longer ones. The same keys and types in both, only the values differ. From 15 January 2027 the default becomes k2 and v1 stays selectable until at least 15 April 2027. Supported on voicelab/qa, voicelab/segments and analyze/profile.

## Response `200`

Segments complete.

- SpeechSegmentsResult: Voiced regions with timestamps. For auto-trim and chapter generation. It finds where speech is, not who is speaking or where the speaker changes.
  - `durationSec` number, required
  - `speechSec` number
  - `silenceSec` number
  - `speechRatio` number, required: 0..1 fraction of audio that is voiced.
  - `longSilences` number: Count of unusually long silences (e.g. potential dead air).
  - `segments` SpeechSegment[], required
    - `startSec` number
    - `endSec` number
    - `durationSec` number
    - `meanRmsDb` number: Mean RMS of the segment in dBFS.

## Other responses

- `400`: Malformed request, a URL we could not use, or a parameter that is not valid. Codes: url_not_allowed, url_fetch_failed, invalid_json, missing_input, invalid_parameter, batch_too_large, upload_not_found.
- `401`: Invalid or revoked API key. /v1/batch and /v1/usage always need a key; the analysis routes also run without one, as a small keyless trial. Codes: invalid_api_key.
- `402`: A limit of your plan was reached: the calls or the data of the month, or a preset that needs a paid plan. The body carries usage where it applies. Codes: quota_exceeded, data_quota_exceeded, profile_requires_paid_plan, voice_minutes_exhausted.
- `413`: File too large for the route, or a recording too long to decode. Codes: file_too_large, track_too_long.
- `429`: Too many requests this minute. See Retry-After. Codes: rate_limited.
- `500`: Something went wrong on our side. The details are logged and never sent to you. Codes: storage_unavailable, analysis_error.

---

[API](https://skmtc.dev/audiolab/apis/audiolab-api.md) · [All operations](https://skmtc.dev/audiolab/apis/audiolab-api/llms.txt) · [OpenAPI document](https://skmtc.dev/audiolab/apis/audiolab-api/revisions/69ff81f4f4ba?raw)