Skip to main content

Referencia de la API HTTP de vocabulario personalizado

Gestione vocabularios personalizados mediante API HTTP, incluyendo la creación, listado, obtención, actualización y eliminación de vocabularios.

Guía del usuario: Mejorar la precisión del reconocimiento.
El vocabulario personalizado solo es compatible con el espacio de trabajo principal. Los subespacios de trabajo no lo admiten.

Endpoint

  • Singapore
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/customizationReemplace {WorkspaceId} con su ID de espacio de trabajo real.
Alibaba Cloud Model Studio ha lanzado dominios específicos del espacio de trabajo para las regiones China (Pekín) y Singapore. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
  • China (Pekín): de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapur: de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Reemplace {WorkspaceId} con su ID de espacio de trabajo real. Los dominios existentes permanecen totalmente funcionales.

Encabezados de solicitud

Parámetro

Tipo

Obligatorio

Descripción

Authorization

string

Sí

Token Bearer. Utilice el formato Bearer <api_key>, donde <api_key> es su clave de API.

Content-Type

string

Sí

Tipo de medio del cuerpo de la solicitud. Establézcalo en application/json.

Crear un vocabulario

Cuerpo de la solicitud

modelstring(Obligatorio)El modelo de vocabulario personalizado. Establezca este valor en speech-biasing.inputobject(Obligatorio)Los parámetros de entrada.

Propiedades

action string(Obligatorio)El tipo de operación. Establezca este valor en create_vocabulary.target_model string(Obligatorio)El modelo de reconocimiento de voz que utiliza este vocabulario. Este valor debe coincidir con el modelo que especifique al llamar a la API de reconocimiento de voz.prefix string(Obligatorio)Un prefijo personalizado para el vocabulario. Solo se permiten letras minúsculas y dígitos, con una longitud máxima de 10 caracteres.vocabulary array[object](Obligatorio)La matriz de entradas de vocabulario.

Propiedades

text string(Obligatorio)El texto de la entrada de vocabulario.El idioma del texto debe ser compatible con el modelo seleccionado. Los idiomas admitidos varían según el modelo.Utilice palabras reales en lugar de combinaciones arbitrarias de caracteres para mejorar la precisión del reconocimiento.Longitud máxima: 15 caracteres para texto que incluye caracteres no ASCII, o 7 palabras separadas por espacios para texto exclusivamente ASCII.weight integer(Obligatorio)El peso de la entrada de vocabulario. Valor recomendado: 4.Valores válidos: de 1 a 5.Si la precisión del reconocimiento no mejora, aumente el peso. Un peso excesivamente alto puede reducir la precisión del reconocimiento de otras palabras.lang string(Opcional)El código de idioma del audio que se va a reconocer. Cuando se establece, el sistema mejora el reconocimiento de las entradas de vocabulario en el idioma especificado. Si no puede determinar el idioma de antemano, deje este parámetro sin configurar. El modelo detecta el idioma automáticamente.Valores válidos (varían según el modelo):
  • Paraformer:
    • zh: Chino
    • en: Inglés
    • ja: Japonés
    • yue: Cantonés
    • ko: Coreano
    • de: Alemán
    • fr: Francés
    • ru: Ruso
  • Fun-ASR:
    • zh: Chino
    • en: Inglés
    • ja: Japonés
La siguiente URL corresponde a la región de Singapur. Reemplace WorkspaceId con su ID de espacio de trabajo real. Las URL varían según la región.Las claves de API para la región de Singapur y la región de Pekín son diferentes. Para obtener más información, consulte Obtener una clave 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}
        ]
    }
}'

Cuerpo de respuesta

request_idstringEl identificador único de esta solicitud.outputobjectLos datos de respuesta.

Propiedades

vocabulary_idstringEl ID del vocabulario creado.
usageobjectLa información de uso de esta solicitud.

Propiedades

count integerEl número de vocabularios creados. Siempre 1.
{
    "output": {
        "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

Listar vocabularios

Cuerpo de la solicitud

modelstring(Obligatorio)El modelo de vocabulario personalizado. Establezca este valor en speech-biasing.inputobject(Obligatorio)Los parámetros de entrada.

Propiedades

action string(Obligatorio)El tipo de operación. Establezca este valor en list_vocabulary.prefix string(Opcional)El prefijo personalizado del vocabulario. Cuando se especifica, solo se devuelven los vocabularios con este prefijo.page_index integerEl número de página, comenzando desde 0.Valor predeterminado: 0.page_size integerEl número de entradas por página.Valor predeterminado: 10.
La siguiente URL corresponde a la región de Singapur. Reemplace WorkspaceId con su ID de espacio de trabajo real. Las URL varían según la región.Las claves de API para la región de Singapur y la región de Pekín son diferentes. Para obtener más información, consulte Obtener una clave 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
    }
}'

Cuerpo de respuesta

request_idstringEl identificador único de esta solicitud.outputobjectLos datos de respuesta.

Propiedades

vocabulary_listarray[object]Los vocabularios consultados.

Propiedades

vocabulary_idstringEl ID del vocabulario.gmt_createstringLa hora de creación.gmt_modifiedstringLa hora de la última modificación.statusstringEl estado:
  • OK: Listo.
  • UNDEPLOYED: No disponible.
usageobjectLa información de uso de esta solicitud.

Propiedades

count integerSiempre 1.
{
    "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"
}

Obtener un vocabulario

Cuerpo de la solicitud

modelstring(Obligatorio)El modelo de vocabulario personalizado. Establezca este valor en speech-biasing.inputobject(Obligatorio)Los parámetros de entrada.

Propiedades

action string(Obligatorio)El tipo de operación. Establezca este valor en query_vocabulary.vocabulary_id string(Obligatorio)El ID del vocabulario que se desea obtener.
La siguiente URL corresponde a la región de Singapur. Reemplace WorkspaceId con su ID de espacio de trabajo real. Las URL varían según la región.Las claves de API para la región de Singapur y la región de Pekín son diferentes. Para obtener más información, consulte Obtener una clave 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"
    }
}'

Cuerpo de respuesta

request_idstringEl identificador único de esta solicitud.outputobjectLos datos de respuesta.

Propiedades

gmt_createstringLa hora de creación.gmt_modifiedstringLa hora de la última modificación.statusstringEl estado:
  • OK: Listo.
  • UNDEPLOYED: No disponible.
target_model stringEl modelo de reconocimiento de voz que utiliza este vocabulario. Este valor debe coincidir con el modelo que especifique al llamar a la API de reconocimiento de voz.vocabularyarray[object]El vocabulario consultado.

Propiedades

text stringEl texto de la entrada de vocabulario.weight integerEl peso de la entrada de vocabulario.lang stringEl idioma del audio que se va a reconocer.
usageobjectLa información de uso de esta solicitud.

Propiedades

count integerSiempre 1.
{
  "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"
}

Actualizar un vocabulario

Cuerpo de la solicitud

modelstring(Obligatorio)El modelo de vocabulario personalizado. Establezca este valor en speech-biasing.inputobject(Obligatorio)Los parámetros de entrada.

Propiedades

action string(Obligatorio)El tipo de operación. Establezca este valor en update_vocabulary.vocabulary_id string(Obligatorio)El ID del vocabulario que se desea actualizar.vocabulary array[object](Obligatorio)El nuevo vocabulario. Esto reemplaza por completo las entradas existentes.

Propiedades

text string(Obligatorio)El texto de la entrada de vocabulario.El idioma del texto debe ser compatible con el modelo seleccionado. Los idiomas admitidos varían según el modelo.Utilice palabras reales en lugar de combinaciones arbitrarias de caracteres para mejorar la precisión del reconocimiento.Longitud máxima: 15 caracteres para texto que incluye caracteres no ASCII, o 7 palabras separadas por espacios para texto exclusivamente ASCII.weight integer(Obligatorio)El peso de la entrada de vocabulario. Valor recomendado: 4.Valores válidos: de 1 a 5.Si la precisión del reconocimiento no mejora, aumente el peso. Un peso excesivamente alto puede reducir la precisión del reconocimiento de otras palabras.lang string(Opcional)El código de idioma del audio que se va a reconocer. Cuando se establece, el sistema mejora el reconocimiento de las entradas de vocabulario en el idioma especificado. Si no puede determinar el idioma de antemano, deje este parámetro sin configurar. El modelo detecta el idioma automáticamente.Valores válidos (varían según el modelo):
  • Paraformer:
    • zh: Chino
    • en: Inglés
    • ja: Japonés
    • yue: Cantonés
    • ko: Coreano
    • de: Alemán
    • fr: Francés
    • ru: Ruso
  • Fun-ASR:
    • zh: Chino
    • en: Inglés
    • ja: Japonés
La siguiente URL corresponde a la región de Singapur. Reemplace WorkspaceId con su ID de espacio de trabajo real. Las URL varían según la región.Las claves de API para la región de Singapur y la región de Pekín son diferentes. Para obtener más información, consulte Obtener una clave 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"}
        ]
    }
}'

Cuerpo de respuesta

request_idstringEl identificador único de esta solicitud.outputobjectLos datos de respuesta. Siempre vacío.usageobjectLa información de uso de esta solicitud.

Propiedades

count integerEl número de vocabularios actualizados. Siempre 1.
{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}

Eliminar un vocabulario

Cuerpo de la solicitud

modelstring(Obligatorio)El modelo de vocabulario personalizado. Establezca este valor en speech-biasing.inputobject(Obligatorio)Los parámetros de entrada.

Propiedades

action string(Obligatorio)El tipo de operación. Establezca este valor en delete_vocabulary.vocabulary_id string(Obligatorio)El ID del vocabulario que se desea eliminar.
La siguiente URL corresponde a la región de Singapur. Reemplace WorkspaceId con su ID de espacio de trabajo real. Las URL varían según la región.Las claves de API para la región de Singapur y la región de Pekín son diferentes. Para obtener más información, consulte Obtener una clave 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"
    }
}'

Cuerpo de respuesta

request_idstringEl identificador único de esta solicitud.outputobjectLos datos de respuesta. Siempre vacío.usageobjectLa información de uso de esta solicitud.

Propiedades

count integerEl número de vocabularios eliminados. Siempre 1.
{
  "output": {},
  "usage": {
    "count": 1
  },
  "request_id": "aee47022-2352-40fe-acfa-xxxx"
}