The Dictation API

POST https://sochen.dev/api/v1/dictate/sessions
Authorization: Bearer sk_sochen_…
Content-Type: application/json

{
  "language": "auto",
  "app": { "name": "My editor", "category": "code" }
}

{
  "id": "dict_…",
  "expiresAt": "2026-09-27T10:15:00.000Z",
  "maxSeconds": 600,
  "stream": null,
  "clientToken": "…",
  "quota": { "plan": "pro", "wordsUsed": 12840, "wordsLimit": null, "resetsAt": "2026-10-01T00:00:00.000Z" },
  "settings": { "language": "auto", "output": "as-spoken", "accuracy": "fast", "styles": { "…": "…" }, "terms": [], "replacements": [], "snippets": [], "voiceSend": false, "transcribeModel": null, "cleanupModel": null }
}

POST https://sochen.dev/api/v1/dictate/sessions/dict_…/transcribe
Authorization: Bearer <sk_sochen_… on a server, or the session's clientToken in a browser>
Content-Type: audio/wav
x-part-index: 0

<a WAV file: mono, 16-bit PCM, 8 to 48 kHz>

{ "transcript": "so in the auth middleware make the get user name function", "seconds": 6.4 }

POST https://sochen.dev/api/v1/dictate/sessions/dict_…/finish
Authorization: Bearer <sk_sochen_… or the clientToken>
Content-Type: application/json

{
  "transcript": "so in the auth middleware make the get user name function return null instead of throwing and add a test",
  "audioSeconds": 9,
  "app": { "name": "My editor", "category": "code" },
  "style": "prompt",
  "output": "english"
}

{
  "text": "In the auth middleware, make `getUserName` return null instead of throwing, and add a test.",
  "raw": "so in the auth middleware make the get user name function return null instead of throwing and add a test",
  "words": 20,
  "style": "prompt",
  "submit": false,
  "quota": { "plan": "pro", "wordsUsed": 12860, "wordsLimit": null, "resetsAt": "2026-10-01T00:00:00.000Z" }
}

POST https://sochen.dev/api/v1/dictate/sessions/dict_…/finish
Authorization: Bearer <sk_sochen_… or the clientToken>
Content-Type: multipart/form-data; boundary=…

--…
Content-Disposition: form-data; name="meta"

{ "transcript": "<the parts' transcripts so far>", "audioSeconds": 9, "style": "prompt" }
--…
Content-Disposition: form-data; name="audio"; filename="tail.wav"
Content-Type: audio/wav

<the last WAV part, heard and written up in one call>
--…--

POST https://sochen.dev/api/v1/dictate/clean
Authorization: Bearer sk_sochen_…
Content-Type: application/json

{ "text": "um so can you, like, move the meeting to thursday no wait friday at 5", "style": "clean" }

{ "text": "Can you move the meeting to Friday at 5?", "words": 16, "style": "clean", "submit": false }

{ "error": "You've used this week's 2,000 free words. They refill on Monday, or upgrade for unlimited dictation." }

// server.mjs (Node 20+). Keeps the API key on the server; the browser gets a client token per session.
import { createServer } from "node:http";
import { readFile } from "node:fs/promises";

const KEY = process.env.SOCHEN_API_KEY; // sk_sochen_…, from https://sochen.dev/dictation

createServer(async (req, res) => {
  if (req.method === "POST" && req.url === "/dictation/session") {
    const upstream = await fetch("https://sochen.dev/api/v1/dictate/sessions", {
      method: "POST",
      headers: { authorization: `Bearer ${KEY}`, "content-type": "application/json" },
      body: JSON.stringify({ language: "auto", app: { name: "My app", category: "docs" } }),
    });
    const session = await upstream.json();
    res.writeHead(upstream.status, { "content-type": "application/json" });
    // Only what the page needs: the id, the token that opens this one session, and the limit.
    res.end(JSON.stringify(upstream.ok ? { id: session.id, clientToken: session.clientToken, maxSeconds: session.maxSeconds } : session));
    return;
  }
  res.writeHead(200, { "content-type": "text/html" });
  res.end(await readFile("./page.html", "utf8"));
}).listen(3000);

<!-- page.html: hold the button, speak, let go. -->
<button id="talk">Hold to talk</button>
<p id="out"></p>
<script type="module">
const API = "https://sochen.dev/api/v1/dictate";
const RATE = 16000;

// The worklet turns the mic into 16 kHz 16-bit PCM, 100 ms at a time.
const worklet = URL.createObjectURL(new Blob([`
  class P extends AudioWorkletProcessor {
    constructor() { super(); this.buf = []; this.n = 0; }
    process(inputs) {
      const ch = inputs[0]?.[0]; if (!ch) return true;
      const out = new Int16Array(ch.length);
      for (let i = 0; i < ch.length; i++) { const s = Math.max(-1, Math.min(1, ch[i])); out[i] = s < 0 ? s * 0x8000 : s * 0x7fff; }
      this.buf.push(out); this.n += ch.length;
      if (this.n >= 1600) { this.port.postMessage(this.buf.splice(0)); this.n = 0; }
      return true;
    }
  }
  registerProcessor("pcm", P);`], { type: "application/javascript" }));

function wav(frames) {
  const bytes = frames.reduce((n, f) => n + f.byteLength, 0);
  const h = new DataView(new ArrayBuffer(44));
  const tag = (at, s) => [...s].forEach((c, i) => h.setUint8(at + i, c.charCodeAt(0)));
  tag(0, "RIFF"); h.setUint32(4, 36 + bytes, true); tag(8, "WAVE"); tag(12, "fmt "); h.setUint32(16, 16, true);
  h.setUint16(20, 1, true); h.setUint16(22, 1, true); h.setUint32(24, RATE, true); h.setUint32(28, RATE * 2, true);
  h.setUint16(32, 2, true); h.setUint16(34, 16, true); tag(36, "data"); h.setUint32(40, bytes, true);
  return new Blob([h.buffer, ...frames], { type: "audio/wav" });
}

let session, context, frames = [], partIndex = 0, uploads = Promise.resolve(), transcripts = [];

async function uploadPart(part) {
  const index = partIndex++;
  uploads = uploads.then(async () => {
    const r = await fetch(`${API}/sessions/${session.id}/transcribe`, {
      method: "POST",
      headers: { authorization: `Bearer ${session.clientToken}`, "content-type": "audio/wav", "x-part-index": String(index) },
      body: wav(part),
    });
    const { transcript } = await r.json();
    transcripts[index] = transcript;
    out.textContent = transcripts.join(" ");
  });
}

async function start() {
  session = await (await fetch("/dictation/session", { method: "POST" })).json();
  const mic = await navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true } });
  context = new AudioContext({ sampleRate: RATE });
  await context.audioWorklet.addModule(worklet);
  const node = new AudioWorkletNode(context, "pcm");
  let seconds = 0;
  node.port.onmessage = (e) => {
    for (const f of e.data) { frames.push(f.buffer); seconds += f.length / RATE; }
    // Cut every ten seconds; the tail goes up on release.
    if (seconds >= 10) { uploadPart(frames.splice(0)); seconds = 0; }
  };
  context.createMediaStreamSource(mic).connect(node);
  context.mic = mic;
}

async function stop() {
  context.mic.getTracks().forEach((t) => t.stop());
  await context.close();
  if (frames.length) uploadPart(frames.splice(0));
  await uploads;
  const transcript = transcripts.join(" ");
  const done = await (await fetch(`${API}/sessions/${session.id}/finish`, {
    method: "POST",
    headers: { authorization: `Bearer ${session.clientToken}`, "content-type": "application/json" },
    body: JSON.stringify({ transcript, audioSeconds: Math.round(partIndex * 10), style: "clean" }),
  })).json();
  out.textContent = done.text;
  frames = []; partIndex = 0; transcripts = [];
}

const out = document.getElementById("out");
const talk = document.getElementById("talk");
talk.onpointerdown = start;
talk.onpointerup = stop;
</script>