Transcription API Usage Guide

Transcribe audio into text. Upload a file as multipart/form-data and receive a JSON envelope containing the transcript and, when the service reports it, the audio duration.

Endpoint: POST https://api.radienthq.com/v1/tools/transcriptions — multipart/form-data in, JSON out. One request, one transcript; there is no job to poll.

#Quickstart

bash

curl https://api.radienthq.com/v1/tools/transcriptions \
  -H "Authorization: Bearer $RADIENT_API_KEY" \
  -F file=@sample_audio.mp3

A real response (the provider value is trimmed here; everything else is verbatim):

json

{"msg":"Transcription completed successfully","result":{"text":"This is a sample recording for the transcription API.","provider":"…","status":"completed","duration":2.832875}}

result.duration is the audio length in seconds when the service reports it, and result.status is completed on success.

#Form data parameters

Field	Type	Required	Default	Notes
`file`	file	Yes	–	The audio file to transcribe. See Limits.
`model`	string	No	service default	A transcription model id served by the API. An id the service does not recognise is refused.
`prompt`	string	No	–	Up to 1,000 characters of context — domain vocabulary, spelling of names — to guide the transcription.
`response_format`	string	No	`json`	Accepted values: `json`, `text`, `srt`, `verbose_json`, `vtt`. The response is always the JSON envelope shown above; subtitle formats are accepted for compatibility but not produced today — send `json` (or omit the field).
`temperature`	number	No	`0`	0–2.
`language`	string	No	auto	Exactly two letters (ISO 639-1), e.g. `en`. Omit to let the service detect the language.

Do not send JSON to this endpoint — the fields travel as form data alongside the file, and a request without a file part is rejected with 400.

#Limits

25 MiB per file. The platform enforces this cap before transcription; larger uploads are rejected with 400.
Any common audio container the service can decode (mp3, wav, m4a, flac, ogg, …). A file that is not decodable audio fails with 500 rather than a 400 — check the file before retrying.
The endpoint is synchronous: a request returns when the transcript is ready.

#Pricing

Transcription is metered per second of audio, rounded up to the whole second:

Serving model	Price per second
Default	$0.0000611
Alternate	$0.0001

A one-minute file therefore costs about $0.0037 (default). If the service cannot report a usable duration, the transcript is still returned and the call is metered at 0 units. Calls that fail are not charged. Balances live in Radient Pass.

A successful transcription's result carries the versioned cost object: amount_usd is the charge for the call, units the metered seconds, and usage_record_id the id of the usage row it lands on. See Cost reporting.

#Errors

Status	Meaning
400	Missing `file`, a file over 25 MiB, or an invalid field (bad `language` length, unknown `response_format`, out-of-range `temperature`).
401	Missing or invalid credentials.
402	Insufficient credits — see Radient Pass.
429	The transcription service is busy; retry after a moment.
500	The service could not transcribe the file (corrupt audio, or an upstream failure).
503	Transcription is temporarily unavailable; retry later.

Real bodies (… marks text trimmed in this page):

json

{"error":"[bad_request] Missing 'file' in form-data"}

json

{"error":"[bad_request] File size exceeds the 25MB limit"}

json

{"error":"[bad_request] Invalid request parameters: Key: 'TranscriptionRequest.Language' Error:Field validation for 'Language' failed on the 'len' tag"}

json

{"error":"[internal] Transcription failed: …"}

json

{"error":"insufficient credits"}

#Tips

Trim silence and split hour-long recordings client-side; a single request is synchronous, so a shorter file means a faster response.
Reuse prompt across chunks of the same recording (spellings, acronyms) to keep the transcript consistent.
Round-trip check: transcribing a clip you generated with the Speech API is a cheap smoke test — a 2.8-second clip returned its text in about 0.6 seconds.

For the full endpoint list, see the API Reference.