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
curl -X POST https://api.voicen.com/speechtotext/v1/jobs/file   -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN' -H 'Content-type: multipart/form-data' -F lang=en-EN -F file=@PATH_TO_MEDIA_FILE
					
curl -X POST https://api.voicen.com/speechtotext/v1/jobs/url -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN' -H 'Content-Type: application/x-www-form-urlencoded' -d 'lang=en-EN&link=$YOUTUBE_LINK'
					
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).
curl -X GET 'https://api.voicen.com/speechtotext/v1/jobs?start_after=1&limit=100' -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN'
					
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;
curl -X GET 'https://api.voicen.com/speechtotext/v1/jobs/$JOB_ID/transcript?type=json' -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN'
				
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

curl -X GET https://api.voicen.com/speechtotext/v1/jobs/1219  -H 'Authorization: Bearer  $VOICEN_ACCESS_TOKEN'
				

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.

curl -X DELETE https://api.voicen.com/speechtotext/v1/jobs/1219 -H 'Authorization: Bearer  $VOICEN_ACCESS_TOKEN'
				
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

curl -X GET 'https://api.voicen.com/speechtotext/v1/account' -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN'
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

curl -X GET 'https://api.voicen.com/speechtotext/v1/payments' -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN'
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
}