Alibaba Cloud Model Studio:Custom hotwords

Python

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


# API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured an environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'
prefix = 'testpfx'
target_model = "fun-asr-realtime"

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

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

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)

service.delete_vocabulary(vocabulary_id)

Java

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 {
    // API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // If you have not configured an environment variable, replace the following line with your Model Studio API key: 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 is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: wss://dashscope.aliyuncs.com/api-ws/v1/inference
        Constants.baseWebsocketApiUrl = "wss://dashscope-intl.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 Lab", 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);

        if ("OK".equals(service.queryVocabulary(vocabulary.getVocabularyId()).getStatus())) {
            Recognition recognizer = new Recognition();
            // Create a RecognitionParam
            RecognitionParam param =
                    RecognitionParam.builder()
                            .model(targetModel)
                            .apiKey(apiKey)
                            .format("wav")
                            .sampleRate(16000)
                            .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 after the task is complete.
                recognizer.getDuplexApi().close(1000, "bye");
            }
        }

        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;
    }
}

Python SDK

• API description

  Important

  target_model: The speech recognition model that will use the hotword list. This model must be the same as the one specified in subsequent speech recognition API calls.

  def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
      '''
      Create a hotword list.
      param: target_model The speech recognition model for the hotword list. This must be the same as the speech recognition model used in subsequent API calls.
      param: prefix A custom prefix for the hotword list. It must contain fewer than 10 lowercase letters and digits.
      param: vocabulary The hotword list JSON.
      return: The hotword list ID.
      '''

• Code example

  import dashscope
  from dashscope.audio.asr import *
  import os
  
  # API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # If you have not configured an environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
  
  # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
  dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
  
  prefix = 'testpfx'
  target_model = "fun-asr"
  
  my_vocabulary = [
      {"text": "Seediq Bale", "weight": 4}
  ]
  
  # Create a hotword
  service = VocabularyService()
  vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)
  
  print(f"The hotword list ID is: {vocabulary_id}")

Java SDK

• API description

  Important

  targetModel: The speech recognition model that will use the hotword list. This model must be the same as the one specified in subsequent speech recognition API calls.

  /**
   * Create a new hotword list.
   *
   * @param targetModel The speech recognition model for the hotword list. This must be the same as the speech recognition model used in subsequent API calls.
   * @param prefix A custom prefix for the hotword. It must contain fewer than 10 lowercase letters and digits.
   * @param vocabulary The hotword list JSON.
   * @return The hotword list object.
   * @throws NoApiKeyException if the API key is empty.
   * @throws InputRequiredException if a required parameter is empty.
   */
  public Vocabulary createVocabulary(String targetModel, String prefix, JsonArray vocabulary)
      throws NoApiKeyException, InputRequiredException 

• Code example

  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.util.ArrayList;
  import java.util.List;
  
  public class Main {
      // API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
      // If you have not configured an environment variable, replace the following line with your Model Studio API key: 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 is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
          Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
          String targetModel = "fun-asr";
  
          JsonArray vocabularyJson = new JsonArray();
          List<Hotword> wordList = new ArrayList<>();
          wordList.add(new Hotword("Wu Yigong", 4));
          wordList.add(new Hotword("Queli Renjia", 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);
          System.out.println("Hotword list ID: " + vocabulary.getVocabularyId());
      }
  }
  
  class Hotword {
      String text;
      int weight;
      String lang;
  
      public Hotword(String text, int weight) {
          this.text = text;
          this.weight = weight;
      }
  }

RESTful API

• URL

  China (Beijing):

  POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization

  Singapore (International):

  POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

• Request headers

  Parameter	Type	Required	Description
  Authorization	string	Supported	The authentication token. The format is Bearer <your_api_key>. Replace <your_api_key> with your actual API key.
  Content-Type	string	Supported	The media type of the data transferred in the request body. Set the value to application/json.

• Request body

  The following request body includes all request parameters. You can omit optional fields as needed.

  Important

  Note the difference between the following parameters:

  • model: The custom hotword model. Set the value to speech-biasing.

  • target_model: The speech recognition model that will use the hotword list. This model must be the same as the one specified in subsequent speech recognition API calls.

  {
      "model": "speech-biasing",
      "input": {
          "action": "create_vocabulary",
          "target_model": "fun-asr",
          "prefix": "testpfx",
          "vocabulary": [
            {"text": "Seediq Bale", "weight": 4, "lang": "zh"}
          ]
      }
  }

• Request parameters

  Parameter	Type	Default	Required	Description
  model	string	-	Supported	The custom hotword model. Set the value to speech-biasing.
  action	string	-	Supported	The operation type. Set the value to create_vocabulary.
  target_model	string	-	Supported	The speech recognition model that uses the hotword list. For more information, see Supported models. This must be the same as the speech recognition model used in subsequent API calls.
  prefix	string	-	Supported	Specify an easy-to-identify name for the hotword list. It must contain fewer than 10 lowercase letters and digits. This keyword appears in the hotword list ID. For example, if the keyword is "testpfx", the final hotword list ID is "vocab-testpfx-51773d05xxxxxx".
  vocabulary	array[object]	-	Supported	The hotword list JSON. For more information, see Hotwords overview.

• Response parameters

  Click to view an example response

  {
      "output": {
          "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
      },
      "usage": {
          "count": 1
      },
      "request_id": "aee47022-2352-40fe-acfa-xxxx"
  }

  Note the following parameters:

  Parameter	Type	Description
  vocabulary_id	string	The hotword list ID.

• Code example

  The following is a cURL example. For Java and Python examples, see the corresponding SDKs.

  If you have not configured your API key as an environment variable, replace $DASHSCOPE_API_KEY with your actual API key.

  https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization# ======= Important =======
  # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization
  # API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # === Delete this comment before execution ===
  
  curl -X POST <a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="35ebbc67890ds">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization</a> \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "speech-biasing",
      "input": {
          "action": "create_vocabulary",
          "target_model": "fun-asr",
          "prefix": "testpfx",
          "vocabulary": [
            {"text": "Seediq Bale", "weight": 4}
          ]
      }
  }'

Python SDK

• API description

  def list_vocabularies(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
      '''
      Query all created hotword lists.
      param: prefix A custom prefix. If specified, returns only the identifiers of hotword lists with this prefix.
      param: page_index The page index.
      param: page_size The page size.
      return: A list of hotword list identifiers.
      '''

• Code example

  import dashscope
  from dashscope.audio.asr import *
  import json
  import os
  
  # API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # If you have not configured an environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
  
  # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
  dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
  
  service = VocabularyService()
  vocabularies = service.list_vocabularies()
  print(f"Hotword list: {json.dumps(vocabularies)}")

• Response parameters

  Click to view an example response

  [
    {
      "gmt_create": "2025-04-22 14:23:35",
      "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
      "gmt_modified": "2025-04-22 14:23:35",
      "status": "OK"
    }
  ]

  The key parameters are as follows:

  Parameter	Type	Description
  vocabulary_id	string	The hotword list ID.
  gmt_create	string	The time when the hotword list was created.
  gmt_modified	string	The time when the hotword list was modified.
  status	string	The status: OK: Can be called. UNDEPLOYED: Cannot be called.

Java SDK

• API description

  /**
   * Query all created hotword lists. The default page index is 0, and the default page size is 10.
   *
   * @param prefix A custom prefix for the hotword.
   * @return An array of hotword list objects.
   * @throws NoApiKeyException if the API key is empty.
   * @throws InputRequiredException if a required parameter is empty.
   */
  public Vocabulary[] listVocabulary(String prefix)
      throws NoApiKeyException, InputRequiredException
  
  /**
   * Query all created hotword lists.
   *
   * @param prefix A custom prefix for the hotword.
   * @param pageIndex The page index.
   * @param pageSize The page size.
   * @return An array of hotword list objects.
   * @throws NoApiKeyException if the API key is empty.
   * @throws InputRequiredException if a required parameter is empty.
   */
  public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize)
      throws NoApiKeyException, InputRequiredException

• Code example

  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.Gson;
  import com.google.gson.GsonBuilder;
  
  public class Main {
      // API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
      // If you have not configured an environment variable, replace the following line with your Model Studio API key: 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 is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
          Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
  
          VocabularyService service = new VocabularyService(apiKey);
          Vocabulary[] vocabularies = service.listVocabulary("testpfx");
          Gson gson = new GsonBuilder()
                  .setPrettyPrinting()
                  .create();
          System.out.println("Hotword list: " + gson.toJson(vocabularies));
      }
  }

• Click to view the response example

  [
    {
      "gmt_create": "2025-04-22 14:23:35",
      "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
      "gmt_modified": "2025-04-22 14:23:35",
      "status": "OK"
    }
  ]

  The key parameters are as follows:

  Parameter	Type	Description
  vocabulary_id	string	The hotword list ID.
  gmt_create	string	The time when the hotword list was created.
  gmt_modified	string	The time when the hotword list was modified.
  status	string	The status: OK: Can be called. UNDEPLOYED: Cannot be called.

RESTful API

• URL

  China (Beijing):

  POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization

  Singapore (International):

  POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

• Request headers

  Parameter	Type	Required	Description
  Authorization	string	Supported	The authentication token. The format is Bearer <your_api_key>. Replace <your_api_key> with your actual API key.
  Content-Type	string	Supported	The media type of the data transferred in the request body. Set the value to application/json.

• Request body

  The following request body includes all request parameters. You can omit optional fields as needed.

  Important

  model: The custom hotword model. Set the value to speech-biasing.

  {
      "model": "speech-biasing",
      "input": {
          "action": "list_vocabulary",
          "prefix": "testpfx",
          "page_index": 0,
          "page_size": 10
      }
  }

• Request parameters

  Parameter	Type	Default	Required	Description
  model	string	-	Supported	The custom hotword model. Set the value to speech-biasing.
  action	string	-	Supported	The operation type. Set the value to list_vocabulary.
  prefix	string	-	Not supported	A custom prefix for the hotword list. It must contain fewer than 10 lowercase letters and digits.
  page_index	integer	0	Not supported	The page number. The count starts from 0.
  page_size	integer	10	Not supported	The number of entries per page.

• Response parameters

  Click to view an example response

  {
    "output": {
      "vocabulary_list": [
        {
          "gmt_create": "2025-12-19 11:47:11",
          "gmt_modified": "2025-12-19 11:47:11",
          "status": "OK",
          "vocabulary_id": "vocab-testpfx-xxxxxxxx"
        }
      ]
    },
    "usage": {
      "count": 1
    },
    "request_id": "10e8cde2-b711-4609-b19b-xxxxxx"
  }

  Note the following parameters:

  Parameter	Type	Description
  vocabulary_id	string	The hotword list ID.
  gmt_create	string	The time when the hotword list was created.
  gmt_modified	string	The time when the hotword list was modified.
  status	string	The status: OK: Can be called. UNDEPLOYED: Cannot be called.

• Code example

  The following is a cURL example. For Java and Python examples, see the corresponding SDKs.

  If you have not configured your API key as an environment variable, replace $DASHSCOPE_API_KEY with your actual API key.

  # ======= Important =======
  # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization
  # API keys for the Singapore and China (Beijing) regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # === Delete this comment before execution ===
  
  curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "speech-biasing",
      "input": {
          "action": "list_vocabulary",
          "prefix": "testpfx",
          "page_index": 0,
          "page_size": 10
      }
  }'