Skip to content

Transcriptions

POST /v1/audio/transcriptions converts recorded speech to text, with timestamps for segments and words and labels for speakers. It accepts OpenAI's transcription request format, so you can use the OpenAI SDKs by changing the base URL to Keln's. It also supports OpenRouter's additions: diarize, keyterms and a JSON body. API keys, rate limits and balance work the same as for chat completions.

from openai import OpenAI

client = OpenAI(base_url="https://api.keln.ai/v1", api_key="sk-keln-…")
with open("speech.mp3", "rb") as audio:
    resp = client.audio.transcriptions.create(model="microsoft/mai-transcribe-2", file=audio)
print(resp.text)
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.keln.ai/v1", apiKey: "sk-keln-…" });
const resp = await client.audio.transcriptions.create({
  model: "microsoft/mai-transcribe-2",
  file: fs.createReadStream("speech.mp3"),
});
console.log(resp.text);
curl https://api.keln.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -F model="microsoft/mai-transcribe-2" \
  -F file="@speech.mp3"

The answer:

{
  "text": "Good afternoon. Hello there.",
  "usage": {"type": "duration", "seconds": 4.2, "cost": 0.000134}
}

The examples use microsoft/mai-transcribe-2. Other transcription models in GET /v1/models accept the same request. Just change the model id.

Request

Send the request as a multipart form, as with OpenAI.

Field Contract
file Required. The audio: WAV, MP3 or FLAC, up to 25 MB. Keln reads the format from the file's bytes, not its name.
model Required. A transcription model id from GET /v1/models: the rows whose output_modalities is ["transcription"]. Keln returns 400 wrong_endpoint for a chat model on this endpoint, and for a transcription model on chat completions.
language Optional. The spoken language as an ISO-639-1 code, such as en. Leave it out and the model detects the language. languages[] with one entry works the same way.
keywords[] Optional. Words and names the model should spell your way, such as product names. OpenRouter's keyterms does the same.
response_format json (the default), text, srt, vtt, verbose_json or diarized_json. See Answers.
timestamp_granularities[] Optional, with verbose_json only, as on OpenAI: segment, word or both. word adds the time of each word.
diarize Optional, with verbose_json only, as on OpenRouter: true labels each segment and word with its speaker.
temperature 0 or left out. Any other value returns 400 param_not_supported.
chunking_strategy auto or left out. Any other value returns 400 param_not_supported.
provider, session_id, trace, user Accepted. Keln removes them before forwarding the request (privacy).

stream: true returns 400 stream_not_supported: a transcription comes back whole. prompt, include[], known_speaker_names[], known_speaker_references[] and source_url return 400 param_not_supported (send spelling hints as keywords[], and the audio itself as file). Keln returns 400 invalid_request for any other field.

The JSON body

Keln also accepts OpenRouter's JSON format. Use Content-Type: application/json and send base64-encoded audio in input_audio.data, with the other fields as described above (arrays for [] fields and a boolean for diarize). Keln detects the audio format from its bytes, so input_audio.format is optional. input_audio.url returns 400 param_not_supported.

{
  "model": "microsoft/mai-transcribe-2",
  "input_audio": {"data": "<the audio file, base64-encoded>", "format": "mp3"},
  "response_format": "verbose_json",
  "diarize": true
}

Answers

response_format What comes back
json text and usage, as in the example above.
text, srt, vtt The plain text, SubRip subtitles or WebVTT subtitles, as text/plain, application/x-subrip or text/vtt.
verbose_json task, language, duration, text, segments and usage, plus words when you ask for word times. With diarize, each segment and word carries speaker: 0 for the first voice heard, 1 for the next, and so on.
diarized_json OpenAI's speaker form: segments of type transcript.text.segment, each with speaker lettered A, B and on in the order the voices are first heard, and text with one line per segment, such as A: Good afternoon.

A verbose_json answer with word timestamps and speakers:

curl https://api.keln.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -F model="microsoft/mai-transcribe-2" \
  -F file="@speech.mp3" \
  -F response_format="verbose_json" \
  -F "timestamp_granularities[]=segment" \
  -F "timestamp_granularities[]=word" \
  -F diarize="true"
{
  "task": "transcribe",
  "language": "english",
  "duration": 4.2,
  "text": "Good afternoon. Hello there.",
  "segments": [
    {"id": 0, "start": 0.96, "end": 1.6, "text": "Good afternoon.", "speaker": 0},
    {"id": 1, "start": 2.0, "end": 3.5, "text": "Hello there.", "speaker": 1}
  ],
  "words": [
    {"word": "Good", "start": 0.96, "end": 1.2, "speaker": 0},
    {"word": "afternoon.", "start": 1.2, "end": 1.6, "speaker": 0},
    {"word": "Hello", "start": 2.0, "end": 2.5, "speaker": 1},
    {"word": "there.", "start": 2.6, "end": 3.5, "speaker": 1}
  ],
  "usage": {"type": "duration", "seconds": 4.2, "cost": 0.000134}
}

language uses the name OpenAI's answers use (english, not en). Times are in seconds from the start of the file.

Limits

  • 25 MB per file, OpenAI's limit, on every model. A larger file returns 400 invalid_request; a request body far past any 25 MB file returns 413 request_too_large.
  • Length and languages depend on the model. A file longer than the model takes returns 400 transcription_shape_not_supported. Each model's page on keln.ai/models lists its longest file and the languages it understands.

Billing

Keln bills transcription models per second of audio, with no minimum. usage.seconds shows the billed duration and usage.cost shows the exact charge. GET /v1/models lists the price per second of audio in pricing.prompt; Models & pricing shows it per hour. Before sending the audio, Keln reserves the file's cost at the model's price against your balance, as it does for tokens on chat.

Errors

Code Meaning
audio_format_not_supported The file isn't WAV, MP3 or FLAC.
transcription_shape_not_supported The model can't take this audio: a file longer than the model's limit, or an option it doesn't offer.
param_not_supported A field this endpoint doesn't take (see Request).
stream_not_supported stream: true.
wrong_endpoint A chat model on this endpoint, or a transcription model on chat completions.
invalid_request A field Keln doesn't take, or a malformed one: no file, an empty one, one over 25 MB, a language that isn't a two-letter code, or timestamp_granularities[] or diarize without verbose_json.
request_too_large (413) A request body far larger than any 25 MB file needs.
503 with Retry-After Keln is busy. Retry after the number of seconds in Retry-After.
model_not_found, rate and balance errors As on every Keln endpoint (errors & limits).

Keys, budgets and zero data retention work the same as on chat completions.