API reference — Speech-to-Text

The contract for invoking a self-hosted Saaras v3 endpoint. Unlike the Managed API, the invoke contract lives in the SageMaker model container — this page is the reference for it.

Real-time — InvokeEndpoint

Request fields

Output modes

Response

{
  "request_id": "20260728_de2321d1-9ddf-4a99-9ed4-49a19bda3136",
  "transcript": "namaste, main aapki kaise madad kar sakta hoon",
  "language_code": "hi-IN",
  "language_probability": 0.98,
  "timestamps": {
    "words": ["namaste", "main", "aapki", "..."],
    "start_time_seconds": [0.10, 0.72, 1.05],
    "end_time_seconds":   [0.61, 0.94, 1.38]
  }
}

timestamps is present only when with_timestamps is "true". The request_id format is YYYYMMDD_<uuid4> (not req_…).

Streaming — InvokeEndpointWithBidirectionalStream

For continuous, low-latency audio, open a two-way SigV4 HTTP/2 stream on port 8443 (client aws-sdk-sagemaker-runtime-http2): audio-in frames go up and transcript-out frames come back. This is a full-duplex bidirectional stream — not the one-way InvokeEndpointWithResponseStream response-streaming operation.

Query parameters — sent URL-encoded in the ModelQueryString:

Message protocol — send JSON frames, then read frames back:

// 1. open with a config frame
{ "type": "config" }
// 2. stream audio chunks
{ "audio": { "data": "<base64 PCM>", "sample_rate": 16000, "encoding": "audio/wav" } }
// 3. flush at end
{ "type": "flush" }

The endpoint returns events frames (VAD signals, when vad_signals=true) and data frames (incremental transcripts).

Errors

Every non-2xx is delivered as HTTP 424 through InvokeEndpoint — branch on OriginalStatusCode and error.code, never on the HTTP status. See Error handling on SageMaker for the collapse rule, the boto3 branch snippet, and the shared envelope.

Bad request — OriginalStatusCode 400, code: invalid_request_error. Causes: a wrong model id (send saaras:v3, not saaras:v3.1), audio over 30 s on the real-time path, empty / unreadable / truncated audio, a missing file, or any content type other than multipart/form-data.

{
  "error": {
    "message": "Lean STT supports only 'saaras:v3'. Got 'not-a-model'.",
    "code": "invalid_request_error",
    "request_id": "20260728_…"
  }
}

Overload — OriginalStatusCode 429, code: service_overloaded. The container sheds fast rather than queueing; back off using the body retry_after.

{
  "error": {
    "message": "Server is busy. Please retry shortly.",
    "code": "service_overloaded",
    "request_id": "20260728_…",
    "retry_after": 1
  }
}