# **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:**

```bash
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](reference/get_api_actor.md#request).

If you need more details about the parameters and options for the ``POST /api/speak`` API, please refer to the [full API reference](reference/post_api_speak.md#request).

**Example Response:**

```json
{
  "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:** 

```bash
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](reference/get_api_v2_speak_oid.md#request).

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

**Example Response when Status is `progress`:**

```json
{
  "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`:**

```json
{
  "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:** 

```bash
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.

<script src="https://gist.github.com/zironycho/caf83bab180b310a9237a5f75130a8ba.js"></script>

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