POST /v1/transcribe — Transcribe Audio with FluidVoice

The transcribe endpoint runs speech recognition on audio you provide and returns the resulting transcript along with a confidence score and sample count. FluidVoice uses whichever speech model you have selected in Settings → Speech Model — you do not need to specify the model in your request. The endpoint accepts three input modes. Choose whichever is most convenient for your use case.

Request

POST /v1/transcribe

Maximum request body size: 25 MB.

Mode A — File path (JSON body)

Send a JSON object with the absolute path to an audio file already on disk. FluidVoice reads the file directly — no file upload required.

curl http://localhost:47733/v1/transcribe \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/alex/Recordings/standup-notes.wav"}'

string

required

Absolute path to an audio file on disk. The file must be readable by FluidVoice. Supports any audio format that macOS AVFoundation can decode (WAV, M4A, AIFF, MP3, CAF, and others).

Mode B — Base64-encoded audio (JSON body)

Send a JSON object containing the audio data encoded as a base64 string. Include filename so FluidVoice can detect the audio format from the file extension.

curl http://localhost:47733/v1/transcribe \
  -H "Content-Type: application/json" \
  -d '{
    "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAA...",
    "filename": "recording.wav"
  }'

string

required

The raw audio file contents encoded as a standard base64 string. The decoded data must be a valid audio file in a format supported by macOS.

string

A filename (e.g. "recording.m4a") used to detect the audio format from the file extension. Defaults to "audio.wav" if omitted. Does not need to be a real file path — only the extension matters.

Mode C — Raw audio bytes (binary body)

Send the raw audio file bytes as the request body. Set Content-Type to the appropriate audio MIME type and use the X-Filename header to help FluidVoice identify the format.

curl http://localhost:47733/v1/transcribe \
  -H "Content-Type: audio/wav" \
  -H "X-Filename: recording.wav" \
  --data-binary @/Users/alex/Recordings/standup-notes.wav

string

The MIME type of the audio data, e.g. audio/wav, audio/mp4, audio/aiff. FluidVoice uses this as a hint but primarily relies on the file extension from X-Filename.

string

A filename whose extension indicates the audio format (e.g. "recording.wav", "memo.m4a"). Defaults to "audio.wav" if not provided.

Response

{
  "confidence": 0.97,
  "provider": "Parakeet Flash",
  "sampleCount": 176400,
  "text": "The deployment is scheduled for Friday at nine AM Pacific."
}

string

required

The transcribed text produced by the speech model.

number

required

A confidence score between 0.0 and 1.0 indicating how certain the model is about the transcript. Higher is more confident.

integer

required

The number of audio samples processed. Divide by the sample rate (typically 16000 for most models) to get the audio duration in seconds.

string

required

The display name of the speech model that produced the transcript, matching the model selected in FluidVoice settings (e.g. "Parakeet Flash", "Nemotron Speech 3.5", "Apple Speech").

Error responses

Status	Body	Meaning
`400`	`{"error": "Missing audio path or audioBase64."}`	The JSON body did not contain a valid `path` or `audioBase64` field.
`400`	`{"error": "Missing audio body."}`	A binary request was sent with an empty body.
`400`	`{"error": "Invalid JSON audio payload."}`	The request body could not be parsed as JSON.
`413`	`{"error": "Request too large."}`	The request body exceeds 25 MB.

The transcription model used is always the one currently active in FluidVoice. If you need to use a specific model, change it in Settings → Speech Model before calling the endpoint.

Overview

Endpoints

POST /v1/transcribe — Transcribe Audio with FluidVoice

Request

Mode A — File path (JSON body)

Mode B — Base64-encoded audio (JSON body)

Mode C — Raw audio bytes (binary body)

Response

Error responses

​Request

​Mode A — File path (JSON body)

​Mode B — Base64-encoded audio (JSON body)

​Mode C — Raw audio bytes (binary body)

​Response

​Error responses

Request

Mode A — File path (JSON body)

Mode B — Base64-encoded audio (JSON body)

Mode C — Raw audio bytes (binary body)

Response

Error responses