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.

{
  "app": "Slack",
  "app_bundle_id": "com.tinyspeck.slackmacgap",
  "focused_element_description": "Message field",
  "dictionary": "[\"Aqua Voice\", \"Kubernetes\"]",
  "replacements": "[{\"from\": \"AV\", \"to\": \"Aqua Voice\"}]",
  "instructions": "Use British spelling."
}

{
  "session_id": "ses_a1e2c85b1cbf43af9dc678a1a7423dcc",
  "raw_text": "hello aqua can you send the update",
  "text": "Hello, Aqua! Can you send the update?",
  "duration_seconds": 2.84
}