Create TTS Text

This request creates an audio recording out of a text message.

post	/tts/texts

Sample 1

A sample POST request to create a TTS text and save the returned resulting audio stream into a file:

curl -X POST \
'https://api.carrierx.com/core/v2/tts/texts' \
-H 'Content-Type: application/json' \
--data-binary '{"text":"This is my text for text-to-speech."}' \
-o my_audio.mp3 \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 1

200 status code and the created audio file.

Sample 2

A sample POST request to create a TTS text and save the returned resulting audio stream as a file into CarrierX storage service container:

curl -X POST \
'https://api.carrierx.com/core/v2/tts/texts?response_format=file&response_container_sid=a0323bcc-df67-4ad6-845f-9b11bdf4e778' \
-H 'Content-Type: application/json' \
--data-binary '{"text":"This is my text for text-to-speech."}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 2

200 status code with a serialized copy of the File object:

{
    "container_sid": "a0323bcc-df67-4ad6-845f-9b11bdf4e778",
    "content_classification": "media",
    "content_duration": 1.83,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_modified": "2021-06-21T13:17:32.517Z",
    "desired_bitrate": null,
    "desired_format": null,
    "file_access_name": "51e4a594e191c8c8e516858709470509c5dafa889bd004acd6157673476cdf11.mp3",
    "file_bytes": 3789,
    "file_sid": "f77251d7-0990-455c-a6ae-d83d61121599",
    "integer_key_1": null,
    "integer_key_2": null,
    "lifecycle_action": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "51e4a594e191c8c8e516858709470509c5dafa889bd004acd6157673476cdf11.mp3",
    "parent_file_sid": null,
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f77251d7-0990-455c-a6ae-d83d61121599",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "type": "audio",
    "unique": false
}

Required Scopes

To create a TTS Text object, the partner must have one of the following scopes enabled:

• tts.manage
• tts.create

Body Arguments

JSON representation of the fields and values of the TTS Text object to be created.

Required fields to create a TTS text are:

• text

Refer to this table to view all fields that appear in the TTS Text object.

Query Arguments

Parameter	Data Type	Description
response_container_sid	string	The secure ID of the container where the output audio file will be stored. If you set this option, the response_format is also required. If this option is omitted, the file will be returned as an audio stream.
response_format	string	The format of the output audio file. Values accepted in this field are: audio — use this value to return the resulting audio as an audio stream. You can save it using the means of the programming language of your choice (e.g., -o my_audio.mp3 for the cURL POST request). file — use this value together with the response_container_sid parameter to save the resulting audio file into CarrierX storage service container. The default value is audio.

Responses

If the request is successful, a 200 response code will be returned together with the created audio file (as a file or as an audio stream, depending on the response_format query attribute value).

Otherwise, if an error occurs, the system will return one of the HTTP errors used with CarrierX system.

TTS Text Object Specific Errors

{
    "message":"object validation error",
    "errors":[
        {
            "field":"language",
            "message":"not supported by voice",
            "reference_sid":null
        }
    ]
}

If you set a bitrate, format, language, or voice_sid not from the list of available values, or select an unsupported language for the chosen voice, the request will return a 422 (object validation error) error. It has the following structure:

Response Field	Data Type	Description
field	string	The field that caused the error.
message	string	The detailed error description.
reference_sid	string	This field is not used and is always set to null, as no object can be created during the request.

To avoid this error, you can:

• use one of the available values for the bitrate, format, language, or voice_sid attributes of the TTS Text object;
• query the TTS Voice objects to find out which languages are supported by the language you select and adjust your request accordingly.