API Documentation
Getting Started
Voicen provides a secure REST API for developers to convert audio/video files to text in different languages.
In this documentation all methods and objects that returned by this methods are explained in detail for developers to easily use.
Base URL
The base URL of API is:
https://api.voicen.com/speechtotext/v1
All commands listed below will be executed via this URL.
Errors are returned in JSON format.
Getting access token
To use Voicen API you need access token that you can find on the your account page.
You can also re-generate your token if you need.
In all API request access token is sent like below:
-H "Authorization: Bearer $VOICEN_ACCESS_TOKEN"
Python SDK
Install via pip
pip3 install --upgrade voicen
Check out the Python SDK docs and examples on : Github
Submit an audio/video file or media link
An example of submitting an audio/video file or media link to Voicen API:
Parameters
- Content-type
- header is used to indicate the media type of the resource.
- lang
- the language of the audio/video file or media link
- link
- the media link
- file
- path to an audio/video file
Status Codes
Code | Description |
---|---|
200 | Success |
400 | Bad request. Error messsge in a JSON format about errors. |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
{
"id": 1219,
"language": "en-EN",
"status": "preparing",
"created": "2019-10-21T 15:51:29"
}
{
"timestamp": 1572608534499,
"status": 400,
"error": "Bad Request",
"message": "Error message here",
"path": "/synthesize"
}
{
"status": 401,
"title": "Authorization failed for this request."
}
Get list of jobs
You can get all of your jobs list.
Parameters
- limit
- Limit number of jobs (integer, max is 1000).
- start_after
- Returns transcription jobs submitted before the job with this ID (string).
Status Codes
Code | Description |
---|---|
200 | Success |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
400 | Bad request |
[
{
"id": 1219,
"language": "en-EN",
"status": "preparing",
"created": "2019-10-21T 15:51:29",
"completed": "2019-10-21T 16:10:02",
},
...
]
{
"status": 401,
"title": "Authorization token is invalid or expired."
}
{
"title": "Bad request.",
"detail": "Invalid value of limit parameter. The max value for limit is 1000",
"status": 400
}
Get your transcriptions
You can get transcriptions of your sent audio/vieo file or media link.
Parameters
- type
-
can be one of the following
- json – transcription in a JSON format;
- txt - transcription in a raw text format;
- srt - transcription in a srt format for YouTube subtitles;
- doc - transcription in a doc format;
Status Codes
Code | Description |
---|---|
200 | Returned transcription corresponds to the sent format. |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
404 | Could not find job for requested ID. |
409 | Error message in JSON about format invalid sent format or process status not 'ready' |
Returned transcription corresponds to the sent format.
{
"status": 401,
"title": "Authorization token is invalid or expired."
}
{
"title": "No job found for this id.",
"status": 404
}
{
"allowedTypes": ["json","srt","txt","doc"],
"serviceResponse": {
"title": "Invalid transcription type.",
"detail": "Our service doesn't support this transcription type. See the allowed types in response message.",
"status": 409
}
}
{
"allowedStatuses": ["ready"],
"currentStatus": "failed",
"serviceResponse": {
"title": "Getting transcription not allowed.",
"detail": "The current status of job doesn't allow to get the transcription. Please see the allowed statuses in service response message.",
"status": 409
}
}
Get job by ID
Status can be one of the following:
["waiting", "preparing", "processing", "transcribing", "ready", "failed"]
Status Codes
Code | Description |
---|---|
200 | Success |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
404 | Could not find job for requested ID. |
{
"id": 1219,
"language": "en-EN",
"status": "ready",
"created": "2019-10-21T 15:51:29",
"completed": "2019-10-21T 16:10:02",
"duration": 2345
}
{
"id": 1219,
"language": "en-EN",
"status": "preparing",
"created": "2019-10-21T 15:51:29",
"completed": "2019-10-21T 16:10:02"
}
{
"status": 401,
"title": "Authorization failed for this request."
}
{
"status": 404,
"title": "No job found for this id."
}
Delete job by ID
Delete transcription job.
All completed job's (status with success or failure) data - audio/video files, media links and their transcriptions will be permanently deleted.
Status Codes
Code | Description |
---|---|
204 | Job was successfully deleted. |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
404 | Could not find job for requested ID. |
409 | Invalid status to be deleted. |
{
"id": 1219,
"language": "en-EN",
"status": "preparing",
"created": "2019-10-21T 15:51:29",
"completed": "2019-10-21T 16:10:02"
}
{
"timestamp": 1572608534499,
"status": 400,
"error": "Bad Request",
"message": "Error message here",
"path": "/jobs"
}
{
"status": 401,
"title": "Authorization failed for this request."
}
{
"status": 404,
"title": "No job found for this id."
}
{
"allowedStatuses" : [ "ready", "failed" ],
"currentStatus" : "processing",
"serviceResponse" : {
"title": "Job cannot be deleted.",
"detail": "Current status of job doesn't allow to delete it. See the allowed statuses in response message.",
"status": 409
}
}
Get information about account and balance
Status Codes
Code | Description |
---|---|
200 | Information about balance and account. |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
{
"email": "info@voicen.com",
"balanceInSeconds": 38941
}
{
"title": "Authorization token is invalid or expired.",
"status": 401
}
Get information payments
Status Codes
Code | Description |
---|---|
200 | Information about payments |
401 | Unauthorized request. The authorization token is old or invalid. Re-generate your token again on https://voicen.com/en/user/api/ |
[
{
"transactionId": "61789640737",
"amount": 6.0,
"type": "payment",
"purchasedMinutes": 10,
"created": "2019-10-21T 16:10:02",
},
...
]
{
"title": "Authorization token is invalid or expired.",
"status": 401
}