Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

API HTTP de palavras-chave personalizadas

Gerencie vocabulários personalizados por meio de APIs HTTP, incluindo criação, listagem, obtenção, atualização e exclusão de vocabulários.

Guia do usuário: Melhorar a precisão do reconhecimento.

Pré-requisitos

Uma chave de API configurado como o DASHSCOPE_API_KEY variável de ambiente

Ponto final

POST https://maas.qwencloudapi.com/api/v1/services/audio/asr/customization

Solicitar cabeçalhos

Parâmetro	Tipo	Obrigatório	Descrição
Autorização	corda	Sim	Token do portador. Formato: `Bearer $DASHSCOPE_API_KEY`.
Tipo de conteúdo	corda	Sim	Tipo de mídia do corpo da solicitação. Definir como `application/json`.

Crie um vocabulário

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
modelo	corda	Sim	O modelo de vocabulário personalizado. Definir como `speech-biasing`.
entrada	objeto	Sim	Os parâmetros de entrada. Veja abaixo.

Parâmetro	Tipo	Obrigatório	Descrição
ação	corda	Sim	O tipo de operação. Definir como `create_vocabulary`.
alvo_modelo	corda	Sim	O modelo de reconhecimento de fala que usa esse vocabulário. Deve corresponder ao modelo especificado ao chamar a API de reconhecimento de fala.
prefixo	corda	Sim	Um prefixo personalizado para o vocabulário. Somente letras minúsculas e dígitos são permitidos, no máximo 10 caracteres.
vocabulário	matriz[objeto]	Sim	A matriz de entradas de vocabulário. Consulte Estrutura de entrada de hotword.

Corpo da resposta

Parâmetro	Tipo	Descrição
solicitação_id	corda	O identificador exclusivo desta solicitação.
saída	objeto	Os dados de resposta.
saída.vocabulário_id	corda	O ID do vocabulário criado.
uso	objeto	Informações de uso.
uso.contagem	inteiro	O número de vocabulários criados. Sempre 1.

Solicitação

curl -X POST https://maas.qwencloudapi.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}
    ]
  }
}'

Resposta

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

Listar vocabulários

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
modelo	corda	Sim	Definir como `speech-biasing`.
entrada	objeto	Sim	Os parâmetros de entrada. Veja abaixo.

Parâmetro	Tipo	Obrigatório	Descrição
ação	corda	Sim	O tipo de operação. Definir como `list_vocabulary`.
prefixo	corda	Não	Filtre por prefixo de vocabulário.
página_índice	inteiro	Não	Número da página, começando em 0. Padrão: 0.
página_tamanho	inteiro	Não	Número de entradas por página. Padrão: 10.

Corpo da resposta

Parâmetro	Tipo	Descrição
solicitação_id	corda	O identificador exclusivo desta solicitação.
saída	objeto	Os dados de resposta.
saída.vocabulário_list	matriz[objeto]	Os vocabulários consultados.
uso	objeto	Informações de uso.
uso.contagem	inteiro	Sempre 1.

Cada item em vocabulary_list contém:

Campo	Tipo	Descrição
vocabulário_id	corda	O ID do vocabulário.
gmt_criar	corda	O tempo de criação.
gmt_modificado	corda	A hora da última modificação.
estado	corda	`OK`: Preparar. `UNDEPLOYED`: Não disponível.

Solicitação

curl -X POST https://maas.qwencloudapi.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
  }
}'

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

Obtenha um vocabulário

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
modelo	corda	Sim	Definir como `speech-biasing`.
entrada	objeto	Sim	Os parâmetros de entrada. Veja abaixo.

Parâmetro	Tipo	Obrigatório	Descrição
ação	corda	Sim	O tipo de operação. Definir como `query_vocabulary`.
vocabulário_id	corda	Sim	O ID do vocabulário a ser obtido.

Corpo da resposta

Parâmetro	Tipo	Descrição
solicitação_id	corda	O identificador exclusivo desta solicitação.
saída	objeto	Os dados de resposta.
uso	objeto	Informações de uso.
uso.contagem	inteiro	Sempre 1.

O output objeto contém:

Campo	Tipo	Descrição
gmt_criar	corda	O tempo de criação.
gmt_modificado	corda	A hora da última modificação.
estado	corda	`OK`: Preparar. `UNDEPLOYED`: Não disponível.
alvo_modelo	corda	O modelo de reconhecimento de fala que usa esse vocabulário.
vocabulário	matriz[objeto]	As entradas do vocabulário. Consulte Estrutura de entrada de hotword.

Solicitação

curl -X POST https://maas.qwencloudapi.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"
  }
}'

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

Atualizar um vocabulário

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
modelo	corda	Sim	Definir como `speech-biasing`.
entrada	objeto	Sim	Os parâmetros de entrada. Veja abaixo.

Parâmetro	Tipo	Obrigatório	Descrição
ação	corda	Sim	O tipo de operação. Definir como `update_vocabulary`.
vocabulário_id	corda	Sim	O ID do vocabulário a ser atualizado.
vocabulário	matriz[objeto]	Sim	O novo vocabulário. Isso substitui completamente as entradas existentes. Consulte Estrutura de entrada de hotword.

Corpo da resposta

Parâmetro	Tipo	Descrição
solicitação_id	corda	O identificador exclusivo desta solicitação.
saída	objeto	Os dados de resposta. Sempre vazio.
uso	objeto	Informações de uso.
uso.contagem	inteiro	O número de vocabulários atualizados. Sempre 1.

Solicitação

curl -X POST https://maas.qwencloudapi.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"}
    ]
  }
}'

Resposta

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

Excluir um vocabulário

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
modelo	corda	Sim	Definir como `speech-biasing`.
entrada	objeto	Sim	Os parâmetros de entrada. Veja abaixo.

Parâmetro	Tipo	Obrigatório	Descrição
ação	corda	Sim	O tipo de operação. Definir como `delete_vocabulary`.
vocabulário_id	corda	Sim	O ID do vocabulário a ser excluído.

Corpo da resposta

Parâmetro	Tipo	Descrição
solicitação_id	corda	O identificador exclusivo desta solicitação.
saída	objeto	Os dados de resposta. Sempre vazio.
uso	objeto	Informações de uso.
uso.contagem	inteiro	O número de vocabulários excluídos. Sempre 1.

Solicitação

curl -X POST https://maas.qwencloudapi.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"
  }
}'

Resposta

{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

Estrutura de entrada de hotword

Cada entrada no vocabulary array possui os seguintes campos:

Campo	Tipo	Obrigatório	Descrição
texto	corda	Sim	O texto de entrada do vocabulário. O idioma do texto deve ser suportado pelo modelo selecionado. Use palavras reais em vez de combinações arbitrárias de caracteres. Comprimento máximo: 15 caracteres para texto que inclua caracteres não ASCII ou 7 palavras separadas por espaço para texto somente ASCII.
peso	inteiro	Sim	O 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 excessivamente alto pode reduzir a precisão do reconhecimento de outras palavras.
idioma	corda	Não	O código do idioma do áudio a ser reconhecido. Quando definido, o sistema melhora o reconhecimento de entradas de vocabulário no idioma especificado. Se não for possível determinar o idioma antecipadamente, deixe esse parâmetro indefinido. Os valores válidos variam de acordo com o modelo. Fun-ASR: `zh` (chinês), `en` (Inglês), `ja` (Japonês).