Voclarity API (1.2.0)

Download OpenAPI specification:Download

Introduction

Welcome to Voclarity API documentation !

For now only the SmartAccelerator technology is available but more innovative speech processing tools will be available in the following months.

Instructions to implement the smart acceleration are below, and you can also use our web interface at this adress.

Authentication

X-Api-Key

This API uses an API Key based authentication. Please contact us to get your personal API Key.

Security Scheme Type API Key
Header parameter name: x-api-key

SmartAccelerator

URL Path : https://api.voclarity.tech/smartaccelerator/

What we call smart acceleration should be called “speech rate control”. Our SmartAccelerator technology normalizes speech rate of any media file to a given WPM (Words Per Minute) rate.

If you prefer you can set a compression rate instead, in this case the file average speaking rate will be multiplied by this factor to compute the target speaking rate. For example, if you set the compression rate to 2.0 for a file with an average speaking rate of 190 WPM, the target speaking rate will be fixed to twice this value: 380 WPM.

SmartAccelerator also allows 3 different options for pause management :

  • Compress: compresses pauses to save a considerable amount of time but also keeps some pauses to preserve speech naturalness,
  • Trim: completely trim pauses to save a maximum amount of time at the expense of speech naturalness,
  • Keep: keep pauses from the original file without any modification.


Lastly you can provide a callback URL to be notified once the processing is over. The notification is done through an HTTP POST request on the callback URL with the exact same body schema from a Get information Success response.

The API should be able to process all common audio/video formats, bit-rates or codecs. The returned processed file will have encoding settings as close as possible to the orignal ones. But if you encounter any issue related to media encoding please contact us so we can extend the API compability to your need.

Start processing

This is the main request used to start the processing of a file located at a given URL.

Request
Security:
X-Api-Key (aBcDeF123456gHiJkL789MnOpQRsT12345uVWxYZ)
Request Body schema: application/json
file-url
required
string

URL to the media file.
(ex: https://your.domain.com/path/to/media_file.ext)

language
required
string

Language spoken in the audio file.

Enum: "english" "french"
speaking-rate
null or number <integer> [ 100 .. 600 ]
Default: 300

Target speaking rate in WPM.

With a non-null compression-rate this value will be overwritten to match the chosen factor. In this case the speaking-rate value will be null and set to the corresponding target speaking rate during the processing.
Once the processing is done, the used speaking-rate value will then be available in the body of the Get information Success response, and in the body of the POST request sent to the callback url if one has been specified.
Note that the computed target speaking-rate will be capped to the parameter range (between 100 and 600 WPM).

compression-rate
null or number <float> [ 0.2 .. 6 ]
Default: null

Target speech compression rate (average speaking rate multiplier).

If non-null the existing value of the speaking-rate property is overwritten: see speaking-rate description to understand its usage.

pause-management
string
Default: "compress"

Pause management setting.

See SmartAccelerator description to see a detailed explanation of this setting.

Enum: "compress" "trim" "keep"
callback-url
null or string
Default: null

The callback URL that will be invoked by the API after the processing is over.
(ex: https://your.domain.com/path/to/some/endpoint)

response-content-disposition
null or string
Default: null

The response-type header field included in the result-url leading to the processed file.

Responses
200

Success

400

Bad Request

403

Forbidden Access

404

Media File Not Found

415

Media file Not Supported

post/smartaccelerator
Request samples
application/json
{}
Response samples
application/json
{}

Get information

You can ask for information regarding the ongoing process of a file. This is especially useful is you haven’t mentioned any callback URL, as the result URL will appear once the processing is done.

Request
Security:
X-Api-Key (aBcDeF123456gHiJkL789MnOpQRsT12345uVWxYZ)
path Parameters
fid
required
string <uuid4>

File ID

Responses
200

Success

400

Bad Request

403

Forbidden Access

404

File ID Not Found

get/smartaccelerator/{fid}
Request samples
curl -i -X GET \
  'http://api.voclarity.tech/smartaccelerator/{fid}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{}

Update processing

You can also update the parameters for an existing file in the 2-hour timeframe before the data are automatically deleted. Updating the parameters for a file is faster than starting a new request from scratch.

Request
Security:
X-Api-Key (aBcDeF123456gHiJkL789MnOpQRsT12345uVWxYZ)
path Parameters
fid
required
string <uuid4>

File ID

Request Body schema: application/json
language
string

Language spoken in the audio file.

Enum: "english" "french"
speaking-rate
null or number <integer> [ 100 .. 600 ]

Target speaking rate in WPM.

With a non-null compression-rate this value will be overwritten to match the chosen factor. In this case the speaking-rate value will be null and set to the corresponding target speaking rate during the processing.
Once the processing is done, the used speaking-rate value will then be available in the body of the Get information Success response, and in the body of the POST request sent to the callback url if one has been specified.
Note that the computed target speaking-rate will be capped to the parameter range (between 100 and 600 WPM).

compression-rate
null or number <float> [ 0.2 .. 6 ]

Target speech compression rate (average speaking rate multiplier).

If non-null the existing value of the speaking-rate property is overwritten: see speaking-rate description to understand its usage.

pause-management
string

Pause management setting.

See SmartAccelerator description to see a detailed explanation of this setting.

Enum: "compress" "trim" "keep"
callback-url
null or string

The callback URL that will be invoked by the API after the processing is over.
(ex: https://your.domain.com/path/to/some/endpoint)

response-content-disposition
null or string

The response-type header field included in the result-url leading to the processed file.

Responses
200

Success

400

Bad Request

403

Forbidden Access

404

File ID Not Found

409

Processing Ongoing

post/smartaccelerator/{fid}
Request samples
application/json
{
  • "language": "english",
  • "speaking-rate": null,
  • "compression-rate": 2,
  • "pause-management": "trim",
  • "callback-url": null,
  • "response-content-disposition": null
}
Response samples
application/json
{}

Clean data

Use Clean request in order in order to delete all data related to a previous request.
Please note than in any case, all data are erased after 2 hours of inactivity.

Request
Security:
X-Api-Key (aBcDeF123456gHiJkL789MnOpQRsT12345uVWxYZ)
path Parameters
fid
required
string <uuid4>

File ID

Responses
200

Success

400

Bad Request

403

Forbidden Access

404

File ID Not Found

409

Processing Ongoing

delete/smartaccelerator/{fid}
Request samples
curl -i -X DELETE \
  'http://api.voclarity.tech/smartaccelerator/{fid}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "deleted-fid": "123e4567-e89b-12d3-a456-426614174000"
}