speeeakHelp & Documentation

Developers › API

API

Create, query, delete and transcribe voice messages from your own software – with an API key.

The Speeeak API is intended for partners who build voice messages into their own interfaces – support systems, apps, chatbots. We issue API keys to partners on request.

Authentication

Every request carries the API key in the header:

Authorization: Bearer ***
Response Meaning
401 API key missing or unknown
403 API key blocked or expired
429 Limit reached (Retry-After tells you when to continue)

Base URL: https://speeeak.io/api/v1

Endpoints

Check your own API key

GET /api/v1/schluessel → name, plan, limits, usage today/total, expiry, webhook.

Create a voice message

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

Field Required Meaning
audio yes audio file (webm/ogg/mp3/m4a/wav/flac/aac; size and length according to plan)
referenz no your own reference, e.g. ticket number (max. 120 characters)
antwort_auf no message ID of an existing message → is chained as a reply
webhook_url no https address for this message only
transkript no 1 = generate text (if the plan allows it)

Response 201:

{
  "kennung": "…", "hoerlink": "https://speeeak.io/n/…", "loeschlink": "https://speeeak.io/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 (none) · wartet (pending, usually < 30 s) · fertig (done) · leer (empty, no speech detected) · fehler (error).

Transcribe only (without saving)

POST /api/v1/transkript – multipart/form-data, field audio (optional sprache, e.g. de) → { "text": "…", "sprache": "de", "dauer_ms": 8900 }. Nothing is saved.

Query a message

GET /api/v1/nachrichten/{kennung} → as above, plus antworten: [ {kennung, hoerlink, dauer_ms, erstellt_am}, … ]. Only your own messages, otherwise 404.

Delete a message

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

Webhook “reply received”

When someone replies to a partner message, Speeeak calls the webhook address:

POST <webhook_url>
Content-Type: application/json
X-Speeeak-Ereignis: antwort_eingegangen
X-Speeeak-Signatur: <HMAC-SHA256 of the body with your webhook secret>

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

You receive the webhook secret together with the API key. Verify the signature before you process the data. If your server does not respond with 2xx, Speeeak retries after 1, 10 and 60 minutes.

What the API deliberately cannot do

Download audio files (partners get links), see other people's messages, delete messages of other API keys.

Example with curl

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