---
title: "Record an audio clip"
method: POST
path: "/v1/audio/record"
tags: ["Audio"]
---

# Record an audio clip

`POST /v1/audio/record`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/audio/record`
- Auth: HTTP bearer

Captures audio via the AudioPiper companion app. `mode=clip` records N seconds starting now and returns base64 WAV (or writes to `save_path` if provided). `mode=status` returns the current AudioPiper mixer state. Optionally pipes the clip through speech-to-text via `return_transcript: true`. Inline payloads capped at 25 MB; max duration 600 s (10 min).

## Request body

- AudioRecordRequest
  - `mode` 'clip' | 'status': Capture mode. Default `clip`.
  - `duration_seconds` number: Clip length in seconds. Default 30. Max 600 (10 min). `mode=clip` only.
  - `save_path` string: Absolute path to write WAV. If omitted, returns base64 (capped at 25 MB). `mode=clip` only.
  - `return_transcript` boolean: Also run transcribe on the captured audio and return text. `mode=clip` only. Default false.

## Response `200`

Captured clip or AudioPiper status

- AudioRecordResponse
  - `mode` 'clip' | 'status', required
  - `duration_seconds` number
  - `bytes` integer
  - `audio_base64` string: Base64-encoded WAV (omitted when `path` is set or `mode=status`)
  - `path` string: Absolute path written to disk (omitted when `audio_base64` is set or `mode=status`)
  - `transcript` string: Speech-to-text result (only when `return_transcript: true` and STT succeeded)
  - `transcript_error` string: STT error message (only when `return_transcript: true` and STT failed)
  - `status` object: AudioPiper mixer state (only when `mode=status`)

## Other responses

- `400`: Invalid request
- `403`: save_path not writable
- `413`: Inline payload exceeds 25 MB — re-request with save_path
- `424`: AudioPiper companion app not installed
- `502`: AudioPiper returned a malformed or unexpected response
- `503`: AudioPiper failed to launch

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)