Skip to main content

Referência da API HTTP de vocabulário personalizado

Gerencie vocabulários personalizados por meio de APIs HTTP. As operações incluem criar, listar, consultar, atualizar e excluir vocabulários.

Guia do usuário: Melhorar a precisão do reconhecimento.
O vocabulário personalizado é compatível apenas com o workspace principal. Sub-workspaces não oferecem suporte a esse recurso.

Endpoint

  • China (Beijing)
  • Singapore
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/customizationSubstitua {WorkspaceId} pelo seu ID do workspace real.
  • Singapore
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/customizationSubstitua {WorkspaceId} pelo seu ID do Workspace real.
O Alibaba Cloud Model Studio lançou domínios específicos para workspaces nas regiões China (Beijing) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Substitua {WorkspaceId} pelo seu ID do Workspace real. Os domínios existentes permanecem totalmente funcionais.

Cabeçalhos da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

Authorization

string

Sim

Token Bearer. Use o formato Bearer <api_key>, em que <api_key> é sua chave de API.

Content-Type

string

Sim

Tipo de mídia do corpo da solicitação. Defina como application/json.

Crie um vocabulário

Corpo da solicitação

A URL a seguir refere-se à região de Singapura. Substitua WorkspaceId pelo ID real do seu workspace. As URLs variam conforme a região.As chaves de API das regiões de Singapura e Beijing são diferentes. Para mais informações, consulte Obter uma chave de API.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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": "create_vocabulary",
        "target_model": "fun-asr",
        "prefix": "testpfx",
        "vocabulary": [
          {"text": "Seediq Bale", "weight": 4}
        ]
    }
}'
modelstring(Obrigatório)Modelo de vocabulário personalizado. Defina como speech-biasing.
inputobject(Obrigatório)Parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. Defina como create_vocabulary.target_model string(Obrigatório)Modelo de reconhecimento de fala que usa este vocabulário. Esse valor deve corresponder ao modelo especificado na chamada da API de reconhecimento de fala.prefix string(Obrigatório)Prefixo personalizado para o vocabulário. Permite apenas letras minúsculas e dígitos, com comprimento máximo de 10 caracteres.vocabulary array[object](Obrigatório)Array de entradas do vocabulário.

Propriedades

text string(Obrigatório)Texto da entrada do vocabulário.O idioma do texto deve ser compatível com o modelo selecionado. Os idiomas suportados variam conforme o modelo.Use palavras reais em vez de combinações arbitrárias de caracteres para melhorar a precisão do reconhecimento.Comprimento máximo: 15 caracteres para texto com caracteres não ASCII ou 7 palavras separadas por espaços para texto exclusivamente ASCII.weight integer(Obrigatório)Peso da entrada do vocabulário. Valor recomendado: 4.Valores válidos: 1 a 5.Se a precisão do reconhecimento não melhorar, aumente o peso. Um peso excessivo pode reduzir a precisão no reconhecimento de outras palavras.lang string(Opcional)Código do idioma do áudio a reconhecer. Quando definido, o sistema aprimora o reconhecimento das entradas de vocabulário no idioma especificado. Se não for possível determinar o idioma antecipadamente, deixe este parâmetro indefinido. O modelo detecta o idioma automaticamente.Valores válidos (variam conforme o modelo):
  • Paraformer:
    • zh: Chinês
    • en: Inglês
    • ja: Japonês
    • yue: Cantonês
    • ko: Coreano
    • de: Alemão
    • fr: Francês
    • ru: Russo
  • Fun-ASR:
    • zh: Chinês
    • en: Inglês
    • ja: Japonês

Corpo da resposta

{
    "output": {
        "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "aee47022-2352-40fe-acfa-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados da resposta.

Propriedades

vocabulary_idstringID do vocabulário criado.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerNúmero de vocabulários criados. Sempre 1.

Listar vocabulários

Corpo da solicitação

A URL a seguir refere-se à região de Singapura. Substitua WorkspaceId pelo ID real do seu workspace. As URLs variam conforme a região.As chaves de API das regiões de Singapura e Beijing são diferentes. Para mais informações, consulte Obter uma chave de API.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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
    }
}'
modelstring(Obrigatório)Modelo de vocabulário personalizado. Defina como speech-biasing.
inputobject(Obrigatório)Parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. Defina como list_vocabulary.prefix string(Opcional)Prefixo personalizado do vocabulário. Quando especificado, retorna apenas vocabulários com esse prefixo.page_index integerNúmero da página, começando em 0.Valor padrão: 0.page_size integerNúmero de entradas por página.Valor padrão: 10.

Corpo da resposta

{
    "output": {
        "vocabulary_list": [
            {
                "gmt_create": "2026-03-02 18:07:38",
                "gmt_modified": "2026-03-02 18:07:38",
                "status": "OK",
                "vocabulary_id": "vocab-ciotest-8e74bef2accf4xxxxxxxx"
            },
            {
                "gmt_create": "2026-02-27 19:04:48",
                "gmt_modified": "2026-02-28 13:40:40",
                "status": "OK",
                "vocabulary_id": "vocab-sifasr-f483ad46e1844fxxxxxxxx"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "81d51a05-8cdd-45c0-973f-xxxxxxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados da resposta.

Propriedades

vocabulary_listarray[object]Vocabulários consultados.

Propriedades

vocabulary_idstringID do vocabulário.gmt_createstringData e hora de criação.gmt_modifiedstringData e hora da última modificação.statusstringStatus:
  • OK: Pronto.
  • UNDEPLOYED: Não disponível.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1.

Consultar um vocabulário

Corpo da solicitação

A URL a seguir refere-se à região de Singapura. Substitua WorkspaceId pelo ID real do seu workspace. As URLs variam conforme a região.As chaves de API das regiões de Singapura e Beijing são diferentes. Para mais informações, consulte Obter uma chave de API.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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": "query_vocabulary",
        "vocabulary_id": "vocab-testpfx-xxxx"
    }
}'
modelstring(Obrigatório)Modelo de vocabulário personalizado. Defina como speech-biasing.
inputobject(Obrigatório)Parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. Defina como query_vocabulary.vocabulary_id string(Obrigatório)ID do vocabulário a consultar.

Corpo da resposta

{
  "output": {
    "gmt_create": "2025-12-19 11:47:11",
    "gmt_modified": "2025-12-19 11:47:11",
    "status": "OK",
    "target_model": "fun-asr",
    "vocabulary": [
      {
        "lang": "en",
        "text": "Seediq Bale",
        "weight": 4
      }
    ]
  },
  "usage": {
    "count": 1
  },
  "request_id": "3d461d3f-b2c4-4de5-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados da resposta.

Propriedades

gmt_createstringData e hora de criação.gmt_modifiedstringData e hora da última modificação.statusstringStatus:
  • OK: Pronto.
  • UNDEPLOYED: Não disponível.
target_model stringModelo de reconhecimento de fala que usa este vocabulário. Esse valor deve corresponder ao modelo especificado na chamada da API de reconhecimento de fala.vocabularyarray[object]Vocabulário consultado.

Propriedades

text stringTexto da entrada do vocabulário.weight integerPeso da entrada do vocabulário.lang stringIdioma do áudio a reconhecer.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1.

Atualize um vocabulário

Corpo da solicitação

A URL a seguir refere-se à região de Singapura. Substitua WorkspaceId pelo ID real do seu workspace. As URLs variam conforme a região.As chaves de API das regiões de Singapura e Beijing são diferentes. Para mais informações, consulte Obter uma chave de API.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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": "update_vocabulary",
        "vocabulary_id": "vocab-testpfx-xxx",
        "vocabulary": [
          {"text": "Seediq Bale", "weight": 4, "lang": "en"}
        ]
    }
}'
modelstring(Obrigatório)Modelo de vocabulário personalizado. Defina como speech-biasing.
inputobject(Obrigatório)Parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. Defina como update_vocabulary.vocabulary_id string(Obrigatório)ID do vocabulário a atualizar.vocabulary array[object](Obrigatório)Novo vocabulário. Substitui completamente as entradas existentes.

Propriedades

text string(Obrigatório)Texto da entrada do vocabulário.O idioma do texto deve ser compatível com o modelo selecionado. Os idiomas suportados variam conforme o modelo.Use palavras reais em vez de combinações arbitrárias de caracteres para melhorar a precisão do reconhecimento.Comprimento máximo: 15 caracteres para texto com caracteres não ASCII ou 7 palavras separadas por espaços para texto exclusivamente ASCII.weight integer(Obrigatório)Peso da entrada do vocabulário. Valor recomendado: 4.Valores válidos: 1 a 5.Se a precisão do reconhecimento não melhorar, aumente o peso. Um peso excessivo pode reduzir a precisão no reconhecimento de outras palavras.lang string(Opcional)Código do idioma do áudio a reconhecer. Quando definido, o sistema aprimora o reconhecimento das entradas de vocabulário no idioma especificado. Se não for possível determinar o idioma antecipadamente, deixe este parâmetro indefinido. O modelo detecta o idioma automaticamente.Valores válidos (variam conforme o modelo):
  • Paraformer:
    • zh: Chinês
    • en: Inglês
    • ja: Japonês
    • yue: Cantonês
    • ko: Coreano
    • de: Alemão
    • fr: Francês
    • ru: Russo
  • Fun-ASR:
    • zh: Chinês
    • en: Inglês
    • ja: Japonês

Corpo da resposta

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados da resposta. Sempre vazio.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerNúmero de vocabulários atualizados. Sempre 1.

Exclua um vocabulário

Corpo da solicitação

A URL a seguir refere-se à região de Singapura. Substitua WorkspaceId pelo ID real do seu workspace. As URLs variam conforme a região.As chaves de API das regiões de Singapura e Beijing são diferentes. Para mais informações, consulte Obter uma chave de API.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.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": "delete_vocabulary",
        "vocabulary_id": "vocab-testpfx-xxx"
    }
}'
modelstring(Obrigatório)Modelo de vocabulário personalizado. Defina como speech-biasing.
inputobject(Obrigatório)Parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. Defina como delete_vocabulary.vocabulary_id string(Obrigatório)ID do vocabulário a excluir.

Corpo da resposta

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados da resposta. Sempre vazio.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerNúmero de vocabulários excluídos. Sempre 1.