Speech to text

Two endpoints, one recogniser (Whisper large-v3):

Transcription without speaker labels

POST /v1/audio/transcriptions

Streaming (stream=true) is not supported here; for live audio use live transcription.

import os
from openai import OpenAI

client = OpenAI(base_url="https://router.appelon.ai/v1", api_key=os.environ["APPELON_API_KEY"])

with open("opname.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(model="whisper-1", file=f, language="nl")
print(transcript.text)

curl -X POST "https://router.appelon.ai/v1/audio/transcriptions" \
  -H "Authorization: Bearer $APPELON_API_KEY" \
  -F "file=@opname.mp3" \
  -F "model=whisper-1" \
  -F "language=nl"

Audio without any speech returns an empty transcript ({"text": ""}), not an error. Billing is per minute of audio, at the same rate as diarization.

Transcription with speaker labels

POST /v1/audio/diarize

Request body

Getting the best transcript

The speaker and vocabulary fields are optional, but on real recordings they make the biggest difference to the result. They cost nothing extra and do not slow the transcription down.

Tell us how many speakers to expect. Without a hint, the number of speakers is estimated from the audio alone. That estimate goes wrong most often on long recordings, similar voices, phone-ins and people talking over each other. You then see two people merged into one SPEAKER_xx, or one person split over several.

• Know the exact number (an interview, a podcast with fixed hosts)? Send num_speakers.
• Know roughly (a radio show with presenters and guests, a meeting)? Send a range with min_speakers and max_speakers, for example 2 and 6. Keep the range realistic: a tight range helps more than a wide one.
• No idea at all? Leave them out.

Give the recogniser your vocabulary. Names of people, places, programmes and organisations are the words speech recognition gets wrong most often. List the ones you expect in initial_prompt, comma separated, spelled the way you want them in the transcript:

initial_prompt=Jan de Vries, Stadskanaal, Eemsdelta, Provinciale Staten, Waterschap Hunze en Aa's

Only list words that actually occur. The prompt is a hint, not an instruction: do not write sentences or requests in it.

Set the language. language=nl skips auto-detection, which can misfire on a recording that starts with music, jingles or an English quote.

curl -X POST "https://router.appelon.ai/v1/audio/diarize" \
  -H "Authorization: Bearer $APPELON_API_KEY" \
  -F "file=@uitzending.mp3" \
  -F "model=whisperx" \
  -F "language=nl" \
  -F "min_speakers=2" \
  -F "max_speakers=6" \
  -F "initial_prompt=Jan de Vries, Stadskanaal, Eemsdelta, Provinciale Staten"

The same fields work on asynchronous jobs.

Example request

The diarization endpoint is not part of the OpenAI SDK, so use a direct HTTP request.

import os
import requests

response = requests.post(
    "https://router.appelon.ai/v1/audio/diarize",
    headers={"Authorization": f"Bearer {os.environ['APPELON_API_KEY']}"},
    files={"file": open("interview.mp3", "rb")},
    data={"model": "whisperx", "language": "nl"}
)

result = response.json()
for segment in result["segments"]:
    print(segment["speaker"], segment["text"].strip())

curl -X POST "https://router.appelon.ai/v1/audio/diarize" \
  -H "Authorization: Bearer $APPELON_API_KEY" \
  -F "file=@interview.mp3" \
  -F "model=whisperx" \
  -F "language=nl"

Response with speaker labels

WhisperX provides speaker diarization: it identifies different speakers in the audio.

{
  "language": "nl",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "Welkom bij dit interview.",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 2.8,
      "end": 5.1,
      "text": "Dank je wel voor de uitnodiging.",
      "speaker": "SPEAKER_01"
    }
  ]
}

Each segment also has a words list with per-word timestamps, and the response has a flat word_segments list of all words. Note that the response’s top-level text field is not a string: for compatibility it holds the same list as segments. For the plain text, join segments[].text, or use /v1/audio/transcriptions when you do not need speaker labels.

Audio without any speech returns an empty transcript (empty segments), not an error.

Speaker embeddings

Speaker labels are only consistent within one recording: SPEAKER_00 in one file has no relation to SPEAKER_00 in the next. To recognise the same voice across recordings, request speaker embeddings:

response = requests.post(
    "https://router.appelon.ai/v1/audio/diarize",
    headers={"Authorization": f"Bearer {os.environ['APPELON_API_KEY']}"},
    files={"file": open("interview.mp3", "rb")},
    data={"model": "whisperx", "language": "nl", "return_speaker_embeddings": "true"}
)

embeddings = response.json()["speaker_embeddings"]
# {"SPEAKER_00": [0.0123, -0.0456, ...], "SPEAKER_01": [...]}

curl -X POST "https://router.appelon.ai/v1/audio/diarize" \
  -H "Authorization: Bearer $APPELON_API_KEY" \
  -F "file=@interview.mp3" \
  -F "model=whisperx" \
  -F "language=nl" \
  -F "return_speaker_embeddings=true"

The response gains a speaker_embeddings object with one 256-dimensional vector per detected speaker. Compare vectors with cosine similarity; the same person in two recordings scores high, different people score low. Store the vectors on your side, keyed by the person you identified.

Appelon returns the embeddings and does not store them. Voice embeddings are biometric data under the GDPR (AVG), so storing and matching them is your responsibility as data controller.

Limits and long recordings

Which one should I use? The synchronous endpoint keeps your HTTP connection open until the transcript is ready. That is the simplest option for recordings up to about an hour. For anything longer, and whenever you do not want to hold a connection open for minutes (a serverless function with a short timeout, a mobile app, a batch of files), use an asynchronous job.

Asynchronous jobs

A job splits one long request into separate steps: you upload the recording and immediately get a job id back, we transcribe it in the background, and you fetch the transcript when it is ready. Nothing breaks if your connection drops in the meantime, and you can submit several recordings at once.

How a job works

1. Submit. You POST the audio file to /v1/audio/diarize/jobs, with the same form fields as the synchronous endpoint. The response comes back within seconds (as soon as the upload is in) with status 202 Accepted and a job id.
2. Wait. The job waits in a queue until a transcription slot is free, then runs. You find out it is ready in one of two ways:
   • Polling: ask for the job’s status every 10 to 30 seconds with GET /v1/audio/diarize/jobs/{id}.
   • Webhook: pass a webhook_url when you submit, and we POST the result to your server as soon as the job ends. No polling needed.
3. Collect. When the status is done, the transcript is in the result field of the status document. It has exactly the same format as the response of the synchronous endpoint.
4. Clean up. We keep the transcript for a limited time (6 hours by default), after which it is deleted automatically. You can delete it earlier with DELETE.

The uploaded audio itself is deleted as soon as the transcription is finished. After that, and after the transcript has been deleted, only the job’s metadata remains (status, timestamps, length).

Job statuses

A job always moves forward: queued, then running, then one of done or failed. Only a queued job can become canceled.

Example: submit and poll

import os
import time
import requests

API = "https://router.appelon.ai/v1/audio/diarize/jobs"
HEADERS = {"Authorization": f"Bearer {os.environ['APPELON_API_KEY']}"}

# 1. Submit: returns as soon as the upload is in
with open("council-meeting.mp3", "rb") as f:
    job = requests.post(
        API,
        headers=HEADERS,
        files={"file": f},
        data={"model": "whisperx", "language": "nl", "min_speakers": "3", "max_speakers": "12"},
    ).json()
print("submitted", job["id"])

# 2. Wait: poll every 15 seconds until the job has ended
while job["status"] in ("queued", "running"):
    time.sleep(15)
    job = requests.get(f"{API}/{job['id']}", headers=HEADERS).json()

# 3. Collect
if job["status"] == "done":
    transcript = job["result"]        # same document as the synchronous endpoint
    print(" ".join(s["text"].strip() for s in transcript["segments"]))
    # 4. Optional: delete the transcript from our side right away
    requests.delete(f"{API}/{job['id']}", headers=HEADERS)
else:
    print(job["status"], job.get("error"))

# 1. Submit
curl -X POST "https://router.appelon.ai/v1/audio/diarize/jobs" \
  -H "Authorization: Bearer $APPELON_API_KEY" \
  -F "file=@council-meeting.mp3" -F "model=whisperx" -F "language=nl" \
  -F "min_speakers=3" -F "max_speakers=12" \
  -F "initial_prompt=Gemeenteraad, Stadskanaal, wethouder Bakker"
# {"id":"job_5f1c...","object":"audio.diarize.job","status":"queued","position":0,...}

# 2 + 3. Check the status; once "done", the transcript is in "result"
curl "https://router.appelon.ai/v1/audio/diarize/jobs/job_5f1c..." \
  -H "Authorization: Bearer $APPELON_API_KEY"

# 4. Delete the transcript (or cancel a job that is still queued)
curl -X DELETE "https://router.appelon.ai/v1/audio/diarize/jobs/job_5f1c..." \
  -H "Authorization: Bearer $APPELON_API_KEY"

Save the job id as soon as you get it (in your database, next to the recording). If your process restarts while it waits, you can pick up where you left off with a GET. Lost the id? GET /v1/audio/diarize/jobs lists your recent jobs.

Request fields

The job endpoint takes every form field of the synchronous endpoint (file, model, language, the speaker counts, initial_prompt, user, session_id), plus two of its own:

Endpoints

Jobs belong to your account: every API key of the account can see and manage them, and any other account gets a 404.

Status document

Every job endpoint (and the webhook) returns the job in this shape:

{
  "id": "job_5f1c2a9e0b7d4c3f8e6a1b2c3d4e5f60",
  "object": "audio.diarize.job",
  "status": "done",
  "created_at": "2026-09-22T13:05:00Z",
  "started_at": "2026-09-22T13:05:02Z",
  "finished_at": "2026-09-22T13:12:40Z",
  "retention_seconds": 21600,
  "expires_at": "2026-09-22T19:12:40Z",
  "audio_seconds": 7415.2,
  "filename": "council-meeting.mp3",
  "result": {"language": "nl", "text": "...", "segments": [...]}
}

Webhooks

With a webhook you do not need to poll: when the job ends, we send a POST to your webhook_url with the status document above as the JSON body.

• When: once the job is done (the body includes the transcript in result) or failed (the body includes error). A job you canceled yourself sends no webhook.
• Your server must answer with a 2xx status within 15 seconds. Anything else counts as a failed delivery, including redirects (we do not follow them). We try three times: immediately, after 5 seconds and after 30 seconds. After that we give up.
• Requirements for the URL: https, on a host that resolves to a public IP address. localhost and private or internal addresses are refused with a 400 when you submit. For local development, use a tunnel service that gives you a public https URL.
• Not signed: the request carries no signature yet, so anyone who knows your URL could send you a fake one. Treat an incoming webhook as a signal that the job has ended, and confirm with a GET on the job before you act on it. Using a hard-to-guess URL (with a random token in the path) helps too.

Webhook only, nothing stored (retention_seconds=0). For the strictest privacy, submit with retention_seconds=0 and a webhook_url. The transcript is then sent to your webhook and never written to disk on our side, so a GET shows the status but no result. The flip side: if all three delivery attempts fail (your server is down, or answers with an error), the transcript is gone and you have to submit the recording again. Only use this when your receiving endpoint is reliable.

When a job fails

A failed job has status: "failed" and an error with a code:

If we restart our gateway while your job is queued or running, the job is not lost: it goes back into the queue and is completed. You are only charged when a job reaches done.

Response codes

These are the HTTP status codes of the job endpoints themselves (errors in the transcription itself end up in the job’s error, see above):

Billing and privacy

Usage is metered once, when the job completes, on the length of the recording and at the same rate as the synchronous endpoint. It shows up in your dashboard like any other transcription.

The uploaded audio and the transcript are stored on our gateway in the Netherlands as encrypted files only, never in a database or a backup. The audio is deleted as soon as the transcription is done. The transcript is deleted when its retention period ends, when you delete it, or is never stored with retention_seconds=0.

Supported formats

• MP3
• WAV
• FLAC
• M4A
• OGG

Language support

WhisperX supports 90+ languages including Dutch, English, German, French, Spanish, and more. Language is auto-detected, but specifying it improves accuracy.

Live transcription

For audio that is happening now (a broadcast, a consult, a meeting) use the realtime endpoint. It speaks the OpenAI Realtime transcription API over a WebSocket, so the OpenAI SDK and most voice frameworks work as they are.

wss://router.appelon.ai/v1/realtime?intent=transcription

Two tiers, one recording:

• Live (/v1/realtime): text while people speak, tentative text within about a second, committed text 2 to 3 seconds behind the audio. Fast, provisional.
• Archive (/v1/audio/diarize): run the same recording through the batch endpoint afterwards for the best quality and stable speaker labels. Keep the recording on your side; Appelon does not store audio.

Connecting

Servers connect with the API key in the Authorization header. Browsers and apps must never hold the API key: your backend requests a short-lived client secret and passes it to the client.

curl -X POST "https://router.appelon.ai/v1/realtime/client_secrets" \
  -H "Authorization: Bearer $APPELON_API_KEY"
# {"value": "ek_...", "expires_at": 1757950000}

The client then connects with ?token=ek_.... A secret is valid for 60 seconds and for one connection.

Sending audio and reading text

import asyncio, base64, os, wave
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["APPELON_API_KEY"],
                     websocket_base_url="wss://router.appelon.ai/v1")

async def main():
    wav = wave.open("studio.wav")  # 16-bit mono PCM, 16 kHz or 24 kHz
    async with client.beta.realtime.connect(model="gpt-4o-transcribe") as conn:
        await conn.session.update(session={
            "type": "transcription",
            "audio": {"input": {
                "format": {"type": "audio/pcm", "rate": wav.getframerate()},
                "transcription": {"model": "gpt-4o-transcribe", "language": "nl"}}},
        })

        async def send():
            while frames := wav.readframes(wav.getframerate() // 10):  # 100 ms
                await conn.input_audio_buffer.append(audio=base64.b64encode(frames).decode())
                await asyncio.sleep(0.1)
        asyncio.create_task(send())

        async for ev in conn:
            if ev.type == "conversation.item.input_audio_transcription.delta":
                print(ev.delta, end="", flush=True)
            elif ev.type == "conversation.item.input_audio_transcription.completed":
                print("\n[final]", ev.transcript)

asyncio.run(main())

Send 16-bit mono PCM at 16 kHz or 24 kHz in chunks of about 100 ms. Events:

Model names whisper-live, gpt-4o-transcribe and gpt-4o-mini-transcribe all map to the same Dutch-tuned model.

Speaker labels

Add "appelon": {"diarize": true} to the session object to get a speaker field (SPEAKER_00, SPEAKER_01) on every delta and completed event. Live labels are provisional: they are assigned within about a second and are unrelated to the labels the batch endpoint gives the same recording.

Interruptions

A session is never resumed. When something ends it, you get an error event with a code and the socket closes; text already delivered as completed is safe, and reconnecting starts a fresh session.

Pricing

Live transcription is metered per minute of audio received, like the batch endpoint. Final pricing for live follows after the pilot.