Aqua API - Dictation, Transcription, and MCP for Developers

API routes

Use Aqua product routes for dictation, session history, and user settings. Use Avalon routes for OpenAI-compatible transcription. Both use api.aquavoice.com and the same API key.

Aqua product routes

Dictate and edit text with the user's own preferences, read stored sessions, and manage dictionary terms, replacements, custom instructions, and app settings. Aqua object shapes, one consistent error envelope, and rate-limit headers on every response.

POST /v1/dictations

GET /v1/sessions

GET /v1/me

GET /v1/customizations

Avalon transcription routes

Batch speech-to-text with avalon-v1.5. OpenAI request, response, and error shapes, ready for the official SDKs. Run requests synchronously or as durable async jobs.

POST /v1/audio/transcriptions

POST /v1/audio/transcription-jobs

GET /v1/models

Dictation and voice editing

POST /v1/dictations applies the user's language setting, dictionary, replacements, custom instructions, and learned preferences, then returns text ready to insert.

Voice editing built in: send operation=edit with the selected text and Aqua applies the spoken instruction, with the same app context the desktop app uses.

Sessions land in Aqua history: each result carries a session ID, and stored sessions expose transcripts, summaries, and action items.

Privacy is honored end to end: with retention off, the text is returned to the caller and nothing is stored.

cURL

curl https://api.aquavoice.com/v1/dictations \  -H "Authorization: Bearer $AQUA_API_KEY" \  -H "Idempotency-Key: update-note-118" \  -F "audio=@dictation.wav" \  -F "operation=dictate"# {#   "raw_text": "hello aqua can you send the update",#   "text": "Hello, Aqua! Can you send the update?",#   "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",#   "duration_seconds": 2.84, ...# }

OpenAI-compatible transcription

The transcription routes serve avalon-v1.5, the latest version of Avalon, the model that debuted #1 among proprietary models on the public OpenASR leaderboard in October 2025 at 6.24% average word error rate and scores 97.3% on AISpeak, our benchmark of AI and coding terms. Swap the base URL and model name, and the official OpenAI SDKs work unchanged.

Python

from openai import OpenAIclient = OpenAI(    api_key="your-avalon-api-key",    base_url="https://api.aquavoice.com/v1")transcript = client.audio.transcriptions.create(    model="avalon-v1.5",    file=open("speech.mp3", "rb"),)print(transcript.text)

Nine audio formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, and webm, up to 25 MiB and one hour of audio.

Five response formats: json, text, srt, vtt, and verbose_json with segment timestamps.

Synchronous requests, or async jobs that return 202 with a durable job ID you can poll.

Try in Playground →

Full benchmarks, hallucination examples, and the model story live on the Avalon page.

Requests and errors

Idempotent by design

Send an Idempotency-Key and retry safely. A terminal result replays for 24 hours without another inference or charge, and a retry can never create a duplicate dictation.

Durable async jobs

Transcription jobs return 202 with a job ID and stay durably queued for up to 72 hours. If a synchronous request times out after the job is stored, the error includes the job ID so the work is never lost.

Rate limits in the open

Responses carry rate-limit headers for both requests and concurrency, so your client can pace itself instead of guessing.

Errors built for retries

Stable error codes with explicit retryable semantics: OpenAI error shapes on transcription routes, one predictable envelope on product routes.

Health you can poll

GET /v1/health reports public service readiness. GET /v1/health/functional is backed by a real end-to-end transcription canary that runs every minute.

API keys

One key covers dictation, sessions, MCP, and transcription. An organization key acts as a member through the Aqua-User header. Full keys are shown only once, and each account can hold up to 30 keys.

Connect your AI agent over MCP

Aqua is also a remote MCP server. Point Claude, ChatGPT, or Codex at the endpoint below and your agent gets ten tools over OAuth: read sessions and transcripts, file feedback that can teach Aqua a correction when learned preferences are enabled, manage dictionary terms, and update settings.

MCP endpoint

https://api.aquavoice.com/mcp

Aqua MCP is in limited access. Your AI provider must support remote MCP and may require workspace admin approval. Read access is requested first; write access requires separate approval.

MCP connection guide

Usage pricing

Your first $1.00 of usage is free. After that, pay for the audio you process.

Avalon transcription: $0.39 per audio hour
Aqua dictation: $0.49 per audio hour

Billed per second, 10-second minimum
Dictate and Edit Mode share one rate
Failed requests and idempotent replays are never billed
No seat fees

Create an API key

Frequently asked questions

What is the difference between the Aqua API and the Avalon API?

Avalon is Aqua's speech-to-text model, served on the OpenAI-compatible transcription routes. The Aqua API is the whole platform around it: personalized dictation and voice editing, stored sessions with transcripts and summaries, dictionary and settings management, and the MCP server for AI agents, alongside those transcription routes.

Is the Aqua API OpenAI-compatible?

The transcription routes are: they keep OpenAI request, response, and error shapes, so the official OpenAI SDKs work unchanged after swapping the base URL and model name. The product routes for dictation, sessions, customizations, and settings use Aqua object shapes with one consistent error envelope.

How do I get an API key?

Create a key in the Aqua API dashboard. One key covers dictation, sessions, customizations, settings, MCP, and transcription. Your account activates with the first key, and the first $1.00 of usage is free, so the first request needs no card. Each account can hold up to 30 keys.

Which languages does the API support?

Dictation supports 50 languages plus automatic detection. Transcription accepts any ISO 639-1 language code as a hint, or detects the language automatically.

What does Aqua store from an API dictation?

That depends on the user's privacy and zero-data-retention settings, which the API respects. When retention is off, the result goes to the caller and no session is kept. When history is available, the dictation is stored as a session in Aqua history, identified by the session ID in the response.