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.

					{
	"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."
}
				

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
}
				