Transcription

Our akro-v1 model is a comprehensive listening model that performs:

• Transcription — Convert speech to text with high accuracy
• Speaker Diarization — Identify and separate different speakers ("who said what")
• Non-Speech Detection — Capture breathing, laughter, hesitation, and other contextual sounds

This makes it ideal for transcribing meetings, interviews, podcasts, and any audio where understanding the full context matters.

All transcription endpoints require authentication — see Overview for API key setup.

Pricing: $0.20 per hour of audio processed, billed by the second, with a $0.01 minimum per request.

The floor covers per-request overhead, and it binds on anything under 3 minutes — a 5-second clip costs the same $0.01 as a 3-minute one. If you are sending many short utterances (a live voice agent, say), concatenate them into fewer, longer requests to pay the per-second rate rather than the floor. See pricing.

POST /transcriptions — Submit Transcription

Submit audio and get a job ID back immediately. Poll /transcriptions/{id} for the results: transcription, speaker diarization, and non-speech events.

Send the audio in one of two ways:

• The file itself as the request body — any common audio format, up to 100 MB.
• A URL to a file you already host (S3, GCS, a CDN): JSON {"url": "https://..."}, up to 1 GiB. We fetch it, so it must be publicly reachable or presigned, and served with a Content-Length.

Parameters

Query parameters for a file upload; JSON fields alongside url for a URL submit.

Submitting a file you have already transcribed with the same settings completes at once from the earlier result, at no charge.

Request

Upload a file:

Or submit a URL:

Response

Errors

The charge itself is made when processing starts, once the audio's duration is known. If your balance can't cover it, the job ends with status: "failed" and an error_message saying how much was needed.

Workflow

1. Submit audio to POST /transcriptions and receive a job ID
2. Poll /transcriptions/{id} to check status
3. When status is "completed", retrieve full results

GET /transcriptions/{id} — Get Transcription Results

Retrieve the full results for a specific job: transcription, speaker diarization, and non-speech events.

Parameters

Request

Response

Status Values

• submitted — Job has been submitted
• processing — Transcription in progress
• completed — Transcription finished successfully
• failed — Transcription failed (check error_message — e.g. undecodable audio, or a balance that couldn't cover the charge)

GET /transcriptions — List Transcriptions

List all transcriptions for your account.

Parameters

Request

Response

Response Format

Text Field

The text field contains the full transcription with speaker labels and optional non-speech events:

• Speaker Labels: SPEAKER_0:, SPEAKER_1:, etc. prefix each speaker's utterances
• Line Breaks: Newlines (\n) separate different speaker turns
• Non-speech Events: When enabled, events like [breath], [pause] appear inline

Example:

Segments Array

The segments array provides precise timing and speaker information for each utterance:

• speaker: Speaker ID as a string ("0", "1", etc.)
• text: The spoken text for this segment (without non-speech events)
• start: Start time in seconds (decimal precision)
• end: End time in seconds (decimal precision)
• segment_idx: Sequential index for this segment

Non-Speech Events

When non_speech=true, our listening model captures various non-speech sounds and events that provide additional context to the conversation.

Common Non-Speech Sounds

Usage Notes

• Non-speech events are placed inline with the transcribed text
• Events appear at their natural position in the conversation flow
• Word elongation is marked with ellipsis: um... so... I think...
• Emphasis on words uses asterisks: I *really* think so

Speech

Hosted VUI — expressive, low-latency text-to-speech. Send text, get back audio in a natural voice, with support for non-verbal cues like [sigh] and [laugh].

Two ways to render text:

• HTTP (POST /v1/tts) — one request, one render. Simplest to integrate.
• WebSocket (/v1/tts/ws) — keep a warm socket open across renders so each one skips the TLS/TCP handshake and reaches first audio sooner. Use this for interactive UIs.

Pricing: $9 per 1M characters (≈ $0.48 per hour of audio). See pricing.

Base URL

Speech is served through the unified Fluxions API gateway under the /vui namespace:

Authentication

All speech endpoints require your API key in the Authorization header — see Overview for API key setup.

Over WebSocket the key rides on the connection: send it as the Authorization header on the handshake, or as ?token=YOUR_API_KEY on the URL from a browser.

GET /voices — List Voices

List the built-in voices.

Request

Response

Pass any voice_id as the voice field when rendering. preview_text is what that voice's sample says: GET /vui/voices/<voice_id>/sample.wav.

POST /v1/tts — Render (HTTP)

Synthesize speech from text. Returns a complete WAV by default, or streams audio chunk-by-chunk when stream=1.

Parameters

JSON body:

Request

Response

200 OK with the audio bytes. Content-Type is audio/wav (or audio/L16 when response_format is "pcm").

Streaming

Add stream=1 (query param or body field) to receive audio as it's generated, delivered as chunked transfer encoding.

By default each chunk streams the instant the model produces it, so first bytes land within ~80 ms. Set verify_chunks: true to have each chunk checked — and re-rendered if it misreads the text — before it streams: first audio then lands once the first chunk is rendered and verified (~0.5–1 s for a typical sentence), and later chunks are checked while the next one renders.

WebSocket /v1/tts/ws — Render (warm socket)

Identical render logic to POST /v1/tts, but the socket stays open between renders. Hold it open and the TLS/TCP/tunnel handshake is paid once — each subsequent speak goes straight to synthesis. Ideal for typing UIs or back-to-back lines.

Audio is delivered as binary frames of s16le PCM, mono, 24 kHz (no WAV header — assemble it yourself if you need a file).

Protocol

Client → server (text JSON):

max_secs and verify_chunks are optional. verify_chunks defaults to false (lowest latency); set it true to check each chunk before it plays (see Streaming).

Authentication. The key is checked once, when the socket opens — send Authorization: YOUR_API_KEY on the handshake. Browsers can't set headers on a WebSocket, so from browser JS pass it on the URL instead: wss://api.fluxions.ai/vui/v1/tts/ws?token=YOUR_API_KEY. Every speak on that socket is then authenticated, including renders with your own cloned voices.

Server → client:

One render = one speak → start → binary PCM* → done. Send another speak on the same socket to render again.

Request

Conversation context

By default every speak renders from the voice alone. For a voice agent, open the socket in conversation mode instead: the voice then hears the conversation so far — what the caller said and what it said itself — and replies in context, the way a person carries tone and pacing from one turn to the next.

Send session.update as the first message. The voice is fixed for the life of the socket.

language is optional. The server answers {"type": "session.updated", "voice": "<id>", "context": true, "caller_audio": true} — caller_audio says whether this server uses caller audio (if false, send text only; binary frames are ignored). Then:

The server replies to each speak with start, binary PCM and done, as above. An interrupt is answered with {"type": "interrupted", "kept_ms": ...}: what stays in context is cut on a phrase boundary, so kept_ms is at most played_ms. A reset is answered with {"type": "reset.done"}. Errors are {"type": "error", "code": "...", "message": "..."}. bad_request (a malformed message) and rate_limited / insufficient_credits (that speak was not rendered) leave the socket open; no_slot means there was no capacity to open the conversation, and the socket closes — retry shortly.

Messages apply in the order you send them: queue a user and three speaks back to back and they render in that order. interrupt and reset also drop any speak still waiting its turn.

Audio the caller speaks over a reply (barge-in) belongs to their next turn: stream it, send interrupt, then user when they finish.

Caller audio or text only? Text is enough and is the safer default. Sending the caller's audio as well lets the voice react to how something was said, but a caller's voice can occasionally colour the reply.

Non-Verbal Cues

Wrap a cue in square brackets inside input and the model renders it as an expressive sound rather than reading the word aloud:

Example: "[gasp] you did NOT just put pineapple on that pizza! [laugh] okay, okay."

Voices

Render with any built-in voice from GET /voices, or clone a custom voice from a short reference clip. Cloned voices are private to your account — render them exactly like a built-in one, with your API key on the request.

POST /v1/voices — Clone a Voice

Upload a reference clip plus its transcript; the model encodes a private voice you can render with. Sent as multipart/form-data.

Leave text out and the server runs your clip through transcription automatically — so the simplest clone is just an audio file. Pass text yourself when you want exact control over the transcript.

Response: { "voice_id": "u-<user>-<hash>", "name": "My Voice", "frames": 173, "seconds": 13.8 }. Pass the returned voice_id as voice in any render call (with your token).

GET /v1/voices/mine — List Your Cloned Voices

Returns { "voices": [ { "voice_id": "u-...-ab12cd34", "name": "My Voice" } ] }.

POST /v1/voices/delete — Remove a Cloned Voice

Note: cloned voices currently live in the running server's memory, not a database — they're tied to your account but are not guaranteed to survive a server restart. Re-upload if a voice_id stops resolving.

Output Format

• Sample rate: 24,000 Hz
• Channels: mono
• Sample format: signed 16-bit little-endian PCM
• HTTP wav: PCM wrapped in a standard WAV container
• HTTP pcm / WebSocket binary frames: raw s16le PCM (no header)

History

The History API is one read-only surface over everything you've done on the platform — transcriptions, TTS renders, and voice conversations — under a single host. Use it to list, page, filter, and search your activity, and to fetch download links for the underlying audio and transcripts.

All history endpoints require authentication — see Overview for API key setup.

Base URL: https://api.fluxions.ai

One shape for everything

Every list response uses the same envelope:

Every item carries an object field telling you its type ("transcription", "tts", or "conversation") plus its native id. To fetch one item's detail, call /history/{type}s/{id} (e.g. /history/tts/123). Timestamps are ISO-8601 UTC; costs are in US dollars.

Shared query parameters

These work on every collection (and the unified feed):

Collection-specific filters: voice (tts, conversations), status (transcriptions), type (the unified feed).

GET /history — Unified Feed

A merged, reverse-chronological feed across all three types. Filter the streams with type (comma-separated).

Parameters

(plus all shared parameters above)

Request

Response

The feed is lightweight: it does not include presigned download_urls. Use the typed collection or detail endpoints to get them.

GET /history/transcriptions — Transcription History

List your transcriptions.

Parameters

(plus all shared parameters)

Request

Response

GET /history/transcriptions/{id} — One Transcription

Returns the full record with presigned download_url (audio), text_url, and segments_url. 404 if it isn't yours.

GET /history/tts — TTS Render History

List your text-to-speech renders.

Parameters

(plus all shared parameters)

Request

Response

GET /history/tts/{id} — One Render

Returns one render with a fresh signed download_url. 404 if it isn't yours.

GET /history/conversations — Conversation History

List your voice conversations (agent calls).

Parameters

(plus all shared parameters)

Request

Response

GET /history/conversations/{id} — One Conversation

Returns the session plus its turn-by-turn transcript. 404 if it isn't yours.

Parameters

Request

Response

GET /history/conversations/search — Search Turns

Full-text search across your conversation turns (Postgres websearch_to_tsquery).

Parameters

Request

Response

GET /history/search — Cross-Domain Search

Search across your whole history in one call. Conversation turns are matched by full text; transcriptions are matched by filename (their text lives in object storage, not the database). Results are type-tagged via object.

Parameters

Request

Response

Errors

Every failed request returns a JSON body with a detail field and a meaningful HTTP status:

Check the status code first — it tells you whether to fix the request, top up, or retry.

401 — Bad or missing key

The key didn't resolve to an account. Check that you're sending the whole key, that it hasn't been revoked, and that the header reached us — some HTTP clients drop Authorization when following a redirect.

402 — Out of credits

Speech:

Transcription refuses a submit when the balance is below its $0.01 minimum, and returns the shortfall so you can show it to a user:

Top up at billing; the same request then succeeds.

The full charge is made when a transcription starts processing, so a job longer than your balance covers ends failed, with the same message in its error_message.

To avoid hitting this at all, poll GET /billing/balance (see Overview) and top up when gated turns true — the speech 402 above carries no balance, so it tells you that you have run out but not by how much.

403 — No key on the request

The request arrived with no Authorization header at all. Send your API key — see Overview.

404 — Unknown voice

Voice ids are exact and include the serving checkpoint's suffix, which changes when we ship a new model. Don't hard-code one from an old integration — read the current id from GET /voices and pass it straight through.

A 404 {"detail": "Not Found"} with no further text means the path itself doesn't exist: check the service prefix (/vui, /akro) and the version segment.

400 / 422 — Bad request body

400 means a required field was absent; 422 means a field was present but out of range or the wrong type (the body then lists the offending fields). Both are deterministic — retrying without changing the request will fail identically.

429 — Rate limited

Back off and retry. Exponential backoff starting around one second is plenty; a burst that trips this will usually clear within a few seconds.

502 / 503 — Capacity

A model server is restarting or every worker is busy. These are transient: retry the identical request after a short pause rather than treating it as a bad request.

WebSocket errors

The speech WebSocket reports failures two ways.

A render that fails leaves the socket open and sends an error frame — send another speak when you've fixed the input:

A connection that isn't authenticated is closed immediately with code 1008 (policy violation), before any speak is read. The key is checked when the socket opens, so a credential sent inside the first message is too late — put it on the handshake as the Authorization header, or on the URL as ?token=.

Cold starts

The GPU fleet powers down when idle. The first request after a quiet period is held at the gateway while a machine comes up — expect up to ~30 seconds, then normal latency for subsequent calls. Set your client timeout accordingly; a short timeout will look like a hang or a 502 when the request would have succeeded.