Improve recognition accuracy

Custom hotwords vs. context enhancement

Model Studio speech recognition provides two approaches for handling specialized terms. Each applies to different models and interfaces:

Supported models and regions

Quick start

import dashscope
from dashscope.audio.asr import *
import os

# The API Keys for the Beijing and Singapore regions are different. Obtain an API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. Configurations vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. Configurations vary by region.
dashscope.base_websocket_api_url = 'wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'
prefix = 'testpfx'
target_model = "fun-asr-realtime"

my_vocabulary = [
    {"text": "Speech Laboratory", "weight": 4}
]

service = VocabularyService()
vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)

try:
    if service.query_vocabulary(vocabulary_id)['status'] == 'OK':
        recognition = Recognition(model=target_model,
                              format='wav',
                              sample_rate=16000,
                              callback=None,
                              vocabulary_id=vocabulary_id)
        result = recognition.call('asr_example.wav')
        print(result.output)
finally:
    # Delete the hotword list regardless of whether recognition succeeded, to avoid occupying quota
    service.delete_vocabulary(vocabulary_id)

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.io.File;
import java.util.ArrayList;
import java.util.List;

public class Main {
    // The API Keys for the Beijing and Singapore regions are different. Obtain an API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If the environment variable is not configured, replace the following line with: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. Configurations vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. Configurations vary by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";

        String targetModel = "fun-asr-realtime";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("Speech Laboratory", 4));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary vocabulary = service.createVocabulary(targetModel, "testpfx", vocabularyJson);

        try {
            if ("OK".equals(service.queryVocabulary(vocabulary.getVocabularyId()).getStatus())) {
                Recognition recognizer = new Recognition();
                RecognitionParam param =
                        RecognitionParam.builder()
                                .model(targetModel)
                                .apiKey(apiKey)
                                .format("wav")
                                .sampleRate(16000)
                                .vocabularyId(vocabulary.getVocabularyId())
                                .build();

                try {
                    System.out.println("Recognition result: " + recognizer.call(param, new File("asr_example.wav")));
                } catch (Exception e) {
                    e.printStackTrace();
                } finally {
                    // Close the WebSocket connection
                    recognizer.getDuplexApi().close(1000, "bye");
                }
            }
        } finally {
            // Delete the hotword list regardless of whether recognition succeeded, to avoid occupying quota
            service.deleteVocabulary(vocabulary.getVocabularyId());
        }
        System.exit(0);
    }
}

class Hotword {
    String text;
    int weight;

    public Hotword(String text, int weight) {
        this.text = text;
        this.weight = weight;
    }
}

Hotword format

Submit hotwords as a JSON array. Each element defines a single hotword and its properties. A vocabulary list (referred to as vocabulary in the API) groups these hotwords for use with a specific model.

Example: Improve the recognition accuracy of movie titles.

[
    {"text": "Seediq Bale", "weight": 4, "lang": "en"},
    {"text": "Goodbye Mr. Loser", "weight": 4, "lang": "en"},
    {"text": "Confucius' Family", "weight": 4, "lang": "en"}
]

Field description:

Tune hotword performance

Limits and billing

Supported models and regions

Quick start

Context enhancement requires no pre-created resources. Simply pass context parameters in your speech recognition request:

• Non-real-time speech recognition: Pass context messages in input.messages of the HTTP request, placed before the audio message.

Use cases: By passing conversation history or domain terminology as context, you can significantly improve transcription accuracy for specialized terms such as names, locations, and product terminology. This feature supports the following scenarios:

• Word list enhancement: Pass domain-specific word lists or terminology through user (input_text) to help the model accurately recognize specialized vocabulary.

• Multi-turn conversation context: In voice interaction scenarios that combine ASR with large language models, pass prior recognition results (user / input_text) and model responses (assistant / text) to improve recognition accuracy for the current turn.

{
    "model": "fun-asr-flash-2026-06-15",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Kubernetes Istio Envoy service mesh sidecar proxy"
                    }
                ]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "Audio URL or Base64 of the current audio to recognize"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {}
}

{
    "model": "fun-asr-flash-2026-06-15",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Prior user speech recognition result"
                    }
                ]
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Prior model response content"
                    }
                ]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "Audio URL or Base64 of the current audio to recognize"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {}
}

Effect example

The text field content format is flexible — it can be a word list, natural language paragraph, or a mix of both. It has high tolerance for unrelated text.

An audio clip should be correctly recognized as: "The jargon within investment banking circles, how much do you know? First, the nine major foreign investment banks, Bulge Bracket, BB ..."

In the example above, adding a word list or natural language paragraph containing terms like "Bulge Bracket" to the text field achieves the enhancement effect.

Q: Why don't hotwords improve recognition accuracy?

Check the following in order:

1. Model mismatch: The target_model specified when creating the list must match the model used by the speech recognition API. A mismatch doesn't cause an error, and recognition still returns results, but the hotwords don't take effect. If the results don't contain expected hotwords, check this first.

2. Unsupported model: The model must belong to the Fun-ASR or Paraformer family. Other families don't support hotwords. Calling the API with an unsupported model doesn't return an error, but the results may be empty or lack hotword enhancement. If using a model such as SenseVoice, check this first.

3. Inappropriate weight: Increase the weight from 4 to 5 and observe the results. If phonetically similar words start being misrecognized as the hotword, reduce it back to 4.

4. Hotword list status: Use the Query API to confirm that status is OK.

Q: Are hotwords used differently in real-time and file-based recognition?

Hotword lists are created the same way. The calling method differs:

• Real-time speech recognition: Pass vocabulary_id in the Recognition or WebSocket connection parameters.

• File-based speech recognition: Pass vocabulary_id in the Transcription request parameters.

In both cases, target_model must match the speech recognition model used in the API call.

Q: How to improve recognition accuracy beyond hotwords?

In addition to hotwords and context enhancement, consider the following:

• Audio quality: Match the sample rate to the model requirements (16 kHz or 8 kHz) and reduce background noise.

• Choose the right model: Different scenarios call for different models. For details, see the Speech-to-text model selection guide.

• Specify the language: Declare the audio language through language_hints to improve accuracy in single-language scenarios.