Speech-to-Text

The launch mechanism is API keys. A key looks like cs_live_… (production) or cs_test_… (sandbox / time-boxed pilots) and is sent on every request as Authorization: Bearer cs_live_… (canonical) or the x-api-key header. A workspace owner or admin creates keys in the Architect console (Speech → API keys, alongside usage and request logs); Camlin issues them directly for pilots that have no workspace yet. Either way a key is shown once, stored only as a hash, and rotation is create-new / move-caller / revoke-old.

Rate limits are enforced per key (token bucket, per product). Responses carry RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset; a limited request receives 429 with Retry-After. Tier numbers are part of your plan.

Demo tier. Disabled in production. There is no keyless carve-out for external callers: the public site's own demo pages go through the site's server, which holds its own key. Every direct API call needs a key.

Enablement status. Live. Authentication has been enforced in production since 5 August 2026. An unkeyed request is refused with 401 and body {"detail": "API key required; send Authorization: Bearer cs_…"}. Send the key as Authorization: Bearer cs_live_… (or the x-api-key alias) on every request.

Browser ASR tokens. A web page must never hold a real API key. If your product runs recognition in the browser (as the Camlin avatar SDK's mic path does), your server calls POST /api/v1/asr/token with its real key (stt scope, optional body {"ttl_s": 300}, max 600) and hands the page the returned cat_… token. The page then sends Authorization: Bearer cat_… to /api/v1/asr/recognize directly. The token is ASR-only (nothing else, and it cannot mint tokens), tenant-bound (your lexicon biasing applies and cannot be re-pointed by the page), short-lived, and rate-limited per visitor IP at the demo tier.

• Usage/request metadata (timestamps, route, status, audio seconds, character counts, key/tenant ids) is retained for 90 days, then purged automatically.
• No payload retention: audio sent for recognition and transcripts produced are not stored unless your tenant explicitly opts in. Lexicon contents you store are tenant data, retained until you delete them.

Send RIFF/WAV bytes in the request body — the bytes are the body, not a multipart form.

Audio format, and what it costs you. Mono 16 kHz PCM is what the model is trained on and what we recommend. Other WAV sample rates are accepted and resampled — including 8 kHz telephony audio, which is the one worth knowing about: on our internal evaluation set, G.711-grade 8 kHz narrowband costs about 1.3 WER points absolute against the same audio at 16 kHz. That is usable for IVR work (it is what phone lines are), but if you control the capture path, capture at 16 kHz — do not downsample and give accuracy away for nothing. Narrowband-specific training is in the current model roadmap.

curl -X POST "$CAMLIN_SPEECH_URL/api/v1/asr/recognize"   -H "Authorization: Bearer $CAMLIN_API_KEY"   -H "Content-Type: audio/wav"   -H "x-camlin-asr-language: en-AU"   --data-binary @sample.wav

The lexicon is the mechanism behind the "gets Australian names right" claim, so it is worth thirty seconds. Every tenant can store a vocabulary — customer surnames, agency names, suburbs, product terms — and once it exists it is applied automatically to every recognition call made with that tenant's key. No per-request configuration, no client code change: update the lexicon and the next call benefits.

Self-service is keyed and own-tenant-only. A key carrying the lexicon scope can read, write, and delete the lexicon for its own tenant — and no other; cross-tenant access returns 403. Enumerating tenants is operator-only.

Availability note. The /api/v1/asr/lexicon* paths are live on the public hostname for keyed callers (the 2 August edge rule lifted with the 5 August launch configuration). If a call is refused, check the key carries the lexicon scope.

{
  "tenant_id": "acme-au",
  "names": ["Sione Tuilagi", "Aanya Reddy", "Hayden Vu"],
  "context_words": ["Centrelink", "NDIS", "BPAY"],
  "pronunciations": { "Tuilagi": "too-ee-LAH-ngee" },
  "boost": 5.0
}

curl -X PUT "$CAMLIN_SPEECH_URL/api/v1/asr/lexicon/acme-au"   -H "Authorization: Bearer $CAMLIN_API_KEY"   -H "Content-Type: application/json"   -d '{"names":["Sione Tuilagi"],"context_words":["NDIS"]}'

Unknown tenant IDs are ignored for recognition, so lexicons can be rolled out incrementally.

Live streaming recognition powers the public /live demo. It is served over Socket.IO, websocket transport only, on the /socket.io path of the same host — it is not a plain WebSocket endpoint, so use a Socket.IO client library configured with transports: ["websocket"]. HTTP long-polling is refused at the handshake: the service scales horizontally and a polled session cannot be guaranteed to keep landing on the task that holds its decode state, so websocket-only keeps the whole session on a single connection pinned to one task.

Credentials travel in the connect payload, the Socket.IO-native place for them (never the query string, which ends up in access logs):

const socket = io(CAMLIN_SPEECH_URL, {
  path: "/socket.io",
  transports: ["websocket"],
  auth: { key: process.env.CAMLIN_API_KEY },  // requires the stt:stream scope
});

An Authorization: Bearer header on the connect request is also accepted for non-browser clients. Connections without a key are refused at connect, as is a key that is invalid or lacks stt:stream. Streamed audio is metered in seconds against your tenant when the session ends.

The session distinguishes committed text — words the decoder has confirmed, which will never change — from tentative text, the unstable tail that may be revised or vanish on the next decode. They arrive on different events, and getting this distinction right is most of building a good live-caption UI:

Ordering guarantees worth building against:

• Within one decode cycle, transcription (if any words committed) arrives before the partial_transcription that carries the new tail — so apply committed text first, then overwrite the tentative display.
• Committed words never retract. Tentative words carry no such promise; treat them as display-only and never hand them to downstream logic.
• commit_reason says why words committed: local_agreement (two consecutive decodes agreed — the normal path) or forced_tail (the tail cap pushed them through to keep latency bounded; slightly less certain).
• After live_stop, one final decode flushes the remaining tail as a transcription with is_final: true. Wait for it before treating the transcript as complete.

Planned. A productised plain-WebSocket streaming API (no Socket.IO dependency), with credentials carried at connection time, is on the launch roadmap for contact-centre platform integrations.

export async function recognizeWav(wavBuffer) {
  const headers = {
    authorization: `Bearer ${process.env.CAMLIN_API_KEY}`,
    "content-type": "audio/wav",
    "x-camlin-asr-language": "en-AU",
  };

  const res = await fetch(`${process.env.CAMLIN_SPEECH_URL}/api/v1/asr/recognize`, {
    method: "POST",
    headers,
    body: wavBuffer,
  });
  if (!res.ok) throw new Error(`recognize failed: HTTP ${res.status}`);
  return res.json();
}

Your tenant's lexicon is applied automatically from the key — no per-request tenant header is needed.

• Production callers should omit backend overrides and let the service route to the fastest healthy path with CPU fallback.
• Near-silent audio returns an empty text with confidence: 0 — the service gates on signal energy before decoding, so silence is never transcribed as hallucinated speech. Treat an empty transcript as "no speech", not an error.
• camlin-au is the customer-facing default recognition profile.
• Lexicon data can contain customer information; keep exports out of source control and support tickets unless approved.