Languages

Sandchest detects the language of your audio by default. You can also pin it, hint it, or require a confidence floor. This page covers each mode, the exact validation rules, and the codes the API accepts.

Detection is the default#

Omit both language_code and language_detection and Sandchest detects the language:

{ "audio_url": "https://example.com/meeting.mp3" }

The completed transcript reports what it found:

{
  "language_code": "de",
  "language_confidence": 0.97,
  "language_detection": true
}

language_confidence is between 0 and 1 and comes from the genuine transcript — Sandchest never fabricates a language for audio it could not read. Detection needs speech: a file with no spoken audio fails with {"error":"language_detection cannot be performed on files with no spoken audio."} on the transcript, rather than guessing.

Pinning a language#

When you already know the language, say so. It skips detection and avoids a wrong guess on short or noisy clips.

{ "audio_url": "https://example.com/meeting.mp3", "language_code": "es" }

The response then carries language_detection: false and the language_code you asked for.

Hinting and fallbacks#

language_detection_options narrows the search or names a safety net.

{
  "audio_url": "https://example.com/support-call.mp3",
  "language_detection": true,
  "language_confidence_threshold": 0.6,
  "language_detection_options": {
    "expected_languages": ["en", "fr", "de"],
    "fallback_language": "en"
  }
}

The rules#

The API enforces four rules and gives you the exact reason each time.

That last rule is satisfied when any of these is true: expected_languages is absent, expected_languages is ["all"], fallback_language is "auto", or expected_languages contains the fallback. When it is omitted, the fallback is compared as en. English locale codes fold together for this comparison — en_au, en_uk and en_us all count as en — while de_ch stays distinct from de.

Models#

Both models stay warm, so neither routing decision costs you a cold start. The transcript's speech_model_used names whichever one produced it. Self-hosted deployments choose their own models with SANDCHEST_MODEL and SANDCHEST_MULTILINGUAL_MODEL — see Self-hosting.

The multilingual model decodes these 25 languages:

Self-hosted deployments have a second option: the worker can be built with an optional Whisper engine and started with SANDCHEST_INFERENCE_ENGINE=whisper, which covers the whole accepted code list below. Parakeet is the default engine and the one behind the hosted service. See Self-hosting.

Accepted language codes#

These 103 codes pass validation on language_code and inside language_detection_options.expected_languages. Anything else is rejected with {"error":"The request contains an unsupported option or an invalid option value."}.

Verify#

Detect the language of a file and read back what was found:

curl -sS "https://stt-api.sandchest.com/v2/transcript/$ID" \
  -H "Authorization: $SANDCHEST_API_KEY" \
  | jq '{status, language_detection, language_code, language_confidence, speech_model_used}'

{
  "status": "completed",
  "language_detection": true,
  "language_code": "en",
  "language_confidence": 0.99,
  "speech_model_used": "nvidia/parakeet-tdt-0.6b-v3"
}

Detected-English audio may report either model: detection runs on the multilingual model, and an uncertain English result is refined on the English one. Whichever finished the job is the one named in speech_model_used.

Next#

Webhooks — stop polling and get told when a transcript is done.