AI 助理
文档备案控制台
官方文档
首页

运行示例

更新时间：
复制 MD 格式
产品详情
我的收藏

本文基于使用主账号且从控制台获取测试Token的方式，为您介绍快速入门体验或轻量级开发测试，助您快速体验语音产品能力。

前提条件

已按照从这里开始完成准备阿里云主账号、开通服务、管理项目和通过控制台获取Token等操作。

体验方式

说明

新手推荐：首次体验建议从通过Curl命令调用一句话识别RESTful接口开始，只需一条命令即可完成首次语音识别调用。

警告

下表中“通过Curl命令调用异步长文本合成RESTful接口”和“通过postman调用异步长文本合成RESTful接口”两个示例仅支持商用版。如果您使用免费试用版调用，将返回错误码40000010（Gateway:FREE_TRIAL_EXPIRED）。如需体验长文本语音合成服务，请先在服务管理与开通页面将该服务升级为商用版。此外，如果您的免费试用期（3个月）已过期，调用其他示例（如一句话识别）也会返回同样的错误，同样需要升级为商用版。

使用方法

说明

通过Curl命令调用一句话识别RESTful接口

命令行操作，无需开发，可上传60s以内的音频。

通过Postman调用一句话识别RESTful接口

图形化界面操作，无需开发，可上传60s以内的音频。

通过SDK调用实时语音识别

使用Java开发语言调用SDK，可用于生产环境。

通过Python示例调用录音文件转写

Python脚本示例，可上传长语音文件（512 MB以内）。

通过SDK调用语音合成

使用Java开发语言调用SDK，可用于生产环境。

通过Curl命令调用异步长文本合成RESTful接口

命令行操作，无需开发，合成语音可下载。

说明

该服务仅支持商用版，需先开通后使用。

通过postman调用异步长文本合成RESTful接口

图形化界面操作，无需开发，合成语音可下载。

说明

该服务仅支持商用版，需先开通后使用。

若您想了解更多SDK方式体验，请参见SDK概览。

通过Curl命令调用一句话识别RESTful接口

  1. 请准备一份时长在60s以内、单通道、16K采样率的录音文件（格式：WAVE Audio, Microsoft PCM, 16 Bit, Mono 16000 Hz）。您可以使用我们为您准备的示例录音文件。

  2. 在命令行操作页面，执行以下命令。

    curl -X POST -H "X-NLS-Token: d9afc8a07b154e0b86d415226******" "http://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr?appkey=TuBrUhcloN******" --data-binary @./nls-sample-16k.wav
    说明

    • 示例中的d9afc8a07b154e0b86d415226******为您从智能语音交互控制台总览获取的Token；TuBrUhcloN******为您从智能语音交互控制台创建项目后，获取到的Appkey。

    • 若您在Windows命令行窗口执行上述命令，您可以对上述HTTP的URL部分无需加引号。

    • 若您想了解更多接口说明，请参见接口说明。

    命令执行完成以后，您可以获得如下识别结果。

    {"task_id":"12964b9b46d046ae8f377fd516df****","result":"北京的天气","status":20000000,"message":"SUCCESS"}%

通过Postman调用一句话识别RESTful接口

  1. 请先下载Postman。

  2. 请准备一份时长在60s以内、单通道、16K采样率的录音文件（格式：WAVE Audio, Microsoft PCM, 16 Bit, Mono 16000Hz）。您可以使用我们为您准备的示例录音文件。

  3. 在Postman里发送如下Post请求。

    参数

    示例

    请求URL

    http://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr

    Params

    appkey：TuBrUhcloN*****，请在智能语音交互控制台获取Appkey。

    Header

    X-NLS-Token：d9afc8a07b154e0b86d415226******，请在智能语音交互控制台总览单击点击获取临时AccessToken。

    Body

    Binary格式，上传语音文件，例如nls-sample-16k.wav。

    1. 请填写Post URL与Params。

      选择POST方法，URL 填写 http://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr。在Params中添加参数 appkey，值填写您的 Appkey。

    2. 请填写Headers。

      添加 Header X-NLS-Token，值为您的 Token；Content-Type 设置为 application/octet-stream。

    3. 请填写Body。

      选择 binary 类型，上传测试音频文件（如 test_8k_45s.wav）。

  4. Response返回后，其中result即语音识别结果。

    请求成功后返回 JSON 响应，其中 result 字段为识别结果（如"北京的天气"），status 为 20000000，message 为 SUCCESS。

    若您想查看一句话识别完整的接口文档，请参见接口说明。

通过SDK调用实时语音识别

  1. 下载nls-sdk-java-demo。

  2. 在IDE编辑器中，打开上一步中下载的示例代码，填写Appkey以及Token等参数。填写完成后，单击鼠标右键，选择Run "SpeechTranscriberDemo main()"。

    参数

    参数值

    Appkey

    请在智能语音交互控制台获取Appkey。

    Token

    请在智能语音交互控制台总览单击点击获取临时AccessToken。

    FilePath

    • 默认：nls-sample-16k.wav ，语音文件在SDK代码包路径下，以本地文件模拟实时流式发送数据。

    • 其他测试语音需满足实时识别语音格式要求，且放到SDK代码包路径下。

    		 
    // ① 请替换为您的Appkey和Token
String appKey = "YOUR_APPKEY";
String token = "YOUR_TOKEN";
String filePath = "nls-sample-16k.wav";

// ② 注释掉以下代码（JAR包命令行方式输入参数使用）
// if (args.length == 3) {
//     appKey = args[0];
//     token = args[1];
//     filePath = args[2];
// }

    • ①：获取Appkey和Token，请参见从这里开始。

    • ②：注释掉该段代码，该段代码用于JAR包命令行方式输入参数使用。

    实时识别返回结果如下，result即为识别结果。

    name: SentenceBegin, status: 0
name: TranscriptionResultChanged, result: 北京
name: TranscriptionResultChanged, result: 北京的
name: TranscriptionResultChanged, result: 北京的天气
name: SentenceEnd, result: 北京的天气。

    若您想了解更多语音识别接口文档，请参见接口说明。

通过Python示例调用录音文件转写

重要

录音文件转写通过Pop API调用，需要使用AccessKey ID和AccessKey Secret进行身份验证，而非Token。如果您尚未创建AccessKey，请参见步骤2：创建AccessKey。

调用接口前，需配置环境变量，通过环境变量读取访问凭证。智能语音交互的AccessKey ID、AccessKey Secret和AppKey的环境变量名：ALIYUN_AK_ID、ALIYUN_AK_SECRET、NLS_APP_KEY。

  1. 安装Python3以及Python SDK。

    1. 请先安装Python3。

    2. 执行如下命令，使用PIP安装（推荐）Aliyun-python-sdk-core，安装版本为2.13.3。

      pip install aliyun-python-sdk-core==2.13.3

  2. 复制示例代码，填写参数。

    1. 获取如下参数。

      参数

      参数值

      AccessKeyID

      两者配套使用，请在访问控制台查看。

      AccessKeySecret

      Appkey

      请在智能语音交互控制台获取Appkey。

      FileLink

      默认Demo测试录音。如需测试其他录音需上传录音文件至OSS，格式请参见接口说明；若OSS中文件访问权限未公开，请先获取访问链接，更多内容，请参见如何获取单个或多个文件的URL。

    2. 复制如下示例代码，修改上一步中的参数，保存到一个Python程序中，如《demo.py》。

      # -*- coding: utf8 -*-
import json
import os
import time
from aliyunsdkcore.acs_exception.exceptions import ClientException
from aliyunsdkcore.acs_exception.exceptions import ServerException
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest
def fileTrans(akId, akSecret, appKey, fileLink) :
    # 地域ID，固定值。
    REGION_ID = "cn-shanghai"
    PRODUCT = "nls-filetrans"
    DOMAIN = "filetrans.cn-shanghai.aliyuncs.com"
    API_VERSION = "2018-08-17"
    POST_REQUEST_ACTION = "SubmitTask"
    GET_REQUEST_ACTION = "GetTaskResult"
    # 请求参数
    KEY_APP_KEY = "appkey"
    KEY_FILE_LINK = "file_link"
    KEY_VERSION = "version"
    KEY_ENABLE_WORDS = "enable_words"
    # 是否开启智能分轨
    KEY_AUTO_SPLIT = "auto_split"
    # 响应参数
    KEY_TASK = "Task"
    KEY_TASK_ID = "TaskId"
    KEY_STATUS_TEXT = "StatusText"
    KEY_RESULT = "Result"
    # 状态值
    STATUS_SUCCESS = "SUCCESS"
    STATUS_RUNNING = "RUNNING"
    STATUS_QUEUEING = "QUEUEING"
    # 创建AcsClient实例
    client = AcsClient(akId, akSecret, REGION_ID)
    # 提交录音文件识别请求
    postRequest = CommonRequest()
    postRequest.set_domain(DOMAIN)
    postRequest.set_version(API_VERSION)
    postRequest.set_product(PRODUCT)
    postRequest.set_action_name(POST_REQUEST_ACTION)
    postRequest.set_method('POST')
    # 新接入请使用4.0版本，已接入（默认2.0）如需维持现状，请注释掉该参数设置。
    # 设置是否输出词信息，默认为false，开启时需要设置version为4.0。
    task = {KEY_APP_KEY : appKey, KEY_FILE_LINK : fileLink, KEY_VERSION : "4.0", KEY_ENABLE_WORDS : False}
    # 开启智能分轨，如果开启智能分轨，task中设置KEY_AUTO_SPLIT为True。
    # task = {KEY_APP_KEY : appKey, KEY_FILE_LINK : fileLink, KEY_VERSION : "4.0", KEY_ENABLE_WORDS : False, KEY_AUTO_SPLIT : True}
    task = json.dumps(task)
    print(task)
    postRequest.add_body_params(KEY_TASK, task)
    taskId = ""
    try :
        postResponse = client.do_action_with_exception(postRequest)
        postResponse = json.loads(postResponse)
        print (postResponse)
        statusText = postResponse[KEY_STATUS_TEXT]
        if statusText == STATUS_SUCCESS :
            print ("录音文件识别请求成功响应！")
            taskId = postResponse[KEY_TASK_ID]
        else :
            print ("录音文件识别请求失败！")
            return
    except ServerException as e:
        print (e)
    except ClientException as e:
        print (e)
    # 创建CommonRequest，设置任务ID。
    getRequest = CommonRequest()
    getRequest.set_domain(DOMAIN)
    getRequest.set_version(API_VERSION)
    getRequest.set_product(PRODUCT)
    getRequest.set_action_name(GET_REQUEST_ACTION)
    getRequest.set_method('GET')
    getRequest.add_query_param(KEY_TASK_ID, taskId)
    # 提交录音文件识别结果查询请求
    # 以轮询的方式进行识别结果的查询，直到服务端返回的状态描述符为"SUCCESS"、"SUCCESS_WITH_NO_VALID_FRAGMENT"，
    # 或者为错误描述，则结束轮询。
    statusText = ""
    while True :
        try :
            getResponse = client.do_action_with_exception(getRequest)
            getResponse = json.loads(getResponse)
            print (getResponse)
            statusText = getResponse[KEY_STATUS_TEXT]
            if statusText == STATUS_RUNNING or statusText == STATUS_QUEUEING :
                # 继续轮询
                time.sleep(10)
            else :
                # 退出轮询
                break
        except ServerException as e:
            print (e)
        except ClientException as e:
            print (e)
    if statusText == STATUS_SUCCESS :
        print ("录音文件识别成功！")
    else :
        print ("录音文件识别失败！")
    return
accessKeyId = os.getenv('ALIYUN_AK_ID')
accessKeySecret = os.getenv('ALIYUN_AK_SECRET')
appKey = os.getenv('NLS_APP_KEY')
fileLink = "https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav"
# 执行录音文件识别
fileTrans(accessKeyId, accessKeySecret, appKey, fileLink)

  3. 执行如下命令，运行示例代码。

    python3 demo.py

    执行成功后，会返回如下结果，并在最后一行显示录音文件识别成功。

    {'TaskId': 'xxx', 'StatusCode': 21050000, 'StatusText': 'SUCCESS', 'Result': {'Sentences': [{'Text': '北京的天气', 'BeginTime': 0, 'EndTime': 2365, 'ChannelId': 0}]}}
录音文件识别成功！

    若您想了解更多录音文件转写接口文档，请参见接口说明。

通过SDK调用语音合成

  1. 下载nls-sdk-java-demo。

  2. 在IDE编辑器中，打开上一步下载的示例代码，填写语音合成的参数。填写完成后，单击鼠标右键，选择Run "SpeechSynthesizerDemo main()"。

    参数

    参数值

    Appkey

    请在智能语音交互控制台获取Appkey。

    Token

    请在智能语音交互控制台总览单击点击获取临时AccessToken。

    		 

    // ① 请替换为您的Appkey和Token
String appKey = "YOUR_APPKEY";
String token = "YOUR_TOKEN";
String filePath = "nls-sample-16k.wav";

// ② 注释掉以下代码（JAR包命令行方式输入参数使用）
// if (args.length == 3) {
//     appKey = args[0];
//     token = args[1];
//     filePath = args[2];
// }

    // ③ 设置语音合成参数
synthesizer.setVoice("xiaoyun");
synthesizer.setSampleRate(16000);
synthesizer.setFormat(OutputFormatEnum.WAV);
synthesizer.setText("今天天气好晴朗");

    • ①：获取Appkey和Token，请参见从这里开始。

    • ②：注释掉该段代码，该段代码用于JAR包命令行方式输入参数使用。

    • ③：在该区域输入语音合成的参数。

    语音合成返回结果如下，音频文件将保存到本地。

    name: SynthesisStarted
[binary audio data received]
name: SynthesisCompleted
Output file: tts_test.wav

    若您想了解更多语音合成接口文档，请参见接口说明。

通过Curl命令调用异步长文本合成RESTful接口

重要

异步长文本语音合成无免费试用版，需要开通商用版后才可使用。使用免费试用版调用将返回错误码40000010（Gateway:FREE_TRIAL_EXPIRED）。请前往控制台将该服务升级为商用版。

  1. 在命令行执行如下命令，提交语音合成任务。

    curl -X POST 'https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async' \
-H 'Content-Type: application/json' \
--data-raw '{
    "payload":{
        "tts_request":{
            "voice":"xiaoyun",
            "sample_rate":16000,
            "format":"wav",
            "text":"今天天气好晴朗",
            "enable_subtitle": true
        },
        "enable_notify":false
    },
    "context":{
        "device_id":"my_device_id"
    },
    "header":{
        "appkey":"TuBrUhcloN******",  # 替换为您的Appkey。
        "token":"d9afc8a07b154e0b86d4152265******" # 替换为您的Token。
    }
}'

    命令执行完成后，会获得如下返回结果，其中task_id为任务唯一标识。

    //POST响应结果返回如下，含Task_id。

{"status":200,"data":{"task_id":"8b240239f3c646748c84acaf98c****"},"error_code":20000000,"error_message":"SUCCESS","request_id":"cc03ca1bccab438eb74740127391****"}

  2. 根据上一步中的task_id，发送GET请求，获取合成文件下载。

    GET请求地址：
https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey={Appkey}&task_id={task_id}&token={Token}

样例如下：
curl -X GET 'https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey=TuBrUhcloNpE****&task_id=8b240239f3c646748c84acaf98c******&token=d9afc8a07b154e0b86d4152265******'

  3. 命令执行成功后，会返回如下结果，其中audio_address为合成后语音的下载链接。

    //GET请求响应返回示例，其中Audio_address即为合成语音的试听和下载地址，复制到浏览器中打开即可。

{"status":200,"data":{"sentences":[{"text":"今天天气好晴朗","begin_time":"0","end_time":"1985"}],"task_id":"8b240239f3c646748c84acaf9*","audio_address":"http://nls-cloud-cn-shanghai.oss-cn-shanghai.aliyuncs.com/jupiter-flow/tmp/8b240239f3c646748c84ac******.wav?Expires=16630****&OSSAccessKeyId=LTAI****************&Signature=rTFF****************","notify_custom":""},"error_code":20000000,"error_message":"SUCCESS","request_id":"6dd08e26170f4be8bd5a510daa2*****"}

    若您需要了解更多的异步长文本语音合成相关信息，请参见接口文档。

通过postman调用异步长文本合成RESTful接口

重要

异步长文本语音合成无免费试用版，需要开通商用版后才可使用。使用免费试用版调用将返回错误码40000010（Gateway:FREE_TRIAL_EXPIRED）。请前往控制台将该服务升级为商用版。

  1. 请先下载Postman。

  2. 在Postman里发送如下Post请求。

    参数

    示例

    URL

    https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async

    Header

    Content-Type：application/json

    Body

    请参考如下代码。

    Body代码：

    {
    "payload":{
        "tts_request":{
            "voice":"xiaoyun",
            "sample_rate":16000,
            "format":"wav",
            "text":"今天天气好晴朗",
            "enable_subtitle": true
        },
        "enable_notify":false
    },
    "context":{
        "device_id":"my_device_id"
    },
    "header":{
        "appkey":"TuBrUhcloN******",  # 替换为您的Appkey
        "token":"d9afc8a07b154e0b86d4152265******" # 替换为您的Token
    }
}

    1. 请填写Post URL。

      选择POST方法，URL 填写 https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async。在Params中添加参数 appkey，值填写您的 Appkey。

    2. 请填写Headers。

      添加 Header X-NLS-Token，值为您的 Token；Content-Type 设置为 application/json。

    3. 请填写Body。

      选择 raw 格式，JSON 类型，填入上方 Body 代码中的 JSON 内容（替换 appkey 和 token 为您的实际值）。

    以上Post请求发送成功后，返回Response如下，含有task_id。其中 status 为 20000000，message 为 SUCCESS，error_code 为 0。

  3. 获取合成文件并下载。

    1. 根据上一步中的task_id发送Get请求。

      GET请求地址：
https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey={Appkey}&task_id={task_id}&token={Token}

样例如下：
https://nls-gateway-cn-shanghai.aliyuncs.com/rest/v1/tts/async?appkey=TuBrUhcloN******&task_id=8a63f10b2eaa4c75a47962eeee******&token=d9afc8a07b154e0b86d4152265******

    2. GET请求Response返回合成文件的audio_address地址，格式如下：JSON 响应包含 status（200）、data 对象（含 audio_address 下载链接、sentences 起止时间数组、task_id）和 error_code（20000000）。

    3. 将上一步骤中的audio_address复制到浏览器即可试听和下载，此文件最多保留7天。

      浏览器中会显示音频播放器页面，可直接播放收听合成效果。

      若您想了解更多异步长文本语音合成接口文档，请参见接口文档。

常见问题

调用服务时报错Gateway:FREE_TRIAL_EXPIRED（错误码40000010）怎么办？

此错误有两种常见原因：

原因一：免费试用期（3个月）已过期。试用期结束后，所有服务（包括一句话识别、实时语音识别、语音合成等）均会返回此错误，需升级为商用版后继续使用。

原因二：调用了商用版专属服务。以下服务不提供免费试用，即使在试用期内调用也会报此错误：

  • 长文本语音合成

  • 录音文件识别（闲时版）

  • 录音文件识别（极速版）

  • 流式文本语音合成（CosyVoice大模型）

  • 语音对话VoiceChat

解决方法：登录智能语音交互控制台的服务管理与开通页面，确认服务开通状态和账户余额，单击对应服务右侧的升级为商用版即可。更多错误码信息，请参见错误码查询。

哪些服务支持免费试用？

支持免费试用的服务包括：录音文件识别、实时语音识别、一句话识别、语音合成、说话人识别、声音事件检测、性别识别和语种识别。新用户可免费试用3个月，支持2路并发。试用期结束后，需升级为商用版才能继续使用。详情请参见计费项。

上一篇：通过OpenAPI获取Token下一篇：SDK和API概览