---
title: "Dictate or edit text"
method: POST
path: "/dictations"
tags: ["dictation"]
---

# Dictate or edit text

`POST /dictations`

## Request

- Base URL: `https://api.aquavoice.com/v1`
- URL: `https://api.aquavoice.com/v1/dictations`
- Auth: HTTP bearer

Runs Aqua's normal dictation pipeline and returns when the text is
ready. The request stays open while Aqua transcribes and formats the
audio, for up to 210 seconds. It does not create a public background
job. Send an `Idempotency-Key` and retry the same request with the same
key if the connection closes. A terminal result replays for 24 hours
without another inference or charge. On a zero-data-retention account,
it replays for 10 minutes. After Aqua dispatches the audio,
an uncertain upstream failure is terminal for that key so a retry cannot
create a second dictation. If Aqua cannot send the audio for
processing, the error is retryable and has a `Retry-After` header. A
retry with the same key runs the dictation again.

Aqua applies the user's language setting, dictionary, replacements,
custom instructions, and casual messaging preference. A request
`language` overrides the saved language for this
dictation. The returned `session_id` identifies the session stored in
Aqua history. Privacy and zero-data-retention settings still apply: the
text is returned to the caller but is not stored when retention is off.
A zero-data-retention account always applies them; see Data handling.

An organization key acts as one member: send `Aqua-User` with the
member's user id. The dictation is billed to the account that owns the
key.

A platform key uses no stored personalization. Send `dictionary`,
`replacements`, `instructions`, and `casual_messaging` with each
dictation; Aqua uses them for that dictation only and does not store
them. Aqua keeps no session for the dictation, so `session_id` is
`null`. Send `Aqua-End-User` to identify your end user. One end user
can have 2 dictations in progress at the same time; more return
`429 end_user_concurrency_limit_exceeded`. Other accounts that send
these fields or this header get `400 platform_only_parameter`.

Use `operation=edit` with `selected_text` to run Edit Mode. The optional
text and app fields give Aqua the same surrounding context it uses when
dictating into an app.

Dictate and Edit Mode bill at the same rate; see Billing.

Every response, a success or an error, has an `X-Request-Id` header.
Give this ID to Aqua support to find the request. A replayed response
has the ID of the original request.

## Headers

- `Idempotency-Key` string
- `Aqua-User` string
- `Aqua-End-User` string

## Request body `multipart/form-data`

- DictationRequest
  - `audio` string, binary, required: A canonical 16 kHz mono PCM16 WAV file, or a mono or stereo Ogg Opus file. Aqua decodes Opus audio to 16 kHz mono PCM16. The 10-minute limit and billing use the decoded duration. The maximum size of an Opus file is 19.2 MB. Use an Opus bitrate of more than 48 kbps, because short clips at lower bitrates can give empty text.
  - `operation` 'dictate' | 'edit': Use `edit` to apply the spoken instruction to `selected_text`.
  - `selected_text` string: Required when `operation` is `edit`.
  - `language` 'auto' | 'ar' | 'be' | 'bn' | 'bg' | 'yue' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'gl' | 'de' | 'el' | 'he' | 'hi' | 'hu' | 'id' | 'ga' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mt' | 'cmn' | 'mr' | 'mn' | 'no' | 'fa' | 'pl' | 'pt' | 'ro' | 'ru' | 'sl' | 'es' | 'sw' | 'sv' | 'ta' | 'th' | 'tr' | 'uk' | 'ur' | 'vi' | 'cy' | 'yi'
  - `app` string: Name of the app where the text will be used.
  - `app_bundle_id` string: Bundle ID or package name for the app.
  - `text_before` string: Text immediately before the insertion or selection.
  - `text_after` string: Text immediately after the insertion or selection.
  - `focused_element_description` string: Accessible description of the target text field.
  - `dictionary` string: Platform keys only. A JSON array of up to 1,000 terms that speech recognition and formatting must spell correctly. Each term has 1–100 characters.
  - `replacements` string: Platform keys only. A JSON array of up to 200 `{"from", "to"}` pairs. Aqua replaces each `from` phrase with its `to` text in a dictation. Each value has 1–100 characters.
  - `instructions` string: Platform keys only. Custom instructions for the formatting of the text.
  - `casual_messaging` 'true' | 'false': Platform keys only. Writes short messages in a casual style, as the casual messaging setting does in the Aqua app.

## Response `200`

The completed Aqua dictation or edit.

- DictationResult
  - `object` 'dictation', required
  - `session_id` string, nullable, required: The session that Aqua stored in history. It is `null` for a platform account, because Aqua keeps no session for its dictations.
  - `operation` 'dictate' | 'edit', required
  - `raw_text` string, required: Speech recognition output before Aqua formatting.
  - `text` string, required: Final Aqua text, ready to insert or use as the edit replacement.
  - `language` 'auto' | 'ar' | 'be' | 'bn' | 'bg' | 'yue' | 'ca' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'gl' | 'de' | 'el' | 'he' | 'hi' | 'hu' | 'id' | 'ga' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ms' | 'mt' | 'cmn' | 'mr' | 'mn' | 'no' | 'fa' | 'pl' | 'pt' | 'ro' | 'ru' | 'sl' | 'es' | 'sw' | 'sv' | 'ta' | 'th' | 'tr' | 'uk' | 'ur' | 'vi' | 'cy' | 'yi', required
  - `duration_seconds` number, required
  - `edit_unclear` boolean, required: True when Edit Mode could not determine the requested change.
  - `edit_deleted` boolean, required: True when Edit Mode intentionally removed the selected text.

## Other responses

- `default`: Product API error.

---

[API](https://skmtc.dev/aquavoice/apis/aqua-api.md) - [All operations](https://skmtc.dev/aquavoice/apis/aqua-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aquavoice/apis/aqua-api/revisions/f0139c07aded?raw)