Webhook, How to Use Typecast APIs

Webhook is employed to receive a message from the Typecast server when speech synthesis completed. It is particularly useful when you need to promptly receive the updated result.
To use the Typecast API with a webhook, you should first make a PUT request to register your webhook URL. Subsequently, send a POST request to /api/speak. Upon the completion of speech synthesis, you will receive the message via the webhook URL. The resulting audio file can be downloaded from the audio_download_url.

Step 1. Register webhook URL on your account.

Before diving into speech synthesis, you need to register your webhook URL. This step allows the server to notify you as soon as the synthesis process is finished.

Example Request:

curl \
  --request PUT \
  --url https://typecast.ai/api/me/callback-url \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "callback_url": "https://your.host.com/here-is-the-webhook"
  }'

This API call sets up the communication channel between Typecast and your server.

If you need more details about the parameters and options for the PUT /api/me/callback-url API, please refer to the full API reference.

Step 2. Send a request to synthesis voice.

Now that we’ve registered the webhook URL, let’s proceed to send a speech synthesis request. We’ll make a POST /api/speak call.

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.

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_url": "https://typecast.ai/api/speak/5d47ff94e6c00800075726d3"
  }
}

This API call initiates the speech synthesis process, and in the response, you’ll receive a speak_url. It’s crucial to store this URL for later matching unique requested data with the webhook message.

Step 3. Receive the result message thorugh webhook url

As soon as the synthesis is completed, Typecast will send a message to your registered webhook URL. This message contains essential information about the synthesized audio file.

Example Webhook Message:

{
  "speak_url": "https://typecast.ai/api/speak/5d47ff94e6c00800075726d3",
  "audio_url_no_redirect": "https://typecast.ai/files/speak/ZGF0YS9...jkwNC53YXY=/no-redirect",
  "status": "done",
  "kind": "/api/speak",
  "audio_download_url": "https://cdn.typecast.ai/blah_the_audio_file_url_blah"
}

• speak_url: The same URL obtained from result.speak_url of Step 1.

• audio_url_no_redirect: This secure audio file URL is available for immediate playback.

• audio_download_url: The audio file that you’ve synthesized.

• status: Please refer to the table below.

  status value	Description
  done	Downloadable audio file is ready.
  failed	Your request has failed.

Caution

• 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.

Webhook Retry Behavior

If a webhook transmission fails due to a timeout, a 429 Too Many Requests error, or any 5xx status code, the Typecast server will retry sending the webhook.

Retries will be attempted up to 18 times. The first 5 attempts will be made without any interval between retries. After these initial attempts, the retry interval will increase exponentially (1 → 2 → 4 → 8 … up to 4,096 minutes).