Developer API

Base URL and version

All Loquino API endpoints live under the prefix https://loquino.de/api/v1. Breaking changes will ship as a separate version /api/v2, while the current version /api/v1 keeps working.

https://loquino.de/api/v1

Submit a file for transcription

Submit a file to POST https://loquino.de/api/v1/transcriptions as multipart/form-data with the header Authorization: Bearer sk_live_…; the Loquino API responds with 202 Accepted and a job id. Form fields: file (required), diarization (true/false, enabled by default) and webhook_url (optional).

curl -X POST https://loquino.de/api/v1/transcriptions \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "file=@meeting.mp3" \
  -F "diarization=true" \
  -F "webhook_url=https://your-app.example/webhooks/loquino"

# 202 response:
{ "id": "…", "status": "queued", "duration_sec": 372, "cost_kopecks": 4200 }

In the 202 response, duration_sec is the measured recording length and cost_kopecks is the amount debited from your balance on submission (in the example 372 s = 7 billable minutes). Transcription runs in the background: fetch the result by polling or webhook.

Check status and get the result

Check whether a job is ready with GET https://loquino.de/api/v1/transcriptions/{id} using the same Bearer key: poll it until status becomes done or failed. While the job is not ready, the response has no transcript fields.

curl https://loquino.de/api/v1/transcriptions/ID \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# When ready:
{
  "id": "…",
  "status": "done",
  "duration_sec": 372,
  "language": "en",
  "text": "The full transcript…",
  "segments": [ { "start": 0.0, "end": 3.2, "text": "…" } ],
  "speakers": [ { "start": 0.0, "end": 3.2, "speaker": "Speaker 1", "text": "…" } ]
}

The Loquino API marks speaker separation with the labels “Speaker 1”, “Speaker 2” within a single recording — with no mapping to real people and no identification of the speaker by voice.

List jobs

The request GET https://loquino.de/api/v1/transcriptions?limit=&cursor= returns the account's jobs, newest first. Paging is cursor-based: pass next_cursor from the response into the cursor parameter of the next request.

Download to a file

The Loquino API returns a finished transcript as a file via GET https://loquino.de/api/v1/transcriptions/{id}/export?format=docx. Available export formats are docx, srt, txt and xlsx; the endpoint works only for jobs in the done status.

Webhooks

If webhook_url was provided when submitting a file, Loquino sends it a POST notification when the job finishes. A Loquino webhook is a signal, not a data delivery: the body contains exactly three fields — id (the job id), status (done or failed) and event (transcription.completed or transcription.failed). The transcript is not in the notification. The same event is duplicated in the X-Svitok-Event header — convenient for routing without parsing the body.

{
  "id": "e3f1a2b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "done",
  "event": "transcription.completed"
}

On receiving a notification, fetch the result yourself: GET https://loquino.de/api/v1/transcriptions/{id} with your Authorization: Bearer sk_live_… header returns the text, segments and speaker replies. This scheme (a signal plus a request for the data) means the transcript is delivered only to whoever presents a valid API key.

There is no notification signature to verify — there is none, and none is needed. Anyone who knows your handler's address could in theory forge the signal, but there is nothing to gain: the body carries no transcript, and your handler fetches the real data from the Loquino API by key. The most a forged call achieves is an extra status request for a job you do not have or that is not ready yet.

// Express example: signal → fetch the data by key. A 2xx response = accepted.
app.post("/webhooks/loquino", express.json(), async (req, res) => {
  const { id, status } = req.body;
  // Respond immediately: the handler must not wait for the result to load.
  res.sendStatus(200);
  if (status !== "done") return;

  // Fetch the data yourself — with your own key, from us.
  const r = await fetch(`https://loquino.de/api/v1/transcriptions/${id}`, {
    headers: { Authorization: `Bearer ${process.env.LOQUINO_API_KEY}` },
  });
  const result = await r.json();
  // result.text, result.segments, result.speakers — dedupe by result.id
});

Notification delivery is idempotent (one successful delivery per job) and retried with increasing backoff on errors. Loquino only sends notifications to public addresses — internal and local URLs are rejected when the file is submitted. Deduplicate incoming events by the id field.

Error codes

The Loquino API returns errors in a single shape: { "error": { "code": "…", "message": "…" } } with the corresponding HTTP status.

Limits

• File — up to 10 GB, recording — up to 6 hours.
• Up to 60 submissions per hour per API key.
• Formats: mp3, wav, m4a, ogg, opus, aac, flac, aiff, wma, mp4, mov, m4v, webm, mkv, avi, 3gp, wmv, mpeg, mpg, ts, flv — audio and video (the audio track is taken from video).

The Loquino API rejects a size or duration overage with code 413 and a submission-rate overage with code 429; a rejected request is not charged.

Billing

Transcription via the Loquino API is billed from your Loquino account balance per minute of recording; speaker separation is included. The amount is debited from your balance when the file is submitted, and minutes are rounded up (a partial minute is billed as a full minute). If a job fails, the debited amount is automatically refunded to your balance.

Submitting with diarization=false (no speaker separation) is billed at a lower per-minute rate than the base rate.

A machine-readable description of the Loquino API is available as OpenAPI 3.1. Audio and transcripts are processed within the EU.

Frequently asked questions