Download iOS

Avalon API documentation

Batch speech-to-text tuned for technical language, with official OpenAI Python and JavaScript SDK support for the contract documented here.

Create API keyAbout Avalon

Base URL

https://api.aquavoice.com/v1

Model

avalon-v1.5

Price

$0.39 per audio hour

Quickstart

Create a key in the dashboard, then call Avalon through the OpenAI SDK or multipart HTTP. Idempotency is optional.

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.aquavoice.com/v1",
)

with open("audio.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="avalon-v1.5",
        file=audio,
    )

print(transcript.text)
bash
curl https://api.aquavoice.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=avalon-v1.5"

Create transcription

POST
/v1/audio/transcriptionsmultipart/form-data

Send Authorization: Bearer YOUR_API_KEY. The file and model fields are required.

This compatibility endpoint waits for the queued job for up to 210 seconds. If it returns a timeout, processing continues; use the response's x-request-id as the job ID to check its status. For bursty or long-running work, use the async job endpoint below.

file
file
Required

Audio in flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm format. Maximum upload size is 25 MiB; decoded audio must be shorter than one hour.

model
string
Required

Must be "avalon-v1.5".

prompt
string

Context or vocabulary hints for the transcription.

language
string

ISO 639-1 language code. Omit it or use "auto" to detect the language.

response_format
string

One of "json" (default), "text", "srt", "vtt", or "verbose_json".

temperature
number

Only 0 is accepted, as a compatibility no-op. Nonzero values are unsupported.

stream
boolean

Only false is accepted. The Avalon API is batch-only.

timestamp_granularities[]
string

Only "segment" is supported, with response_format="verbose_json".

Optional header: Idempotency-Key. Reuse one 1–255 character value for every retry of the same logical request. Matching completed requests replay for 24 hours without another inference or charge.

Optional header: X-Client-Request-Id for your own correlation. It does not provide idempotency.

Responses

The default json response contains the transcript and duration usage.

json
{
  "text": "Transcribed text",
  "usage": {
    "type": "duration",
    "seconds": 12.34
  }
}

Text and subtitles

text returns plain text. srt and vtt use Avalon's segment timing.

Verbose JSON

Guarantees task, detected language, duration, text, usage, and segment id/start/end/text.

Every response includes x-request-id. Errors use the OpenAI-style envelope below.

json
{
  "error": {
    "message": "Safe customer-facing message",
    "type": "invalid_request_error",
    "param": "file",
    "code": "invalid_audio"
  }
}

Async jobs

API inference runs at low priority behind Aqua Voice dictation. Submit bursty workloads as durable jobs so your client does not need to hold a connection open while work waits for capacity.

Each account's concurrency limit controls how many of its jobs may run at once. Additional jobs remain queued instead of being rejected.

POST
/v1/audio/transcription-jobssame multipart fields as create transcription
bash
curl https://api.aquavoice.com/v1/audio/transcription-jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=avalon-v1.5"

A successful submission returns 202 with a durable job record.

json
{
  "id": "req_...",
  "object": "transcription.job",
  "status": "queued",
  "created_at": "2026-08-04T14:43:47Z",
  "completed_at": null,
  "audio_duration_seconds": 12.34,
  "error_code": null,
  "result_url": null
}

Get status with GET /v1/audio/transcription-jobs/{job_id}. While work is pending, status is queued. A completed job includes its terminal status and a result_url.

Fetch the transcription from GET /v1/audio/transcription-jobs/{job_id}/result. Before completion it returns a retryable 409; after completion it uses the requested response format. All job endpoints require the same API key and only expose that account's jobs.

OpenAI compatibility

Avalon implements a compatible subset of OpenAI's batch transcription contract. It is not a drop-in replacement for every OpenAI audio feature.

Supported

  • Official OpenAI Python and JavaScript SDKs
  • JSON, text, SRT, VTT, and partial verbose JSON
  • Segment timestamps
  • temperature=0 and stream=false

Not supported

  • Streaming or word timestamps
  • Diarization or known speakers
  • Nonzero temperature or token logprobs
  • Full verbose diagnostics
  • Keyword arrays, multiple-language hints, or custom VAD
  • Translations, realtime, or other model IDs

Unsupported parameters return a structured 400 error naming the parameter; they are not silently ignored.

Retries and idempotency

Errors include x-should-retry. Retryable throttling and in-progress idempotent requests also include Retry-After.

Without Idempotency-Key, every attempt is an independent inference and billable request. With a key, matching successful and deterministic client-error responses replay for 24 hours. Reusing a key for different request content returns 409.

Billing is $0.39 per audio hour, measured per second with a 10-second minimum per request. Account request and concurrency limits are returned in x-ratelimit-* headers.

Migration from the legacy Avalon API

  • Use the canonical /v1/audio/transcriptions path. The old /api/v1/audio/transcriptions path remains an alias to the new contract.
  • Send model=avalon-v1.5; the model is required and Avalon v1 is retired.
  • Read request correlation from the x-request-id response header.
  • Expect unknown or unsupported parameters to return structured errors instead of being ignored.