speeeakHilfe & Dokumentation

Entwickler › API

API

Sprachnachrichten aus eigener Software anlegen, abfragen, löschen und in Text umwandeln – mit einem API-Schlüssel.

Die Speeeak-API ist für Partner gedacht, die Sprachnachrichten in eigene Oberflächen einbauen – Support-Systeme, Apps, Chatbots. Schlüssel vergeben wir auf Anfrage an Partner.

Anmeldung

Jede Anfrage trägt den Schlüssel in der Kopfzeile:

Authorization: Bearer DEIN-SCHLÜSSEL
Antwort Bedeutung
401 Schlüssel fehlt oder ist unbekannt
403 Schlüssel gesperrt oder abgelaufen
429 Limit erreicht (Retry-After sagt, wann es weitergeht)

Basis-Adresse: https://speeeak.de/api/v1

Endpunkte

Eigenen Schlüssel prüfen

GET /api/v1/schluessel → Name, Tarif, Limits, Verbrauch heute/gesamt, Ablauf, Webhook.

Sprachnachricht anlegen

POST /api/v1/nachrichten – multipart/form-data

Feld Pflicht Bedeutung
audio ja Audiodatei (webm/ogg/mp3/m4a/wav/flac/aac; Größe und Länge laut Tarif)
referenz nein eigene Kennung, z. B. Ticketnummer (max. 120 Zeichen)
antwort_auf nein Kennung einer bestehenden Nachricht → wird als Antwort verkettet
webhook_url nein https-Adresse nur für diese Nachricht
transkript nein 1 = Text erzeugen (wenn der Tarif es erlaubt)

Antwort 201:

{
  "kennung": "…", "hoerlink": "https://speeeak.de/n/…", "loeschlink": "https://speeeak.de/n/…/loeschen/…",
  "referenz": "Ticket-4711", "dauer_ms": 4008, "groesse_bytes": 38927, "format": "webm",
  "angehoert": 0, "antwort_auf": null, "erstellt_am": "…", "laeuft_ab_am": "…",
  "transkript_status": "wartet", "transkript": null, "transkript_sprache": null
}

transkript_status: keins · wartet (meist < 30 s) · fertig · leer (keine Sprache erkannt) · fehler.

Nur in Text umwandeln (ohne Speichern)

POST /api/v1/transkript – multipart/form-data, Feld audio (optional sprache, z. B. de) → { "text": "…", "sprache": "de", "dauer_ms": 8900 }. Nichts wird gespeichert.

Nachricht abfragen

GET /api/v1/nachrichten/{kennung} → wie oben, zusätzlich antworten: [ {kennung, hoerlink, dauer_ms, erstellt_am}, … ]. Nur eigene Nachrichten, sonst 404.

Nachricht löschen

DELETE /api/v1/nachrichten/{kennung} → { "geloescht": true }.

Webhook „Antwort eingegangen“

Antwortet jemand auf eine Partner-Nachricht, ruft Speeeak die Webhook-Adresse auf:

POST <webhook_url>
Content-Type: application/json
X-Speeeak-Ereignis: antwort_eingegangen
X-Speeeak-Signatur: <HMAC-SHA256 des Rumpfs mit deinem Webhook-Geheimnis>

{ "ereignis": "antwort_eingegangen", "zeitpunkt": "…",
  "original": { "kennung": "…", "referenz": "Ticket-4711" },
  "antwort":  { "kennung": "…", "hoerlink": "https://…", "dauer_ms": 3000, "erstellt_am": "…" } }

Das Webhook-Geheimnis bekommst du zusammen mit dem Schlüssel. Prüfe die Signatur, bevor du die Daten verarbeitest. Antwortet dein Server nicht mit 2xx, versucht Speeeak es nach 1, 10 und 60 Minuten erneut.

Was die API bewusst nicht kann

Audio-Dateien herunterladen (Partner bekommen Links), fremde Nachrichten sehen, Nachrichten anderer Schlüssel löschen.

Beispiel mit curl

curl -X POST https://speeeak.de/api/v1/nachrichten \
  -H "Authorization: Bearer DEIN-SCHLÜSSEL" \
  -F "audio=@aufnahme.m4a" -F "referenz=Ticket-4711" -F "transkript=1"