Alibaba Cloud Model Studio：Kustomisasi hotword

Python

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


# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum mengatur variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# URL WebSocket untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: 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 {
    // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // Jika Anda belum mengatur variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // URL WebSocket untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: 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();
            // Buat RecognitionParam
            RecognitionParam param =
                    RecognitionParam.builder()
                            .model(targetModel)
                            .apiKey(apiKey)
                            .format("wav")
                            .sampleRate(16000)
                            .build();

            try {
                System.out.println("Hasil pengenalan: " + recognizer.call(param, new File("asr_example.wav")));
            } catch (Exception e) {
                e.printStackTrace();
            } finally {
                // Tutup koneksi WebSocket setelah tugas selesai
                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;
    }
}

SDK Python

• Deskripsi API

  Penting

  target_model: Model pengenalan ucapan yang akan menggunakan daftar hotword ini. Harus sesuai dengan model yang digunakan dalam panggilan pengenalan ucapan selanjutnya.

  def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
      '''
      Buat daftar hotword.
      param: target_model Model pengenalan ucapan yang terkait dengan daftar hotword ini. Harus sesuai dengan model yang digunakan dalam panggilan pengenalan ucapan selanjutnya.
      param: prefix Awalan kustom untuk daftar hotword. Hanya angka dan huruf kecil yang diizinkan. Harus kurang dari 10 karakter.
      param: vocabulary Daftar hotword dalam format JSON.
      return: ID daftar hotword.
      '''

• Kode contoh

  import dashscope
  from dashscope.audio.asr import *
  import os
  
  # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
  # Jika Anda belum mengatur variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
  
  # URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: 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}
  ]
  
  # Buat daftar hotword
  service = VocabularyService()
  vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)
  
  print(f"ID daftar hotword: {vocabulary_id}")

SDK Java

• Deskripsi API

  Penting

  targetModel: Model pengenalan ucapan yang akan menggunakan daftar hotword ini. Harus sesuai dengan model yang digunakan dalam panggilan pengenalan ucapan selanjutnya.

  /**
   * Buat daftar hotword baru.
   *
   * @param targetModel Model pengenalan ucapan yang terkait dengan daftar hotword ini. Harus sesuai dengan model yang digunakan dalam panggilan pengenalan ucapan selanjutnya.
   * @param prefix Awalan kustom untuk daftar hotword. Hanya angka dan huruf kecil yang diizinkan. Harus kurang dari 10 karakter.
   * @param vocabulary Daftar hotword dalam format JSON.
   * @return Objek daftar hotword.
   * @throws NoApiKeyException Jika kunci API kosong.
   * @throws InputRequiredException Jika parameter yang diperlukan tidak ada.
   */
  public Vocabulary createVocabulary(String targetModel, String prefix, JsonArray vocabulary)
      throws NoApiKeyException, InputRequiredException 

• Kode contoh

  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 {
      // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
      // Jika Anda belum mengatur variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: public static String apiKey = "sk-xxx"
      public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
  
      public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
          // URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: 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("Confucius' Family", 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("ID daftar hotword: " + vocabulary.getVocabularyId());
      }
  }
  
  class Hotword {
      String text;
      int weight;
      String lang;
  
      public Hotword(String text, int weight) {
          this.text = text;
          this.weight = weight;
      }
  }

API RESTful

• URL

  Daratan Tiongkok (Beijing):

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

  Internasional (Singapura):

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

• Header permintaan

  Parameter	Type	Wajib	Deskripsi
  Authorization	string	Didukung	Token autentikasi dalam format Bearer <your_api_key>. Ganti "<your_api_key>" dengan kunci API Anda yang sebenarnya.
  Content-Type	string	Didukung	Jenis media data dalam badan permintaan. Tetap sebagai application/json.

• Isi permintaan

  Badan permintaan berisi semua parameter. Abaikan bidang opsional sesuai kebutuhan.

  Penting

  Perhatikan perbedaan antara parameter berikut:

  • model: Model kustomisasi hotword. Tetap sebagai speech-biasing.

  • target_model: Model pengenalan ucapan yang akan menggunakan daftar hotword ini. Harus sesuai dengan model yang digunakan dalam panggilan pengenalan ucapan selanjutnya.

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

• Parameter permintaan

  Parameter	Tipe	Bawaan	Wajib	Deskripsi
  model	string	-	Didukung	Model kustomisasi hotword. Tetap sebagai speech-biasing.
  action	string	-	Didukung	Jenis operasi. Tetap sebagai create_vocabulary.
  target_model	string	-	Didukung	Model pengenalan ucapan yang akan menggunakan daftar hotword ini. Untuk detailnya, lihat Model yang didukung. Harus sesuai dengan model yang digunakan dalam panggilan pengenalan ucapan selanjutnya.
  prefix	string	-	Didukung	Beri nama yang mudah dikenali untuk daftar hotword (hanya angka dan huruf kecil, kurang dari 10 karakter). Awal ini muncul dalam ID daftar hotword. Misalnya, dengan awalan "testpfx", ID akhirnya adalah "vocab-testpfx-51773d05xxxxxx".
  vocabulary	array[object]	-	Didukung	Daftar hotword dalam format JSON. Untuk detailnya, lihat Ikhtisar hotword.

• Parameter respons

  Klik untuk melihat contoh respons

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

  Parameter utama:

  Parameter	Tipe	Deskripsi
  vocabulary_id	string	ID daftar hotword.

• Kode contoh

  Contoh cURL (untuk Java dan Python, lihat contoh SDK masing-masing).

  Jika Anda belum mengonfigurasi kunci API sebagai variabel lingkungan, ganti $DASHSCOPE_API_KEY dengan kunci API Anda yang sebenarnya.

  https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization<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># ======= Catatan penting =======
  # URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization
  # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
  # === Hapus komentar ini sebelum menjalankan ===
  
  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}
          ]
      }
  }'

SDK Python

• Deskripsi API

  def list_vocabularies(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
      '''
      Daftar semua daftar hotword yang telah dibuat.
      param: prefix Awalan kustom. Jika diatur, hanya mengembalikan daftar hotword dengan awalan ini.
      param: page_index Indeks halaman yang akan diambil.
      param: page_size Jumlah item per halaman.
      return: Daftar pengenal daftar hotword.
      '''

• Kode contoh

  import dashscope
  from dashscope.audio.asr import *
  import json
  import os
  
  # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
  # Jika Anda belum mengatur variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
  
  # URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: 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"Daftar hotword: {json.dumps(vocabularies)}")

• Parameter respons

  Klik untuk melihat contoh respons

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

  Parameter utama:

  Parameter	Tipe	Deskripsi
  vocabulary_id	string	ID daftar hotword.
  gmt_create	string	Waktu saat daftar hotword dibuat.
  gmt_modified	string	Waktu saat daftar hotword terakhir dimodifikasi.
  status	string	Status: OK: Siap digunakan. UNDEPLOYED: Belum siap digunakan.

SDK Java

• Deskripsi API

  /**
   * Daftar semua daftar hotword yang telah dibuat. Indeks halaman bawaan adalah 0. Ukuran halaman bawaan adalah 10.
   *
   * @param prefix Awalan kustom untuk daftar hotword.
   * @return Array objek daftar hotword.
   * @throws NoApiKeyException Jika kunci API kosong.
   * @throws InputRequiredException Jika parameter yang diperlukan tidak ada.
   */
  public Vocabulary[] listVocabulary(String prefix)
      throws NoApiKeyException, InputRequiredException
  
  /**
   * Daftar semua daftar hotword yang telah dibuat.
   *
   * @param prefix Awalan kustom untuk daftar hotword.
   * @param pageIndex Indeks halaman yang akan diambil.
   * @param pageSize Jumlah item per halaman.
   * @return Array objek daftar hotword.
   * @throws NoApiKeyException Jika kunci API kosong.
   * @throws InputRequiredException Jika parameter yang diperlukan tidak ada.
   */
  public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize)
      throws NoApiKeyException, InputRequiredException

• Kode contoh

  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 {
      // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
      // Jika Anda belum mengatur variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: public static String apiKey = "sk-xxx"
      public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
  
      public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
          // URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: 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("Daftar hotword: " + gson.toJson(vocabularies));
      }
  }

• Klik untuk melihat contoh respons

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

  Parameter utama:

  Parameter	Tipe	Deskripsi
  vocabulary_id	string	ID daftar hotword.
  gmt_create	string	Waktu saat daftar hotword dibuat.
  gmt_modified	string	Waktu saat daftar hotword terakhir dimodifikasi.
  status	string	Status: OK: Siap digunakan. UNDEPLOYED: Belum siap digunakan.

API RESTful

• URL

  Daratan Tiongkok (Beijing):

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

  Internasional (Singapura):

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

• Header permintaan

  Parameter	Tipe	Wajib	Deskripsi
  Authorization	string	Didukung	Token autentikasi dalam format Bearer <your_api_key>. Ganti "<your_api_key>" dengan kunci API Anda yang sebenarnya.
  Content-Type	string	Didukung	Jenis media data dalam badan permintaan. Tetap sebagai application/json.

• Isi permintaan

  Badan permintaan berisi semua parameter. Abaikan bidang opsional sesuai kebutuhan.

  Penting

  model: Model kustomisasi hotword. Tetap sebagai speech-biasing.

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

• Parameter permintaan

  Parameter	Tipe	Bawaan	Wajib	Deskripsi
  model	string	-	Didukung	Model kustomisasi hotword. Tetap sebagai speech-biasing.
  action	string	-	Didukung	Jenis operasi. Tetap sebagai list_vocabulary.
  prefix	string	-	Tidak didukung	Awalan kustom untuk daftar hotword. Hanya angka dan huruf kecil yang diizinkan. Kurang dari 10 karakter.
  page_index	integer	0	Tidak	Indeks halaman, dimulai dari 0.
  page_size	integer	10	Tidak didukung	Jumlah item per halaman.

• Parameter respons

  Klik untuk melihat contoh respons

  {
    "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"
  }

  Parameter utama:

  Parameter	Tipe	Deskripsi
  vocabulary_id	string	ID daftar hotword.
  gmt_create	string	Waktu saat daftar hotword dibuat.
  gmt_modified	string	Waktu saat daftar hotword terakhir dimodifikasi.
  status	string	Status: OK: Siap digunakan. UNDEPLOYED: Belum siap digunakan.

• Kode contoh

  Contoh cURL (untuk Java dan Python, lihat contoh SDK masing-masing).

  Jika Anda belum mengonfigurasi kunci API sebagai variabel lingkungan, ganti $DASHSCOPE_API_KEY dengan kunci API Anda yang sebenarnya.

  # ======= Catatan penting =======
  # URL untuk wilayah Singapura. Untuk model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization
  # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
  # === Hapus komentar ini sebelum menjalankan ===
  
  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
      }
  }'