Speech to text

Send a file, get a transcript. POST /v1/audio/transcriptions takes a multipart upload and answers with the words in it. Before you start: put a key in EESI_API_KEY — see Authentication — and install a client if you want one, from SDKs. Neither SDK is published to PyPI or npm yet, so both install from a checkout.

curl https://api.eesi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -F file=@interview.wav \
  -F model=nur-stt-v1

from eesi_sdk import EESIClient

with EESIClient(api_key="sk-eesi-...") as client:
    with open("interview.wav", "rb") as audio:
        result = client.create_transcription(
            file=("interview.wav", audio, "audio/wav"),
            model="nur-stt-v1",
        )

print(result["text"])

import { readFile } from "node:fs/promises";
import { EESIClient } from "@eesi/sdk";

const client = new EESIClient({ apiKey: process.env.EESI_API_KEY });

const bytes = await readFile("interview.wav");
const result = await client.createTranscription({
  file: new Blob([bytes], { type: "audio/wav" }),
  model: "nur-stt-v1",
});

console.log((result as { text: string }).text);

{ "text": "The rain had not stopped for three days." }

The SDK defaults are sized for JSON calls, not for a GPU pass over an hour of audio. Anything past a couple of minutes of recording needs a longer budget.In Python, pass EESIClient(timeout=1800). A float covers every phase.TypeScript has two budgets, and the one a long decode hits is not the one named “read”. connectTimeoutMs (10 s by default) bounds the wait for response headers; readTimeoutMs (60 s) bounds reading the body once they arrive. The gateway sends no headers until the model has answered, so new EESIClient({ readTimeoutMs: 1_800_000 }) on its own still gives up after ten seconds with RequestTimeoutError: POST /audio/transcriptions timed out (connect after 10000 ms). Pass new EESIClient({ connectTimeoutMs: 1_800_000, readTimeoutMs: 1_800_000 }).Either way the GPU carries on with the work after your side has stopped waiting for it.

Is this the right endpoint

A recording you already have

Calls, voicemails, uploads, anything that is a file rather than a stream. This endpoint.

Captions and search

verbose_json carries the timings you need to line text up with audio. This endpoint.

Several speakers

Use audio intelligence — the same endpoint and the same model, asked for verbose_json, which adds speaker labels.

A live microphone

Use a realtime session. It streams, and it decides where turns end.

Do not chop a live microphone into repeated POSTs. It costs a round trip per chunk, and it cuts turns at arbitrary boundaries rather than where somebody stopped talking — which is the difference between a transcript you can read and a wall of fragments.

The request

Everything is a form field on a multipart/form-data body.

Field	Required	Notes
`file`	Yes	The audio. Anything ffmpeg decodes: WAV, MP3, FLAC, OGG, M4A, WebM, and video containers with an audio track.
`model`	Yes	An `stt` id from `GET /v1/audio/models`.
`language`	No	A language hint. Omit it to auto-detect.
`response_format`	No	`json` (default), `text` or `verbose_json`. See below before reaching for `srt` or `vtt`.
`timestamp_granularities[]`	No	`word`, `segment`, or both. The square brackets are part of the field name.
`temperature`	No	Decoding temperature, default `0.0`.
`prompt`	No	Accepted and forwarded, for OpenAI compatibility. The model serving both transcription ids in production ignores it, so do not expect it to bias spellings.
`stream`	No	`true` streams SSE while the model decodes. Default `false`.

What each `response_format` gives you

Value	Body
`json`	`{"text": "…"}` and nothing else.
`text`	The transcript as `text/plain`.
`verbose_json`	The full payload: `duration`, `language`, `segments` with timings, and — on a diarizing model — speakers, word timing, confidence and acoustics. See Audio intelligence.

srt and vtt are in the request schema, and no transcription backend in this catalog serves them. Sending either reaches the model and comes back as a relayed 400: response_format 'srt' is not supported. Supported: json, text, verbose_json. Ask for verbose_json and build the caption file from segments — you need the timings anyway.

Pass `language` when you know it

Auto-detection is decided from the opening seconds. A recording that starts with noise, hold music, or a greeting in a different language can be identified wrongly, and once it is, the entire transcript comes back in the wrong language. That failure is total rather than partial, which is what makes the hint worth sending even when detection is usually right.

curl https://api.eesi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -F file=@interview.wav \
  -F model=nur-stt-v1 \
  -F language=en \
  -F response_format=verbose_json

A supplied language is echoed back untouched. When you omit it, the response carries the detected code and a language_probability beside it.

Timings and segments

verbose_json is what lets you line a transcript up with the audio it came from — build captions, jump a player to a phrase, or index a recording for search.

{
  "task": "transcribe",
  "language": "en",
  "duration": 3.2,
  "text": "The rain had not stopped for three days.",
  "segments": [
    {
      "id": 0,
      "start": 0.07,
      "end": 3.2,
      "speaker": "S01",
      "text": "The rain had not stopped for three days.",
      "pace_wpm": 165,
      "audibility": "on_mic"
    }
  ]
}

Transcription is one diarizing model, so verbose_json carries speaker and the acoustic fields even when you asked for plain transcription. They are part of what nur-stt-v1 is, not a tier you upgrade into. Skip the word-alignment pass with timestamp_granularities[]=segment. On a long file that is worth a few seconds of GPU time.

Streaming a long decode

A long recording decodes for minutes. stream=true turns the response into server-sent events so you can show progress rather than a spinner:

import httpx, json

with httpx.Client(base_url="https://api.eesi.ai", timeout=None) as http:
    with http.stream(
        "POST",
        "/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"file": ("interview.mp3", open("interview.mp3", "rb"), "audio/mpeg")},
        data={"model": "nur-stt-v1", "stream": "true"},
    ) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if not line.startswith("data:"):
                continue
            event = json.loads(line[5:])
            if event["type"] == "transcript.segment":
                segment = event["segment"]
                print(f"[{segment['start']:.1f}s] {segment['text']}")

The frames are transcript.text.delta as text accumulates, transcript.segment per finished segment, and one transcript.text.done carrying the whole verbose_json payload in a verbose field — so a streaming client never needs a second request for the authoritative result. Each segment’s end is how far into the audio the model has reached, which makes a progress bar end / duration. A model whose backend cannot stream still honours stream=true: the batch call runs and the finished transcript arrives as one transcript.text.delta followed by transcript.text.done. You get the contract, not the progress.

Limits and cost


Price	$0.001 per minute of audio.
Request rate	60 requests per minute per organization.
Upload	The gateway admits up to 1 GB for a diarizing model and 25 MB otherwise. The serving deployment sets the real ceiling — 256 MB on current production hardware — so a 400 MB file passes the gateway and is refused by the model.
Decode time	Up to 30 minutes of upstream read budget on a long-form model. Cold starts count against it.
Duration	No minute count is enforced. The serving pool’s context window is what binds — 32,768 tokens shared between the audio and a transcript that costs roughly 15 tokens per second of speech — and the service’s audio handling is sized for files up to about 90 minutes. A decode that runs out mid-file is cut rather than refused, and `verbose_json` says so with `truncated: true`. Split at silence boundaries and check the flag.
Free plan	1,800 seconds of transcription per day, resetting at 00:00 UTC, for organizations that have never bought credits.

Uploads are read in chunks and refused as soon as they cross the cap, so an oversized file is rejected rather than buffered. The message names the cap and what to do about it. Billing follows the audio, not the request: json and verbose_json are metered on the duration the model reports, and text on the duration measured from the file you sent. A client that hangs up mid-stream is still billed, because the decode was already spent.

Failures

Status	`code`	What happened
400	—	`response_format` is `srt` or `vtt`, relayed from a backend that serves neither.
400	`model_wrong_kind`	You named a `tts` id. The message names the endpoint that serves it.
404	`model_not_found`	No catalog entry has that id or alias. Read `GET /v1/audio/models`.
413	`content_size_limit_exceeded`	The upload is over the gateway’s cap. Split the recording.
429	`rate_limit_exceeded`	Over 60 requests a minute.
429	`free_tier_daily_limit`	The free plan’s daily ceiling. Resets at 00:00 UTC.
429	`insufficient_quota`	The prepaid balance is empty.
502	`upstream_unreachable`	The serving backend did not answer. Retry with backoff.
502	`upstream_auth_misconfigured`	The gateway’s own credentials were refused upstream. Never your key — report it.
502	`upstream_protocol_error`	The backend answered with something that is not a transcription — no JSON, no `text`. Retry once, then report it.
503	`model_unavailable`	A real `stt` id with no backend wired up in this deployment. Pick a served id.
503	`server_busy`	Too many uploads are in flight on this instance. Retry with backoff.

One mistake, three statuses. A model id that does not work here answers 404 when nothing in the catalog has it, 400 when it is real but belongs to another endpoint, and 503 when it is the right kind and this deployment has no backend for it. The last is a deployment fact rather than a mistake in your request, which is why it is not a 4xx.

Audio intelligence

Speakers, word timing and audibility from the same endpoint.

Transcribe a meeting

The whole recipe, including naming the speakers.

Live conversation

A microphone rather than a file.

Models

Which id serves what, and how to read the catalog.

Authentication

Where an sk-eesi-… key comes from, and what a bad one looks like.

Start here

Realtime interaction

Speech

Platform

Is this the right endpoint

A recording you already have

Captions and search

Several speakers

A live microphone

The request

What each `response_format` gives you

Pass `language` when you know it

Timings and segments

Streaming a long decode

Limits and cost

Failures

Next

Audio intelligence

Transcribe a meeting

Live conversation

Models

Authentication

​Is this the right endpoint

A recording you already have

Captions and search

Several speakers

A live microphone

​The request

​What each response_format gives you

​Pass language when you know it

​Timings and segments

​Streaming a long decode

​Limits and cost

​Failures

​Next

Audio intelligence

Transcribe a meeting

Live conversation

Models

Authentication

Is this the right endpoint

The request

What each `response_format` gives you

Pass `language` when you know it

Timings and segments

Streaming a long decode

Limits and cost

Failures

Next