API Dokumentasiya

Giriş

Voicen.com müştəriləri danışığın mətnə çevrilməsi servisindən istifadə edilməsi üçün RESTful API ilə təmin edir.

Burada bütün ümumi istifadə üçün nəzərdə tutulan metodlar və metodlar tərəfindən qaytarlan obyektlər, səhvlər proqramçılar tərəfindən asanlıqla istifadə edilməsi üçün ətraflı şəkildə izah edilmişdir.


Baza URL

Voicen.com-un API-dan istifadə üçün baza URL aşağıdakı kimidir:

https://api.voicen.com/speechtotext/v1

API metodları üçün URL-lər baza URL-ə uyğundur.

Error`lar json formatında qayıdacaq.

İcazə tokeninin əldə edilməsi

Voicen.com API-larını istifadəsi üçün ilk öncə icazə tokenini əldə etmək lazımdır.

İcazə tokeni bir dəfə generasiya edilir və həmişə istifadə edilir.

İcazə tokenini əldə etmək üçün Voicen API səhifəsinə gedin.

Bütün API sorğularda icazə tokenini Authorization: Bearer HTTP başlığında göndərməlisiniz.

-H "Authorization: Bearer $VOICEN_ACCESS_TOKEN"

Python SDK

pip ilə yüklə

pip3 install --upgrade voicen

Github səhifəsində Python SDK dokumentasiya və nümunələrə bax

Faylın və ya media linkin göndərilməsi

Audio, video faylın transkripsiya üçün göndərilməsi nümunəsi:

Parameters
Content-type
Header is used to indicate the media type of the resource.
lang
Səs faylının və ya linkin dili
link
Səs faylının linki
file
Səs faylının yolu
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=az-AZ -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=az-AZ&link=$YOUTUBE_LINK'
					
Status Codes
Code Description
200 Success
400 Bad request. Qayıdan jsonda "message"-da xəta ilə bağlı ətraflı məlumat qayıdır.
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
404 Sorğu etdiyiniz ID üçün proses tapılmadı
{
	"id": 1219,
	"language": "az-AZ",
	"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."
}
{
	"status": 404,
	"title": "No job found for this id."
}

Proseslərin siyahısını əldə etmək

Siz indiyə qədər yaratdığınız proseslərin siyahısını əldə edin.

Parameters
limit
siyahının maksimum uzunluğunu təyin edə bilərsiniz
start_after
verilən proses ID-dən sonrakı prosesləri əldə edə bilərsiniz
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 Proseslərin siyahısı müvəffəqiyyətlə qaytarıldı
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
400 Səhv sorğu
[
	{
		  "id": 1219,
		  "language": "az-AZ",
		  "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
}

Transkripsiyanızı əldə edin

Göndərdiyiniz media fayl və ya youtube linkin transkripsiyasını əldə edə bilərsiniz

Parameters
type
Aşağıdakılardan biri ola bilər
  • json – transkripsiya json formatında qaytarılır;
  • txt - transkripsiya adi mətn formatında qaytarılır;
  • srt - transkripsiya youtube alt yazı formatında qaytarılır;
  • doc - transkripsiya microsoft
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 Transkripsiya göstərilən tiplərdən birinə uyğun olaraq qaytarılmışdır.
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
404 Sorğu etdiyiniz ID üçün proses tapılmadı.
409 Əgər nəticənin tipi düzgün göndərilməyibsə və ya prosesin statusu 'ready' deyilsə sizə json formatında xəta qaytarılacaq.
Transkripsiya göstərilən tiplərdən birinə uyğun olaraq qaytarılmışdır.
{
	"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
    }
}

ID-yə görə proses haqqında məlumat əldə etmək

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

Status olaraq “waiting”, “preparing”, “processing”, “transcribing”, “ready”, “failed” cavablarından biri qayıdır.

Status Codes
Code Description
200 Success
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
404 Sorğu etdiyiniz ID üçün proses tapılmadı
{
	"id": 1219,
	"language": "az-AZ",
	"status": "ready",
	"created": "2019-10-21T 15:51:29",
	"completed": "2019-10-21T 16:10:02",
	"duration": 2345
}
{
	"id": 1219,
	"language": "az-AZ",
	"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."
}

Prosesin ID-yə görə silinməsi

Transkripsiya prosesini silinməsi.

Bu proseslə əlaqəli bütün verlənləri, transkripsiya və media faylı daxil olmaqla silir.

Prosesin statusu “ready” və ya “failed” olduqda silə bilərsiniz.

curl -X DELETE https://api.voicen.com/speechtotext/v1/jobs/1219 -H 'Authorization: Bearer  $VOICEN_ACCESS_TOKEN'
				
Status Codes
Code Description
204 Proses müvəffəqiyyətlə silindi.
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
404 Sorğu etdiyiniz ID üçün proses tapılmadı
409 Prosesin cari statusu onu silməyə imkan vermir
{
	"id": 1219, 
	"language": "az-AZ", 
	"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
	}
}

Hesab və balans haqqında məlumat

curl -X GET 'https://api.voicen.com/speechtotext/v1/account' -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN'
Status Codes
Code Description
200 Hesab və balans haqqında məlumat
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
{
	"email": "info@voicen.com", 
	"balanceInSeconds": 38941
}
{
	"title": "Authorization token is invalid or expired.", 
	"status": 401
}

Ödənişlər haqqında məlumat

curl -X GET 'https://api.voicen.com/speechtotext/v1/payments' -H 'Authorization: Bearer $VOICEN_ACCESS_TOKEN'
Status Codes
Code Description
200 Ödənişlər haqqında məlumat
401 İcazəsiz sorğu. İcazə tokeni köhnədir və ya icazə tokeni etibarsızdır. https://voicen.com/en/user/api/ səhifəsində yeni token generasiya etməlisiniz.
[
	{
	  "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
}