Speech recognition

Endpoint and API key

POST /v1/audio/transcriptions uses Authorization: Bearer YOUR_API_KEY. Use a key bound to a balance-based Audio group; subscription groups are not supported.

Use async: true for both STT and TTS. Submission returns task_id; poll the task without keeping the original connection open. Synchronous models also support async submission.

Use GET /v1/models with your key to find available model IDs. Check Models (/models) for current prices, billing units and group or personal multipliers. Format support and parameter restrictions depend on the model; see the exceptions below.

curl --max-time 190 "https://apixly.ai/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Async tasks

Use async: true for both STT and TTS. Submission returns task_id; poll the task without keeping the original connection open. Synchronous models also support async submission.

A model that requires asynchronous execution rejects synchronous requests with 400 async_required before creating an upstream task or charging. Check GET /v1/audio/config for supported execution modes.

waiting means queued; in_progress means processing; only success confirms completion. TTS audio is in output.result or output.file_url; STT results are in output.transcription. Download audio before expires_at.

Use a unique Idempotency-Key per generation. After a disconnect, reuse the original key and identical parameters or query task_id. Cancelling an unstarted queued task releases its reservation; submitted tasks need confirmed cancellation. unknown is not a confirmed free failure: keep the task ID and check with support.

curl "https://apixly.ai/v1/task/TASK_ID" -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://apixly.ai/v1/task/TASK_ID/cancel" -H "Authorization: Bearer YOUR_API_KEY"

Parameters and output formats

Endpoint response_format options are json (default), text, verbose_json, srt and vtt. Use a format supported by your selected model. Provide model and exactly one audio source.

language, prompt, temperature and timestamp_granularities[] are optional and model-dependent. Enable only parameters supported by the selected model; see the exceptions below.

Upload an audio file

Replace YOUR_AUDIO_MODEL with an available transcription model from GET /v1/models. Replace YOUR_API_KEY and the filename or public URL in the examples. curl sets the multipart boundary automatically; do not set Content-Type manually with -F.

curl --max-time 190 "https://apixly.ai/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: UNIQUE_GENERATION_ID" \
  -F 'model=YOUR_AUDIO_MODEL' \
  -F '[email protected]' \
  -F 'response_format=json' \
  -F 'async=true'

Use a public audio URL

For multipart/form-data, use file for a local upload, or file/file_url for an HTTP/HTTPS audio URL. JSON accepts model and file_url, as shown below; replace the sample URL.

URLs must be directly accessible on the public internet. Private addresses and URLs containing a username or password are rejected.

curl --max-time 190 "https://apixly.ai/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: UNIQUE_GENERATION_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_AUDIO_MODEL","file_url":"https://example.com/recording.wav","async":true}'

Billing

Billing method, unit and price depend on the selected model. Check Models (/models) for the current price and any group or personal multipliers. Do not infer charges from HTTP latency or the response format.

Submission reserves the estimated fee at the model price, billing unit and discount fixed for this task. Queuing is not final charging. Completed work is settled once; the final USD amount appears in usage.cost_request and usage records.

Model-specific exceptions

File limits and timeouts

• Audio must be decodable; supported file formats depend on the model. The default upload limit is 25 MiB, subject to gateway configuration. If conversion is needed, the converted file must also fit the limit.
• For models supporting synchronous HTTP, omit async or set it to false and keep the connection open. The STT processing deadline is 180 seconds. Longer jobs should use async: true.
• HTTP, async and realtime WebSocket capabilities depend on the model and are listed by GET /v1/audio/config.

Response examples

JSON contains text; text returns plain text, verbose_json includes timestamps, and srt/vtt return subtitles. Empty text may be a valid successful result for silence and is billed normally. Save the response X-Client-Request-ID for support and usage reconciliation.

waiting means queued; in_progress means processing; only success confirms completion. TTS audio is in output.result or output.file_url; STT results are in output.transcription. Download audio before expires_at.

{"text":"Hello, this is a short audio test. The number is forty two."}

1
00:00:00,000 --> 00:00:03,840
Hello, this is a short audio test. The number is forty two.

Errors and safe resubmission

Use a unique Idempotency-Key per generation. After a disconnect, reuse the original key and identical parameters or query task_id. Cancelling an unstarted queued task releases its reservation; submitted tasks need confirmed cancellation. unknown is not a confirmed free failure: keep the task ID and check with support.

Additional endpoints and model limits

Check model access and account enablement; endpoint registration alone does not mean every model or account supports it.

POST /v1/audio/translations accepts whisper-base, whisper-large and whisper-large-v3 with the same file/file_url and response_format inputs as transcription. It translates speech into English; it is not general text translation.

POST /v1/audio/voice-feature-extraction accepts audio input and prompt and returns application/octet-stream. It requires an account with native Audio extensions enabled. Store the binary as data; never execute or deserialize untrusted artifacts.

GET /v1/audio/speech/ws and GET /v1/audio/transcriptions/ws require a WebSocket upgrade, an Audio key and an extension-enabled account. Use ?model=TeleASR-MultiDialect for STT or TeleTTS-Mandarin / TeleTTS-MultiDialect / TeleTTS-Bidirectional-Mandarin for TTS. The native start frame selects the same model and 16-bit mono PCM; this is not the OpenAI Realtime event protocol. HTTP audio enablement does not enable WebSocket audio. GET /v1/audio/config currently lists HTTP operations, not these gated extensions.

POST /v1/async/music/generations is an account-enabled music extension (ACE-Step-v1-3.5B), accepting JSON or multipart src_audio/reference_audio uploads. Do not send TTS text to a model unless its own contract supports it. Poll GET /v1/task/{id}; POST /v1/task/{id}/reconcile only refreshes authoritative task/settlement state and does not create a new generation. Idempotency-Key remains required for safe retries.

POST /v1/async/audio/speech and POST /v1/async/audio/transcriptions are dedicated submission endpoints for the same Audio task lifecycle; async:true on the ordinary endpoints uses that lifecycle too. No /v1/async/audio/translations alias is registered: use /v1/audio/translations with async:true.

curl https://apixly.ai/v1/audio/translations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: UNIQUE_TRANSLATION_ID" \
  -F 'model=whisper-large-v3' \
  -F '[email protected]' \
  -F 'response_format=json' \
  -F 'async=true'
# Poll returned task_id with GET /v1/task/TASK_ID.

# Only on extension-enabled accounts; this returns binary data, not text.
curl https://apixly.ai/v1/audio/voice-feature-extraction \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'model=YOUR_VOICE_FEATURE_MODEL' \
  -F '[email protected]' \
  -F 'prompt=The exact words spoken in the recording.' \
  -o voice-feature.bin

# Refresh authoritative state; this does not submit another generation.
curl -X POST https://apixly.ai/v1/task/TASK_ID/reconcile \
  -H "Authorization: Bearer YOUR_API_KEY"

Model-specific request contracts

Discover available IDs with GET /v1/models using your key. The public price catalog is not a guarantee of current routing. Existing valid requests need no changes; optional fields are model-specific.

whisper-large-v3 supports POST /v1/audio/translations (English target). It is distinct from whisper-large-v3-turbo; do not infer translation support for Turbo. Output/timestamp formats depend on model config. For Russian auto-detection omit language where explicit ru is unavailable.

SenseVoiceSmall language: auto/zh/en/yue/ja/ko/nospeech. Whisper-specific translation and word timestamps are not shared capabilities.

ACE-Step-v1-3.5B uses POST /v1/async/music/generations only when the account music extension is enabled. task: text2music(default),retake,repaint,edit,extend. prompt describes sound and lyrics contains lyrics; duration30–240 seconds(default60), src_audio_url is a public reference URL, or upload src_audio/reference_audio with multipart. Additional source-operation parameters are model-specific; poll /v1/task/{id}. Presence in a catalog does not prove account enablement or a completed music-generation E2E.

• ACE-Step-v1-3.5B
• SenseVoiceSmall
• TeleASR-MultiDialect
• whisper-large-v3
• whisper-large-v3-turbo

# Requires an account-enabled music model; discover model access first.
curl https://apixly.ai/v1/async/music/generations \
  -H "Authorization: Bearer YOUR_AUDIO_API_KEY" \
  -H "Idempotency-Key: UNIQUE_MUSIC_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"ACE-Step-v1-3.5B","task":"text2music","prompt":"Soft instrumental piano with a slow steady rhythm","lyrics":"[instrumental]","duration":30}'
# Poll the returned task with GET /v1/task/TASK_ID.