MANUAL/VoiSona Manual (English)/Talk Manual (English)/Learn How to Use VoiSona Talk./REST API Tutorial

REST API Tutorial

日本語 / English

What Is the REST API of VoiSona Talk

A REST API (Representational State Transfer Application Programming Interface) is a mechanism that lets external programs use the functions of an application. Data is exchanged over HTTP, so speech synthesis requests, state checks, result retrieval, and so on can be automated.
By enabling the REST API of VoiSona Talk, you can control speech synthesis from various programming languages such as Python, C++, and JavaScript. This makes it possible to embed the synthesized speech of VoiSona Talk in your own applications, web services, chatbots, games, and more.
The following tutorial shows how to enable the REST API of VoiSona Talk and run speech synthesis with Python.

Enabling the REST API

  1. Launch VoiSona Talk.
  1. If you have not signed in, sign in.
    1. From the menu bar, select Help → Sign In
      1. Mail: your registered email address
      2. Password: the password you set at registration
  1. Make sure that at least one voice library has been downloaded.
  1. Enable the REST API.
    1. From the menu bar, select Edit → Preferences and open the API tab
      1. Set a listen port number of your choice. The default is 32766.
      2. Make sure that the user name is the email address you signed in with. This item cannot be changed.
      3. Set an API password of your choice. This password does not have to be your sign-in password. However, it must not be empty.
      4. Turn on the "Enable REST API" check box.
          • While it is on, the listen port number and the password cannot be changed. To change them, turn off the "Enable REST API" check box.
      5. The "Talk API Reference" link next to the "Enable REST API" check box becomes active. Refer to it for more details on how to use the API.

Example of Using the API with Python

Sample Code

The complete sample code is shown below. This tutorial explains each part in order.
The requests package is required to run the sample code.
The following is an example of running the sample code.
Change the user name and password to match the settings of the API server.

Getting the Available Voice Libraries

The list of voice libraries can be obtained as follows.
The following is an example of the output.
If no voice library has been downloaded in the editor, the list is empty.

Synthesizing Speech

The following sends a speech synthesis request to the server.
In the sample code, the first voice library found in the retrieved list is used for synthesis.
When synthesis is complete, "こんにちは" is played through the default audio device.
Note that the server keeps only a limited number of requests. Sending a new request once the limit is reached results in a 409 (Conflict) error. If you set to true in the request, old requests that are neither queued nor running are deleted automatically so that the new request can be accepted.
Using the UUID returned by the synthesize_text function, you can check the state of the submitted request as follows.
The in the response is one of (waiting), (in progress), (completed), or (processing failed). The sample code waits until the state becomes and raises an error if it becomes .
You can also delete a request by specifying its UUID.
Instead of playing the synthesized speech on the audio device, you can retrieve it as WAV data. If you set to in the request, the synthesized speech is kept on the server and can be retrieved from the endpoint after processing is complete.
The WAV data becomes available once the of the request is . Trying to retrieve it earlier results in a 409 (Conflict) error. Requests whose is not have no WAV data, so trying to retrieve it results in a 404 (Not Found) error.
You can also set to to save the speech as a WAV file on the server side. See the "Talk API Reference" for details.

Controlling Voice Expression

To change the expression of the voice, include in the request. The following example doubles the speed of the synthesized speech.

Detailed Control of Speech Information

You can control the speech in detail by including text with metadata in the speech synthesis request. To do so, first send a text analysis request and obtain the analysis result for the text.
The following is the result of analyzing "こんにちは".
By modifying this analysis result and passing it to the server, you can change the accent and pronunciation. The following is an example of modifying it with an XML parser.
For more details, open the "Talk API Reference" from the link in the API tab of Preferences in VoiSona Talk.