Transcript options

One JSON body creates a transcript, at POST /v2/transcript or POST /api/v1/transcripts. Only audio_url is required; everything else has a sensible default. This page is the complete field reference for both directions.

curl -sS https://stt-api.sandchest.com/v2/transcript \
  -H "Authorization: $SANDCHEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-08-30-meeting-141" \
  -d '{
    "audio_url": "https://example.com/meeting.mp3",
    "language_detection": true,
    "disfluencies": true,
    "format_text": true
  }'

The audio#

An uploaded asset expires after the deployment's retention window (24 hours on the hosted service). Referring to an expired or deleted upload returns {"error":"The uploaded audio asset was not found or has expired."}.

Language#

Rules the API enforces, with the exact error each one produces, are in Languages. The short version: send language_code, or send language_detection: true, or send neither and get detection.

fallback_language must appear in expected_languages, or be "auto", or expected_languages must be ["all"] — otherwise the request is rejected with {"error":"fallback_language must be in expected_languages or auto."}. When comparing, en_au, en_uk and en_us all fold to en; de_ch stays distinct from de.

Text formatting#

custom_spelling#

An array of { "from": ..., "to": ... } rules. from is a spoken word or phrase, or an array of them, matched case-insensitively. to is the single word to display.

{
  "audio_url": "https://example.com/meeting.mp3",
  "custom_spelling": [
    { "from": ["sand chest", "sandchest"], "to": "Sandchest" },
    { "from": "assembly ai", "to": "AssemblyAI" }
  ]
}

Rules apply after recognition and alignment. They do not bias the acoustic model or improve accuracy — they rewrite what was already heard. When a multi-word from collapses into one word, the merged word keeps the first word's start, the last word's end, and the mean confidence.

Constraints, and the exact error for each:

null, false, 0, "", [] and {} all mean "no rules" and are accepted.

Models#

Sandchest routes to its own configured models — English audio to Parakeet TDT v2, automatic and non-English requests to the multilingual Parakeet TDT v3. The response field speech_model_used reports the model that genuinely produced the transcript, so you always know what ran. See Languages.

Webhooks#

Both auth fields must be sent together with a webhook_url, or all three omitted. Anything else returns {"error":"Invalid webhook URL or authentication parameters."}. Full behaviour in Webhooks.

Idempotency#

Idempotency-Key is a request header, not a body field. At most 200 characters.

POST /v2/transcript HTTP/1.1
Authorization: sc_live_...
Idempotency-Key: import-2026-08-30-meeting-141
Content-Type: application/json

• Same key, same request → the original transcript, not a second one, and no second charge.
• Same key, a genuinely different request → HTTP 409 and {"error":"This Idempotency-Key was already used for a different transcription request."}.
• Same key, but the transcript was deleted → HTTP 409 and {"error":"This Idempotency-Key belongs to a deleted transcript."}. Keys stay reserved after deletion; they never produce a fresh job.
• Longer than 200 characters → HTTP 400 and {"error":"Idempotency-Key must contain at most 200 characters."}.

Keys are scoped to your workspace and do not expire. Re-uploading the identical bytes and retrying with the same key still counts as the same request: Sandchest compares the stored SHA-256 of the audio, not the URL.

Multichannel#

multichannel: true recognises each physical input channel on its own, so a two-track call recording gives you both sides with independent timings. Up to 32 channels.

When it is on, the completed transcript adds:

• audio_channels — how many channels were decoded.
• utterances — per-channel spans, each with speaker, channel, text, start, end, confidence and words.
• speaker and channel on every word, both set to the channel label: "1", "2", and so on.

Channel labels identify input channels. They are not inferred speaker identities — Sandchest does not do diarization, and speaker_labels: true is rejected.

The transcript object#

Returned by create, get, list-item lookups and delete.

The word object#

{
  "text": "deploy",
  "start": 1100,
  "end": 1480,
  "confidence": 0.99,
  "speaker": null,
  "channel": null
}

Timings are acoustic, from the model's own alignment. Every derived resource — sentences, paragraphs, SRT, VTT, word search — is built from these same word boundaries, so a caption never disagrees with a word.

Verify#

Create a transcript with a couple of options and check they round-trip:

curl -sS https://stt-api.sandchest.com/v2/transcript \
  -H "Authorization: $SANDCHEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"'"$UPLOAD_URL"'","disfluencies":true,"language_code":"en"}' \
  | jq '{status, disfluencies, language_detection, language_code}'

{
  "status": "queued",
  "disfluencies": true,
  "language_detection": false,
  "language_code": null
}

language_code is null until the transcript completes — the response echoes what was detected, not what was requested. Poll the same id and it fills in.

Next#

Languages — automatic detection, the supported codes, and which model handles which.