Diktat

Diktat · von Holdenried Solutions

Speech to text API: curl, Node and Python examples

Diktat is a German dictation service with an HTTP API. You create a key in your account, send audio to /api/v1/transkription and get text back — optionally smoothed, always with your dictionary as context. This page is readable without an account.

Authentication

Put the key in the Authorization header as Bearer. The key starts with dkt_ and is shown once when created; only its hash is stored. Read it from the environment variable DIKTAT_SCHLUESSEL, never hard-code it.

The request body

{
  "audio_base64": "…",
  "mime": "audio/wav",
  "sprache": "de",
  "glaetten": true
}

curl (Linux, macOS)

# 1. Schlüssel in die Umgebung (nicht ins Repo, nicht in den Quelltext)
export DIKTAT_SCHLUESSEL='dka_…'

# 2. Testaufruf: muss "ok": true liefern
curl -fsS -H "Authorization: Bearer $DIKTAT_SCHLUESSEL" https://diktat.h-ried.com/api/anbindung/ich

# 3. Erkennen und glätten (auf macOS: base64 -i aufnahme.wav | tr -d '\n')
curl -fsS -X POST https://diktat.h-ried.com/api/v1/transkription \
  -H "Authorization: Bearer $DIKTAT_SCHLUESSEL" -H 'Content-Type: application/json' \
  -d '{"audio_base64":"'"$(base64 -w0 aufnahme.wav)"'","mime":"audio/wav","sprache":"de","glaetten":true}'

Node

// DIKTAT_SCHLUESSEL steht in der Umgebung: process.env.DIKTAT_SCHLUESSEL
const fs = require('node:fs');
const antwort = await fetch('https://diktat.h-ried.com/api/v1/transkription', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DIKTAT_SCHLUESSEL}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    audio_base64: fs.readFileSync('aufnahme.wav').toString('base64'),
    mime: 'audio/wav',
    sprache: 'de',
    glaetten: true,
  }),
});
console.log(await antwort.json());

Python

import base64, json, os, urllib.request

schluessel = os.environ['DIKTAT_SCHLUESSEL']
with open('aufnahme.wav', 'rb') as datei:
    audio = base64.b64encode(datei.read()).decode()

koerper = json.dumps({
    'audio_base64': audio,
    'mime': 'audio/wav',
    'sprache': 'de',
    'glaetten': True,
}).encode()
anfrage = urllib.request.Request(
    'https://diktat.h-ried.com/api/v1/transkription',
    data=koerper,
    headers={'Authorization': f'Bearer {schluessel}', 'Content-Type': 'application/json'},
)
print(urllib.request.urlopen(anfrage).read().decode())
# Mit "requests" statt urllib (pip install requests): requests.post(URL, headers={...}, json={...})

Endpoints

CallWhat it returns
POST /api/v1/transkriptionaudio in, text out (optionally smoothed)
GET /api/v1/kontingentfair-use usage, smoothing unlock, balance, prices
GET /api/v1/glossarthe technical-terms dictionary used as context
GET /api/v1/ichwhich account the key belongs to
GET /api/anbindung/ichwhich connection a dka_… key belongs to

Error codes

HTTPCodeWas er bedeutet
401anbindung-widerrufen / —Der Schlüssel fehlt, ist falsch oder wurde widerrufen. Im Konto einen neuen Schlüssel erzeugen.
402guthaben_zu_geringDas Guthaben reicht für das Glätten nicht. Der Rohtext kommt trotzdem mit.
403anbindung-pausiert / konto-nicht-freigeschaltetDie Anbindung ist pausiert oder das Konto wartet auf die Freischaltung.
429anbindung-deckel / fairuseTagesdeckel oder Fair-Use-Grenze erreicht. Zurückgesetzt wird um 00:00 UTC.

As of: