Custom terminology

Speech to Text writes what it hears. A bank name, a product or an acronym often comes out spelled the way it sounds: امريتس ان بي دي instead of Emirates NBD, or kay why see instead of KYC. Send your terms in the terminology field and the result carries a corrected copy of the transcript, with every change listed.

The words as heard are never lost. transcription stays exactly as it was transcribed; the corrected text is in terminology.corrected.

When to use it

• Your callers say brand, product or place names that a general model spells its own way.
• You need acronyms written as letters: KYC, IBAN, SWIFT.
• The same name is said in Arabic and English, and you want one spelling.

Terminology does not change what the model hears. It corrects the text after transcription, so a word the model missed entirely cannot be added.

Quick example

Send terminology as a JSON string beside file and language. It works on POST /v1/speech-to-text/sync and POST /v1/speech-to-text.

curl -X POST "https://api.echonova.ai/v1/speech-to-text/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@call.mp3;type=audio/mpeg" \
  -F "language=ar" \
  -F 'terminology={"keywords": ["KYC", {"term": "Emirates NBD", "variants": ["امريتس ان بي دي"]}]}'

import json
import requests

terminology = {
    "keywords": [
        "KYC",
        {"term": "Emirates NBD", "variants": ["امريتس ان بي دي"]},
        {"term": "SWIFT", "context_words": ["transfer", "تحويل"]},
    ]
}

with open("call.mp3", "rb") as audio:
    response = requests.post(
        "https://api.echonova.ai/v1/speech-to-text/sync",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("call.mp3", audio, "audio/mpeg")},
        data={"language": "ar", "terminology": json.dumps(terminology)},
    )

data = response.json()["data"]
print(data["transcription"])              # as heard
print(data["terminology"]["corrected"])   # spelled your way

The response adds a terminology object:

{
  "transcription": "حولت المبلغ عبر السويفت إلى امريتس ان بي دي أمس.",
  "terminology": {
    "raw": "حولت المبلغ عبر السويفت إلى امريتس ان بي دي أمس.",
    "corrected": "حولت المبلغ عبر الـSWIFT إلى Emirates NBD أمس.",
    "edits": [
      { "start": 16, "end": 23, "original": "السويفت", "replacement": "الـSWIFT", "stage": "phonetic", "score": 1 },
      { "start": 28, "end": 43, "original": "امريتس ان بي دي", "replacement": "Emirates NBD", "stage": "exact", "score": 1 }
    ],
    "nearMisses": [],
    "warnings": [],
    "mapperStatus": "applied",
    "mapperVersion": "3.0.0"
  }
}

With the asynchronous endpoint, the same object is on the job from GET /v1/speech-to-text/jobs/{jobId} once it completes, and in the job.completed webhook.

Keyword fields

terminology is {"keywords": [...]}. Each keyword is a plain string, or an object when you want more control.

Terms, variants and other phrases are up to 100 characters each. Fields not in this table are ignored.

How matching works

Matching ignores case, Arabic hamza forms (أ إ آ), ى and ة, and diacritics. A match is always whole words and never crosses a comma or the end of a sentence.

score runs from 0 to 1. Exact and phonetic matches apply. A fuzzy match applies when it is close enough, or when it is a little less close but one of your context_words, or another keyword, is nearby. Short acronyms such as IT or API match exactly only, so they never replace an everyday word.

Arabic prefixes stay on the word: السويفت becomes الـSWIFT, and بالكي واي سي becomes بالـKYC. Digits, e-mail addresses and URLs are never changed.

Read the result

Use the offsets to highlight corrections in your own interface: raw.slice(edit.start, edit.end) is always edit.original.

Without the terminology field the response has no terminology key at all, and the endpoint behaves exactly as before.

Downloads stay as heard

GET /v1/speech-to-text/jobs/{jobId}/export builds TXT, SRT and JSON from transcription and its timed segments, so downloads keep the words as heard. Take terminology.corrected from the job for the corrected text.

Near misses

A near miss is a match the service was not sure enough to apply, for example اونلاين بانكنق for Online Banking at a score of 0.81. It is listed in nearMisses with the words heard, the candidate term and a score, and the transcript is left unchanged there.

Nothing is remembered between requests. To have a near miss fixed next time, show it to a person, and when they confirm it, add the heard words to that term's variants in the list you send.

Live streams

On wss://api.echonova.ai/v1/speech-to-text/stream, send a terminology message at any time. It applies to every segment after it:

{
  "type": "terminology",
  "terminology": { "keywords": ["KYC", { "term": "Emirates NBD", "variants": ["امريتس ان بي دي"] }] }
}

The server answers {"type": "terminology.set", "active": true}, and each transcript message then carries a terminology object for its segment, with offsets into that segment's text. Send it again to replace the list, or with "terminology": null to clear it.

A list that is not valid gets an error message with code validation_failed and is ignored; the session continues with the terms it had. The message must fit in one 64 KiB frame, which holds a few hundred keywords.

Limits

Terminology is free: the request costs the same with or without it.

Errors

A terminology field that cannot be read answers 400 before anything is transcribed or charged.

If the matching itself fails or takes too long, the transcription still completes: mapperStatus is skipped, corrected equals raw, and warnings says why.

FAQ

Does terminology make transcription slower?

Barely. A list of a few thousand keywords on a five-minute call adds well under a second.

Can I store a list and refer to it by name?

No. Send the full list with every request. Keep it in your own system and add confirmed near misses to it over time.

Why did a term not apply?

Check nearMisses first: the match may have been too uncertain. Then add the heard words as a variant, or add context_words so a close match can apply when they are nearby.

Is the Speech to Text playground the same feature?

Yes. The playground's Terminology option sends the same field and shows the corrected transcript with each change highlighted.

Related

• Speech to Text formats and output
• Live transcription
• Transcribe audio synchronously
• Stream speech to text
• Errors