Batch transcription

If you already have a recording and do not need text while it plays, post the file and get one response.

POST /v1/transcribe HTTP/1.1
Host: api.utter.cc
Authorization: Bearer utt_live_…
Content-Type: multipart/form-data

Request

Sent as multipart/form-data.

Field	Required	Default	Notes
file	yes		The audio file.
tier	no	standard	ultra, turbo, standard, economy. Sets the rate you pay. See Latency tiers.
language	no	hi-IN+en-IN	hi-IN+en-IN, hi-IN, en-IN. See Languages.

Unlike the WebSocket, this endpoint accepts a container: WAV, FLAC, MP3, M4A, OGG and WebM are decoded server side, and multi channel audio is mixed down to mono. Sending 16 kHz mono to begin with avoids a decode step and is the fastest path.

curl

curl https://api.utter.cc/v1/transcribe \
  -H "Authorization: Bearer $UTTER_API_KEY" \
  -F "[email protected]" \
  -F "tier=standard" \
  -F "language=hi-IN+en-IN"

Python

With pip install requests:

batch.py

import os
import requests

with open("meeting.wav", "rb") as f:
    response = requests.post(
        "https://api.utter.cc/v1/transcribe",
        headers={"Authorization": f"Bearer {os.environ['UTTER_API_KEY']}"},
        files={"file": ("meeting.wav", f, "audio/wav")},
        data={"tier": "standard", "language": "hi-IN+en-IN"},
        timeout=300,
    )

if response.status_code != 200:
    error = response.json()["error"]
    raise SystemExit(f"{error['code']}: {error['message']}")

result = response.json()
print(result["text"])
for segment in result["segments"]:
    print(f"  [{segment['start']:6.2f} → {segment['end']:6.2f}] {segment['text']}")

Response

200 OK, application/json:

{
  "text": "Invoice share kar diya hai, meeting 5 baje start hoti hai. Deck abhi finalise kar raha hoon.",
  "segments": [
    {
      "start": 0.0,
      "end": 4.62,
      "text": "Invoice share kar diya hai, meeting 5 baje start hoti hai."
    },
    {
      "start": 4.9,
      "end": 8.52,
      "text": "Deck abhi finalise kar raha hoon."
    }
  ],
  "language": "hi-IN+en-IN",
  "tier": "standard",
  "audio_s": 8.52,
  "billed_s": 8.52
}

Field	Meaning
text	The whole transcript, segments joined in order.
segments	Each closed segment, with start and end in seconds from the start of the file.
language	The language setting that was used.
tier	The tier that served the request, and the rate it was metered at.
audio_s	Duration of the decoded audio, in seconds.
billed_s	Seconds metered for this request.

Choosing batch or streaming

Batch is one request and one response, which is simpler to operate. It costs the same per second of audio as streaming on the same tier, so for a recording the cheapest correct choice is usually economy, whose extra latency does not matter when nobody is waiting on a live caption.

Reach for streaming when a person is listening, when the audio is being captured now, or when you want to show text before the speaker stops.

Errors

Failures use the same envelope as everything else, with the HTTP status carrying the category. See Errors.