# **POST** /api/speak/prosody-meta/{ :id }

> An API for extracting start/stop timestamps of each word from a synthesized speech which is generated by [POST /api/speak](reference/post_api_speak.md#request) , as well as other data of it.

```{caution}
This API is not available to all customers. Please [contact our sales team](https://typecast.ai/contact) for eligibility details.
```

## Request

### Headers

* [Required headers](reference/request.md#headers)

### Parameters

#### Path parameters
* {:id}: ID of a speak that the word timestamps are extracted from. Refer to [response](reference/post_api_speak.md#response) of `POST /api/speak`.

### Body as JSON Object

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| **`language`** | string | Yes | The language of the give speak as the following format: (English: en-us , Korean: ko-kr). |
| **`version`** | enum(string) | No | The default value is `v1`. The value should be either `v2` or `v1`. `v1` returns results based on normalized text, while `v2` returns results based on the user's original input. |


<details open>
  <summary>Example with cURL</summary>

```bash
curl --request POST \
  --url https://typecast.ai/api/speak/prosody-meta/{your_speak_id} \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{"language": "ko-kr", "version": "v2"}'
```

</details>

## Response

### Status Code

| Status Code | Description |
|-------------|-------------|
| 401         | [Authorization Error](reference/error.md#error-codes)   |
| 403         | [Forbidden Error](reference/error.md#error-codes)   |
| 200         | JSON object containing the `result`.                    |

### `result` consists of the following
| Key | Description |
|-----|-------------|
| __`_id`__      | ID of the given speak. |
| __`prosody_meta`__ | Prosody Metadata. Refer to the below for the detail with an example. |
| __`actor_id`__ | ID of the requested actor. |
| __`uid`__      | ID of user. |
| __`query`__    | The body of the request to create the given speak. |
| __`status`__   | The result status of the given speak. |
| __`task_id`__  | The internal task ID. |
| __`speak_url`__ | Deprecated. |
| __`audio`__     | The metadata of the created speech audio file. |
| __`audio_path`__ | The path of the audio file. |
| __`quality`__    | Used internally. |
| __`sentence_task_ids`__ | Used internally. |
| __`callback`__   | Used internally. |
| __`download`__   | Used internally. |
| __`text_count`__ | length of the `text` that you requeste. |
| __`duration`__   | how much time the speak took (sec). |
| __`is_generated_by_api`__ | True for the api user. |
| __`seed`__ | Used internally. |


### `prosody_meta` consists of the following
| Key | Description |
|-----|-------------|
| __`phoneme_seq`__      | List of word in the text, which is used to synthesize the speak. |
| __`phoneme_location`__ | List of start/stop time location of the words in __`phoneme_seq`__. |
| __`phoneme_time`__ | List of start/stop time (second) of the words in __`phoneme_seq`__. |
| __`features`__ | The intonation data. |
| __`request_version`__ |  The version value used in the version parameter of the request. Returns null if the value is `v1` |

<details open>
  <summary>Prosody-Meta Example</summary>

```json
{
    "result": {
        ...
        "prosody_meta": {
            "phoneme_seq": [
                "thank",
                "you"
            ],
            "phoneme_time": [
                [
                    0.2230625,
                    0.48675
                ],
                [
                    0.567875,
                    0.709875
                ]
            ],
        }
    }
}
```

</details>

## Example usage to extract timestamp of each word
Here is a sample script to get the timestamp with the above Prosody-Meta Example response

<details open>
  <summary>Prosody-Meta Example</summary>

```json
response = requests.post(
    f"{prosody_meta_base_url}/{speak_id}",
    headers=my_authorized_header,
    json={"language": "ko-KR", "version": "v2"}
)
prosody_meta = response.json()['result']['prosody_meta']
prosody_seq = prosody_meta['phoneme_seq']
prosody_time = prosody_meta['phoneme_time']
for word, (start, end) in zip(prosody_seq, prosody_time):
    print(word, start, end)
# > thank 0.2230625 0.48675
# > you 0.567875 0.709875
```