API Reference

Transcription API

Transcribe audio files into text.Four endpoints, picked by two questions: do you want the result back in the response, or queued? And inline upload or presigned upload?Sync, inline: POST /transcribe. Upload via multipart/form-data (capped at 8 MiB), get the transcript in the response.Async, inline: POST /transcribe/async. Same upload, but the job runs in the background. Poll GET /transcribe/{job_id} or pass a webhook_url to be notified when it finishes. Queued jobs can be cancelled with DELETE /transcribe/{job_id}.Sync, presigned: POST /transcribe/by-upload. First call `POST /uploads/presign` to mint an upload URL, PUT your file directly to that URL, then call this endpoint with the upload ID. Transcript comes back in the response. Same 8 MiB ASR cap.Async, presigned: POST /transcribe/async/by-upload. The presigned-upload flow above, run as a background job with optional webhook.Accepted formats: WAV, FLAC, and Ogg/Opus.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 6
Scopes: transcribe:use

POST/transcribe

Synchronously transcribe an audio file.

Transcribe Audio

Uploads an audio file via multipart/form-data and returns the transcription synchronously. The request body is capped at 8 MiB; larger uploads return 413. Empty files return 400. Calls are metered against your account and deducted from credits when transcription completes successfully.

Request body

filebinaryrequired
Audio file uploaded as multipart/form-data. Accepted formats: WAV, FLAC, Ogg/Opus. Maximum 8 MiB. Other file types are rejected.
languagestringoptional
Language hint (e.g. english, french). Omit to let the model detect the language.
group_idstring (uuid)optional
Optional UUID correlating multiple chunked uploads of one recording. Send the same value with every chunk; dashboards aggregate the chunks into a single transcription entry.
group_totalintegeroptional
Expected number of chunks in the group, 1–10000 (requires group_id). Lets dashboards flag a group whose chunks did not all arrive as partial.

Errors

400Empty File

The uploaded file is empty (zero bytes).

Upload a non-empty audio file.

401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Your API key does not have the transcribe:use scope.

Issue a new key with the transcribe:use scope.

413Payload Too Large

The uploaded file exceeded the 8 MiB cap.

Compress or trim the audio to fit under 8 MiB before retrying. The presigned-upload flow has the same cap.

422Unprocessable Entity

Missing file field or unsupported audio format.

Attach a file field with a supported audio format (WAV, FLAC, Ogg/Opus).

503Service Unavailable

The ASR service is temporarily unavailable.

Retry after a few seconds; the service should recover automatically.

Request

json

curl -X POST https://api.aethexai.com/api/v1/transcribe \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected];type=audio/wav" \
  -F "language=english"

200 Response

json

{
  "id": "8f2b1c4a-9d3e-4f12-9a8c-3b7e1d5f6c2a",
  "text": "Hello, I would like to check the status of my order.",
  "language": "english",
  "duration_seconds": 3.42,
  "segments": [],
  "status": "completed",
  "processing_time_ms": 812,
  "created_at": "2026-05-08T10:00:00Z"
}

POST/transcribe/async

Queue a transcription job and receive results via webhook.

Transcribe Audio (Async)

Accepts an audio file, stores it, and processes the transcription in the background. The result is sent to webhook_url when complete. Poll GET /transcribe/:job_id as a fallback if no webhook is configured.Webhook status field. webhook_status is null when no webhook_url was supplied — that is the steady-state value for polling-only clients. The non-null values (pending, delivered, failed, unsafe) only appear when a webhook is registered. unsafe is returned when the webhook URL is rejected by SSRF policy (e.g. private-network destination).

Request body

filebinaryrequired
Audio file to transcribe (multipart/form-data).
languagestringoptional
Language hint (e.g. english, french).
webhook_urlstringoptional
URL to receive a POST when transcription completes. Optional — poll GET /transcribe/:job_id if omitted.

Errors

400Empty File

The uploaded file is empty (zero bytes).

Upload a non-empty audio file.

401Unauthorized

Missing or invalid API key.

Include a valid X-API-Key header.

403Forbidden

Your API key does not have the transcribe:use scope.

Use a key with the transcribe:use scope.

413Payload Too Large

The uploaded file exceeded the 8 MiB cap.

Compress or trim the audio to fit under 8 MiB before retrying. The presigned-upload flow has the same cap.

422Unprocessable Entity

Missing file field or unsupported audio format.

Attach a file field with a supported audio format.

422Invalid Webhook URL

webhook_url is present but not a valid HTTPS URL.

Pass a valid https:// URL or omit webhook_url.

422Malware Detected

The uploaded file was flagged by the malware scanner.

Upload a clean audio file.

503Service Unavailable

The ASR service is temporarily unavailable.

Retry after a few seconds; the ASR service should recover automatically.

Request

json

curl -X POST https://api.aethexai.com/api/v1/transcribe/async \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@long_recording.wav;type=audio/wav" \
  -F "language=english"

200 Response

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "pending",
  "text": "",
  "language": "english",
  "duration_seconds": null,
  "processing_time_ms": null,
  "error_message": null,
  "webhook_status": null,
  "webhook_last_error": null,
  "webhook_last_attempt_at": null,
  "webhook_delivered_at": null,
  "created_at": "2026-05-08T10:05:00Z",
  "updated_at": "2026-05-08T10:05:00Z"
}

POST/transcribe/by-upload

Synchronously transcribe a file already in object storage.

Transcribe by Upload ID

Transcribes an audio file that was previously uploaded via POST /uploads/presign. Useful when you have already stored the file and want to avoid re-uploading it.

Request body

upload_idstringrequired
Signed upload token returned by POST /uploads/presign. Opaque string, 8–8192 characters.
languagestringoptional
Language hint (e.g. english, french).

Errors

401Unauthorized

Missing or invalid API key.

Include a valid X-API-Key header.

403Forbidden

Your API key does not have the transcribe:use scope.

Use a key with the transcribe:use scope.

422Invalid Upload ID

upload_id is not a valid signed upload token.

Use the upload_id returned by POST /uploads/presign.

422Upload Not Found

The upload_id is valid but the file has already been consumed or expired.

Request a new upload token via POST /uploads/presign and re-upload the file.

503Service Unavailable

The ASR service is temporarily unavailable.

Retry after a few seconds.

Request

json

curl -X POST https://api.aethexai.com/api/v1/transcribe/by-upload \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "language": "english"
  }'

200 Response

json

{
  "id": "8f2b1c4a-9d3e-4f12-9a8c-3b7e1d5f6c2a",
  "text": "Hello, I would like to check the status of my order.",
  "language": "english",
  "duration_seconds": 3.42,
  "segments": [],
  "status": "completed",
  "processing_time_ms": 812,
  "created_at": "2026-05-08T10:00:00Z"
}

POST/transcribe/async/by-upload

Queue a transcription job from a previously uploaded file.

Transcribe Async by Upload ID

Async variant of POST /transcribe/by-upload. Queues a background transcription job from a file already in object storage, then sends results to webhook_url when done.

Request body

upload_idstringrequired
Signed upload token returned by POST /uploads/presign. Opaque string, 8–8192 characters.
languagestringoptional
Language hint (e.g. english, french).
webhook_urlstringoptional
URL to receive a POST when transcription completes. Optional.

Errors

401Unauthorized

Missing or invalid API key.

Include a valid X-API-Key header.

403Forbidden

Your API key does not have the transcribe:use scope.

Use a key with the transcribe:use scope.

422Invalid Upload ID

upload_id is not a valid signed upload token.

Use the upload_id returned by POST /uploads/presign.

422Upload Not Found

The upload_id is valid but the file has already been consumed or expired.

Request a new upload token via POST /uploads/presign and re-upload the file.

422Invalid Webhook URL

webhook_url is present but not a valid HTTPS URL.

Pass a valid https:// URL or omit webhook_url.

503Service Unavailable

The ASR service is temporarily unavailable.

Retry after a few seconds; the service should recover automatically.

Request

json

curl -X POST https://api.aethexai.com/api/v1/transcribe/async/by-upload \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "language": "english",
    "webhook_url": "https://hooks.your-domain.example/webhooks/transcription"
  }'

200 Response

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "pending",
  "text": "",
  "language": "english",
  "duration_seconds": null,
  "processing_time_ms": null,
  "error_message": null,
  "webhook_status": "pending",
  "webhook_last_error": null,
  "webhook_last_attempt_at": null,
  "webhook_delivered_at": null,
  "created_at": "2026-05-08T10:05:00Z",
  "updated_at": "2026-05-08T10:05:00Z"
}

GET/transcribe/:job_id

Poll the status of an async transcription job.

Get Transcription Job

Returns the current state (pending, processing, completed, or failed) and the transcript text once processing is complete.

Path & Query

job_idstringrequired
UUID of the transcription job, returned by POST /transcribe/async.

Errors

401Unauthorized

Missing or invalid API key.

Include a valid X-API-Key header.

403Forbidden

Your API key does not have the transcribe:use scope.

Use a key with the transcribe:use scope.

404Job Not Found

No job with this ID exists.

Confirm the id from POST /transcribe/async or POST /transcribe/async/by-upload.

422Invalid Job ID

job_id is not a valid UUID.

Pass the UUID returned by POST /transcribe/async.

Request

json

curl https://api.aethexai.com/api/v1/transcribe/a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16 \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "completed",
  "text": "Full transcription text appears here once processing completes.",
  "language": "english",
  "duration_seconds": 12.4,
  "processing_time_ms": 1432,
  "error_message": null,
  "webhook_status": "delivered",
  "webhook_last_error": null,
  "webhook_last_attempt_at": "2026-05-08T10:05:14Z",
  "webhook_delivered_at": "2026-05-08T10:05:14Z",
  "created_at": "2026-05-08T10:05:00Z",
  "updated_at": "2026-05-08T10:05:14Z"
}

DELETE/transcribe/:job_id

Cancel a pending or in-progress transcription job.

Cancel Transcription Job

Cancels a job that has not yet completed. Returns the job with status: cancelled. Completed or already-cancelled jobs return 409.

Path & Query

job_idstringrequired
UUID of the transcription job to cancel.

Errors

401Unauthorized

Missing or invalid API key.

Include a valid X-API-Key header.

403Forbidden

Your API key does not have the transcribe:use scope.

Use a key with the transcribe:use scope.

404Job Not Found

No job with this ID exists.

Confirm the id from POST /transcribe/async.

409Conflict

The job is already completed or cancelled.

Only pending or processing jobs can be cancelled.

422Invalid Job ID

job_id is not a valid UUID.

Pass the UUID returned by POST /transcribe/async.

Request

json

curl -X DELETE https://api.aethexai.com/api/v1/transcribe/a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16 \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "cancelled"
}