Skip to main content
Referência da API de palavras-chave personalizadas

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.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais
Referência da API HTTP de vocabulário personalizado - Alibaba Cloud Model Studio