Developer quickstart

Make your first API request, then turn an audio recording into text. The examples use a personal API key and a terminal with curl.

Create an API key

Open the API dashboard and create a key. Review the dashboard's API billing and usage information. If you restrict the key's scopes, include dictation and transcription for the examples below.

Set an environment variable in your terminal. Replace the placeholder with your key. Keep the key on your server when you build an app.

export AQUA_API_KEY="your-api-key"
API key creation in a local demonstration account.
API key creation in a local demonstration account.

Check authentication

curl --fail-with-body https://api.aquavoice.com/v1/me \
  -H "Authorization: Bearer $AQUA_API_KEY"

The response identifies the current user and credential. A 401 response means you need to check the key and its expiry. Organization keys have additional user-selection rules. See Authentication in the API reference.

Turn speech into finished text

Save a short recording as audio.wav in your current directory. This request applies your account's dictionary, replacements, and instructions to the dictation.

curl --fail-with-body https://api.aquavoice.com/v1/dictations \
  -H "Authorization: Bearer $AQUA_API_KEY" \
  -F "audio=@audio.wav" \
  -F "operation=dictate" \
  -F "language=en"

Read the text field in the JSON response for the finished text. The response also includes session_id, language, and duration_seconds. Privacy and retention settings still apply.

For spoken edits, send operation=edit and a selected_text field with the text to change. Your audio should contain the edit instruction. The returned text is the replacement. Inspect edit_unclear and edit_deleted before applying it. See the dictation endpoint.

Transcribe an audio file with Avalon

Save your recording as audio.mp3 and call the transcription endpoint. This example returns a transcript in the text field.

curl --fail-with-body https://api.aquavoice.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $AQUA_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=avalon-v1.5" \
  -F "response_format=json"

Use response_format=srt or vtt for subtitles. For speaker labels, use diarize=true with response_format=diarized_json. For longer processing, use the asynchronous transcription endpoint.

Handle errors and retries

  • Save the response's X-Request-Id when you need support.
  • A 403 can indicate that the key lacks a required scope. Check the response body and dashboard settings.
  • For 429 responses, follow Retry-After.
  • For a dictation you may retry, send an Idempotency-Key that is unique to that recording and request. Reuse that key with the same request on a retry.
  • A synchronous transcription can return 504 request_timeout with error.job_id while processing continues. Poll that job instead of starting a duplicate.

The API reference contains request limits, response schemas, billing, and data handling. Use the CLI reference to work from the terminal without writing an integration, or MCP documentation to connect an AI app.