Speech to text

Transcribe recorded audio using an available speech-to-text model from GET /v1/models. Select a model with kind: stt and inspect its stt metadata before submitting. Both POST /v1/audio/transcriptions and POST /v1/audio/transcriptions/jobs return 202 with a durable job. Poll for the final transcript.

Job lifecycle

Submission is asynchronous: the 202 response contains the job ID and status, not the final transcript. Read GET /v1/audio/transcriptions/jobs/{id} until a terminal state is returned. Successful polling responses use HTTP 200, including when the job has failed.

STT normally progresses through queued → processing → completed. OCR jobs use queued → running → succeeded. Keep these status sets separate in your client. Use a bounded polling interval and an application deadline; reaching your deadline does not cancel the job.

Upload and transcribe

curl -X POST https://relayon.app/v1/audio/transcriptions \
  -H "Authorization: Bearer ro_live_YOUR_KEY" \
  -H "Idempotency-Key: recording-001" \
  -F "model=relayon-stt" \
  -F "language=en" \
  -F "timestamps=word" \
  -F "diarize=true" \
  -F "file=@recording.mp3"

curl https://relayon.app/v1/audio/transcriptions/jobs/sttjob_YOUR_JOB_ID \
  -H "Authorization: Bearer ro_live_YOUR_KEY"

Reuse a file or send an HTTPS URL

Upload to /v1/files with multipart purpose=audio, JSON purpose: "audio", or raw bytes with X-File-Purpose: audio. Playground files and jobs belong to the selected account. API-key uploads and jobs belong to that key’s workspace. Job reads and cancellation require the API key or session identity that created the job.

{
  "model": "relayon-stt",
  "audio": {
    "type": "file_id",
    "file_id": "file_YOUR_FILE_ID"
  },
  "timestamps": "word",
  "diarize": true,
  "response_format": "json"
}

For a remote source, replace audio with {"type":"audio_url","url":"https://example.com/recording.mp3"}. RelayOn fetches and validates it, blocking private network destinations and unsafe redirects. Use a stable HTTPS URL accessible for download, or upload the file to RelayOn.

Shared speech options

These parameter names are shared across RelayOn speech models. Supported languages, features and limits depend on the selected model. Inspect GET /v1/models/{model} for its stt metadata and capabilities. Unsupported options are rejected rather than silently ignored.

Supported languages come from the selected model’s stt.languages list. Omit language for automatic detection when stt.auto_language is true. An unsupported hint, such as xx-bogus, returns HTTP 422 with error.code: unsupported_language; the API does not silently switch to detection. Check stt.languages before sending a hint. If your application permits detection and stt.auto_language is true, it can retry without the hint after this explicit rejection. Do not use that fallback for timeouts, ambiguous submissions or an already accepted job.

The gateway accepts at most 1 GB, one audio track and two input channels; individual models may impose lower limits. Read stt.max_audio_bytes and stt.max_input_channels. A model that sets stt.max_audio_seconds rejects longer audio; when it is absent, the model has no duration limit and is billed by audio duration. When requesting timestamps or speaker labels, also apply stt.max_annotated_audio_seconds when present. Supported containers include WAV, MP3, FLAC, OGG, AAC, M4A and WebM. RelayOn validates decoding and duration before reserving spend; caller-supplied duration is ignored. File upload alone does not establish that audio is valid.

Result

{
  "id": "sttjob_example",
  "object": "audio.transcription.job",
  "status": "completed",
  "model": "relayon-stt",
  "result": {
    "model": "relayon-stt",
    "text": "Hello, everyone.",
    "language": "en",
    "no_speech": false,
    "audio_duration_seconds": 3,
    "words": [
      {
        "start": 0.2,
        "end": 0.6,
        "text": "Hello,",
        "speaker": "speaker_0",
        "channel": 0
      }
    ],
    "usage": {
      "audio_seconds": 3,
      "billable_seconds": 3,
      "metering_basis": "audio_duration",
      "channels_processed": 1
    }
  }
}

This abbreviated example is illustrative. Timestamps use seconds from the audio start. Requested word and speaker-segment arrays are complete in real responses. Valid silence succeeds with empty text and no_speech: true; processing silence is billable.

Use result.no_speech === true to detect a reported no-speech result. Do not infer silence from the word count: words may be absent when timestamps were not requested.

Pricing, idempotency and cancellation

Provider models use eligible keys connected to your active account or organization first. Where paid capacity is available, safe fallback uses your RelayOn balance. Read the selected model’s published prices and stt.metering_basis: duration-metered models report billable audio seconds, while token-metered models report input audio and output text tokens. Audio hours measure activity independently of billing.

Use the selected model’s current published rates, including any feature charges. Duration-based charges apply to processed billable seconds; token-based charges use measured token usage. Billable duration can round up from decoded duration. Paid jobs reserve an estimate and settle actual usage at their admitted rates; unused credit is released.

Use a unique Idempotency-Key per recording and options. Repeating it in the same caller and account or workspace returns the original job; changed input returns 409 idempotency_conflict. Omitted keys are generated and echoed in the response. Repeated polls do not create additional charges.

Cancel with DELETE /v1/audio/transcriptions/jobs/{id}. Cancellation is best effort; processing may continue, but cancelled and failed gateway jobs have no customer charge. Jobs report queued, processing, uncertain, completed, failed or cancelled. An uncertain submission retains its processing state. Poll the existing job rather than creating a potentially billable duplicate.

Polling a failed job returns HTTP 200 with a safe error. Audio validation errors include invalid_audio, unsupported_format, unsupported_language, audio_too_large and audio_too_long. If transcription is temporarily unavailable, follow the returned error code before retrying. Transcript results are available for a limited time; job status remains available after results expire.