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
| Call | What it returns |
|---|---|
| POST /api/v1/transkription | audio in, text out (optionally smoothed) |
| GET /api/v1/kontingent | fair-use usage, smoothing unlock, balance, prices |
| GET /api/v1/glossar | the technical-terms dictionary used as context |
| GET /api/v1/ich | which account the key belongs to |
| GET /api/anbindung/ich | which connection a dka_… key belongs to |
Error codes
| HTTP | Code | Was er bedeutet |
|---|---|---|
| 401 | anbindung-widerrufen / — | Der Schlüssel fehlt, ist falsch oder wurde widerrufen. Im Konto einen neuen Schlüssel erzeugen. |
| 402 | guthaben_zu_gering | Das Guthaben reicht für das Glätten nicht. Der Rohtext kommt trotzdem mit. |
| 403 | anbindung-pausiert / konto-nicht-freigeschaltet | Die Anbindung ist pausiert oder das Konto wartet auf die Freischaltung. |
| 429 | anbindung-deckel / fairuse | Tagesdeckel oder Fair-Use-Grenze erreicht. Zurückgesetzt wird um 00:00 UTC. |
As of: