Polling, How to Use Typecast APIs

Polling is employed to make periodic requests to the Typecast server for retrieving updates. Generally, polling is straightforward to implement and is beneficial when frequent updates are not necessary.

To utilize the Typecast API through polling, initiate the process by sending a POST request to /api/speak. Subsequently, perform periodic GET /api/speak/{ :id } requests. Once the status transitions to ‘done’, proceed to download the resulting audio file from the audio_download_url.

Using cURL

Step 1. Send a request to synthesis voice.

Let’s first initiate the speech synthesis by making a POST /api/speak call to send a request for voice synthesis.

Example Request:

curl \
  --request POST \
  --url https://typecast.ai/api/speak \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "text": "My name is Typecast.",
    "lang": "auto",
    "actor_id": "${24-letters-your_actor_id}",
    "xapi_hd": true,
    "model_version": "latest"
  }'

In the example above, make sure to replace ${24-letters-your_actor_id} with your actual actor ID. You can obtain a list of available actor IDs by making a GET request to /api/actor. For more information about the API, see full API reference.

If you need more details about the parameters and options for the POST /api/speak API, please refer to the full API reference.

Example Response:

{
  "result": {
    "speak_v2_url": "https://typecast.ai/api/speak/v2/64a25802e671d3676a7a62ca"
  }
}

Step 2. Send a request repeatedly until status of speak is done

After initiating the speech synthesis in Step 1, the next step involves polling the /api/speak/v2/{ :id } URL to check the status of the ongoing synthesis.

Caution

• It is recommended to poll with a cycle of at least 1 second. Requesting more frequently may lead to system errors.

• Please note that polling does not deduct from the given quota.

Example Request:

curl \
  --request GET \
  --url https://typecast.ai/api/speak/v2/64a25802e671d3676a7a62ca \
  --header "Authorization: Bearer $API_TOKEN"

If you need more details about the parameters and options for the GET /api/speak/{ :id } API, please refer to the full API reference.

Initially, the response data will indicate the status as progress with a null audio_download_url:

Example Response when Status is progress:

{
  "result": {
    "status": "progress",
    "audio_download_url": null
  }
}

Once result.status turns to done, it signifies that the audio file is ready for download, and you can retrieve it from result.audio_download_url.

Example Response when Status is done:

{
  "result": {
    "status": "done",
    "audio_download_url": "https://cdn.typecast.ai/blah_the_audio_file_url_blah"
  }
}

Step 3. Download the audio file with result.audio_download_url

After successfully completing Step 2 and confirming that result.status is done, you can proceed to download the audio file using the provided result.audio_download_url.

Example Request:

curl \
  --request GET \
  --url https://cdn.typecast.ai/blah_the_audio_file_url_blah \
  --output <your_file_name>

This step finalizes the process, allowing you to obtain the synthesized audio file for further use.

Caution

• This GET request does not deduct from the given quota.

• result.audio_download_url will expire after 24 hours.

• If the URL expires, you need to make a new POST request to /api/speak to obtain a fresh audio file. Please be aware that this new POST request will deduct from the given quota.

Python Sample Code

For your convenience, here’s a sample Python code. This code demonstrates how to make requests for speech synthesis and then continuously poll for updates, with polling intervals of 1 minute, lasting for a total of 120 minutes.

If you have any additional inquiries concerning sample code, feel free to leave comments on the GitHub link provided above.