მეტყველების ტექსტად გარდაქმნის API

ეს API დასრულებული აუდიოფაილების ტრანსკრიფციას რიგში ჩაყენებული დავალებების სახით ასრულებს. გაგზავნეთ ფაილი, შეინახეთ დაბრუნებული დავალების ID და მოითხოვეთ დავალების მონაცემები, სანამ დამუშავება არ დასრულდება. ყველა მოთხოვნა გაგზავნეთ HTTPS-ით, თქვენი ანგარიშის ავთენტიფიკაციის მონაცემებით: მაგალითებში ნაჩვენები HTTP Basic მონაცემებით ან API ტოკენით, როგორც აღწერილია განყოფილებაში „ავთენტიფიკაცია“. ავთენტიფიკაციის მონაცემები შეინახეთ თქვენს სერვერზე.

საბოლოო წერტილები

ორი API ჰოსტი, https://api.multi.tel და თავსებადობის ჰოსტი https://api.multitel.net, იყენებს თქვენი ანგარიშით შემოფარგლულ ერთსა და იმავე დავალებებს, იდემპოტენტურობის გასაღებებს, ლიმიტებსა და ანგარიშსწორებას. ისინი განსხვავდება ატვირთვის კოდირებითა და პასუხის გარე სტრუქტურით, ამიტომ თანმიმდევრულად გამოიყენეთ ერთი ჰოსტი და მისი შესაბამისი პარსერი.

ჰოსტზე api.multi.tel ყველა გზა ასევე ხელმისაწვდომია პრეფიქსით /v1/speech-to-text პრეფიქსის ნაცვლად /v3/speech_to_text, მაგალითად POST /v1/speech-to-text/estimate. ჰოსტზე api.multitel.net გამოიყენეთ /v3/speech_to_text გზები.

სერვისის ინფორმაციის პასუხი მოიცავს შემდეგ მონაცემებს: mode (batch), realtime (false), paidEnabled (მიიღება თუ არა ამჟამად ახალი ფასიანი დავალებები), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) და maxUploadBytes (26214400), აგრეთვე მოკლე აღწერას ველში description. მისი წაკითხვა უფასოა და შესაძლებელია მაშინაც, როდესაც ფასიანი დავალებების გაგზავნა გამორთულია; პასუხი 503 transcription_unavailable ბრუნდება მხოლოდ მაშინ, როდესაც მთლიანად სერვისი მიუწვდომელია.

აუდიოფაილის მომზადება

გამოიყენეთ დასრულებული აუდიოფაილი, რომლის ზომაა არაუმეტეს 25 MiB (26,214,400 ბაიტი), ხოლო ხანგრძლივობა — არაუმეტეს 2 საათი (7,200 წამი). გაგზავნისას ფაილი უნდა ამოიცნობოდეს როგორც MP3, WAV, Ogg, FLAC, MOV ან Matroska მედია, რომელიც შეიცავს აუდიონაკადს; მის მეტამონაცემებში მითითებული ხანგრძლივობა უნდა იყოს ნულზე მეტი და არაუმეტეს 7,200 წამისა. ამოცნობილი ფაილი, რომელიც ამ შემოწმებებს ვერ გადის, უარყოფილია პასუხით 422 unsupported_audio. ფაილი, რომლის წაკითხვაც ვერც ერთ ამ ფორმატში ვერ ხერხდება, ამჟამად შესაძლოა ამის ნაცვლად სერვერის შეცდომით (500) იქნეს უარყოფილი; ასეთ ფაილს უცვლელად ხელახლა ნუ გაგზავნით. მხოლოდ ფაილის გაფართოება თავსებადობას არ ადასტურებს.

ამ შემოწმებების გავლა არ იძლევა აუდიოს დეკოდირების გარანტიას. აუდიო მუშავდება ერთი ან ორი არხის სახით. ორზე მეტი აუდიოარხის მქონე ფაილი, ფაილი, რომლის დეკოდირებული აუდიო 2 საათზე გრძელია, ან ნებისმიერი სხვა ფაილი, რომლის დეკოდირება დამუშავებისას ვერ ხერხდება, სრულდება სტატუსით failed და, როგორც წესი, შეცდომის კოდით decode_failed; ასეთ დავალებაზე საფასური არ ირიცხება. გაგზავნამდე მრავალარხიანი აუდიო გადააკეთეთ მონო ან სტერეო ფორმატში.

ენის არასავალდებულო მინიშნება არის საუბრის ენის ორ- ან სამასოიანი კოდი პატარა ასოებით, მაგალითად en. თუ მინიშნება არ გსურთ, ველი გამოტოვეთ; api.multi.tel ცარიელ სტრიქონს უარყოფს. მინიშნება დამუშავებას მიმართულებას აძლევს, მაგრამ მხარდაჭერილი ენების სიასთან არ მოწმდება, ამიტომ მიუთითეთ საუბრის ენის სწორი კოდი.

ტრანსკრიფციის დავალების გაგზავნა

გაგზავნეთ JSON სათაურით Content-Type: application/json მისამართზე POST https://api.multi.tel/v3/speech_to_text. მოთხოვნის სხეული შეიძლება იყოს არაუმეტეს 35 MiB, რაც მაქსიმალური ზომის ფაილს base64 კოდირების შემდეგაც იტევს; უფრო დიდი სხეული უარყოფილია პასუხით 413.

ნებისმიერი სხვა JSON თვისება, მათ შორის idempotency_key, უარყოფილია პასუხით 400 invalid_transcription_request. გასაღები გაგზავნეთ სათაურში.

იდემპოტენტურობის გასაღები

ყოველი გაგზავნისთვის საჭიროა Idempotency-Key სათაური, რომლის სიგრძეა 1-დან 190 სიმბოლომდე. გამოიყენეთ ASCII ასოები, ციფრები, -, _, . და :, საწყისი ან ბოლო გამოტოვებების გარეშე: თავსებადობის ჰოსტი აშორებს გარე თეთრ სივრცეს და გასაღების სიგრძეს ბაიტებში ზომავს, ამიტომ სხვა სიმბოლოები თითოეულ ჰოსტზე შესაძლოა განსხვავებულად დაითვალოს. გასაღების არარსებობა ან 191 ან მეტი სიმბოლოს მქონე გასაღები იწვევს უარყოფას პასუხით 400.

გასაღებები შემოიფარგლება თქვენი ანგარიშითა და მეტყველების ტექსტად გარდაქმნის სერვისით, ორივე ჰოსტსა და თქვენი ანგარიშის ყველა ავთენტიფიკაციის მონაცემზე. იგივე გასაღების ხელახლა გაგზავნა იმავე ფაილითა და ენით აბრუნებს არსებულ დავალებას პასუხით HTTP 200 და duplicate: true, მისი სტატუსის მიუხედავად და მაშინაც, თუ დავალების შექმნის შემდეგ დამუშავება განახლდა, დამატებითი საფასურის გარეშე. გასაღების ხელახლა გამოყენება სხვა ფაილით ან ენით აბრუნებს 409 idempotency_conflict. ახალი გასაღები ქმნის ახალ დავალებას, თუნდაც ფაილი იდენტური იყოს, და დამუშავების წარმატებით დასრულების შემთხვევაში საფასური ცალკე ირიცხება.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

ახალი დავალება აბრუნებს HTTP 202-ს ქვემოთ ნაჩვენები ველებით, ხოლო განმეორებითი მოთხოვნა აბრუნებს HTTP 200-ს დავალების სრული ობიექტით, რომელიც აღწერილია განყოფილებაში „ტრანსკრიპტის წაკითხვა“. დავალების ID, რომელიც UUID-ია, წაიკითხეთ ველიდან data.id. ახალი დავალების პასუხი ასე გამოიყურება (იდენტიფიკატორი და მნიშვნელობები მაგალითებია):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

როდესაც დავალება რიგშია ან მუშავდება, durationSeconds, billedSeconds და costUsd ფაილის მეტამონაცემებზე დაფუძნებული შეფასებებია. საბოლოო საფასური დეკოდირებულ ხანგრძლივობას ეფუძნება.

გაგზავნამ ასევე შეიძლება დააბრუნოს 402 insufficient_balance, როდესაც წინასწარ გადახდილი ბალანსი ამ დავალებასა და თქვენს სხვა დაუსრულებელ დავალებებს ერთად ვერ ფარავს; 429 transcription_queue_full, როდესაც თქვენს ანგარიშს ან სერვისს მეტისმეტად ბევრი დაუსრულებელი დავალება აქვს; 429 audio_validation_busy, როდესაც ფაილების ვალიდაციის სიმძლავრე სრულადაა დაკავებული; და 503 paid_transcription_not_enabled, როდესაც ფასიანი ტრანსკრიფცია გამორთულია. პასუხების 429 და 503 შემთხვევაში მოგვიანებით ხელახლა სცადეთ იმავე გასაღებით.

შეფასება დავალების შექმნის გარეშე

იგივე JSON სხეული გაგზავნეთ მისამართზე POST https://api.multi.tel/v3/speech_to_text/estimate. იდემპოტენტურობის გასაღები საჭირო არ არის. შეფასება ამოწმებს და ზომავს ფაილს, მაგრამ არ ახდენს მის ტრანსკრიფციას, არ ქმნის დავალებას, არ ჯავშნის თანხას, არ ამოწმებს თქვენს ბალანსს და არ ჩამოჭრის თანხას თქვენი ანგარიშიდან. ველში language ენის მინიშნება მიიღება, მაგრამ შეფასებაზე არ მოქმედებს.

წარმატებული შეფასება აბრუნებს HTTP 200-ს შემდეგი ველებით: estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd და costUsd ობიექტში data. იგი ფაილის მეტამონაცემებში მითითებულ ხანგრძლივობას იყენებს, ხოლო დასრულებული დავალების საფასური ეფუძნება დეკოდირებულ ხანგრძლივობას, რომელიც შეიძლება განსხვავდებოდეს. შეფასებისას ფაილი ისევე მოწმდება, როგორც დავალების გაგზავნისას. შეფასებები ხელმისაწვდომია მხოლოდ მაშინ, როდესაც ფასიანი ტრანსკრიფცია ჩართულია (სხვაგვარად ბრუნდება 503 paid_transcription_not_enabled). შეიძლება დაბრუნდეს 429 audio_validation_busy, როდესაც ფაილების ვალიდაციის სიმძლავრე სრულადაა დაკავებული; მცირე ხნის შემდეგ ხელახლა სცადეთ.

ტრანსკრიპტის წაკითხვა

პერიოდულად მოითხოვეთ GET /v3/speech_to_text/JOB_ID, როგორც აღწერილია დოკუმენტში „დავალებებთან მუშაობის სახელმძღვანელო“. დავალების ობიექტი შეიცავს შემდეგ ველებს:

ტრანსკრიპტები და მათი დროის ნიშნულები, ენისა და არხის აღნიშვნები ავტომატურად იქმნება და მათი სიზუსტე გარანტირებული არ არის. ხარისხის ნებისმიერი ნიშნული შედეგის გადამოწმების მიზეზად მიიჩნიეთ და მნიშვნელოვანი სახელები, რიცხვები და ვალდებულებები საწყის აუდიოს შეადარეთ. ხანგრძლივი სიჩუმე და ძალიან ჩუმი მონაკვეთები გამოტოვებულია და სეგმენტებს არ წარმოქმნის. შედეგები ცალკეულ მოსაუბრეებს არ ამოიცნობს. როდესაც შედეგში ველის channelCount მნიშვნელობაა 2, თითოეულ სეგმენტს აქვს ველი channel მნიშვნელობით A (პირველი, ანუ მარცხენა არხი) ან B (მეორე, ანუ მარჯვენა არხი). ამით მოსაუბრეების განცალკევება ხდება მხოლოდ მაშინ, როდესაც თითოეული მათგანი ცალკე არხზეა ჩაწერილი. ორარხიანი აუდიოს საფასური ერთხელ, მისი სრული ხანგრძლივობის მიხედვით ირიცხება და არა თითოეულ არხზე ცალ-ცალკე. მონო შედეგებს არხების აღნიშვნები არ აქვს.

api.multitel.net-ის გამოყენება

თავსებადობის საბოლოო წერტილი POST https://api.multitel.net/v3/speech_to_text იღებს multipart/form-data მოთხოვნას ფაილის ნაწილით სახელწოდებით audio და არასავალდებულო ველით language; არ გამოიყენება JSON ველი audioBase64. ველში language ცარიელი მნიშვნელობა მინიშნების არარსებობად ითვლება. გაგზავნეთ იგივე Idempotency-Key სათაური. თუ სათაური არ არის, ეს ჰოსტი ასევე იღებს ფორმის ველს idempotency_key. ველები სახელებით source, free, billing_source, realtime ან stream უარყოფილია პასუხით 400 unsupported_transcription_option; ფორმის სხვა ველები უგულებელყოფილია. ეს ჰოსტი ასევე აბრუნებს შემდეგ შეცდომებს:

• 400 idempotency_key_required გასაღების არარსებობის ან მეტისმეტად გრძელი გასაღების შემთხვევაში.
• 400 audio_upload_required ატვირთვის არარსებობის ან არასრულად მიღების შემთხვევაში.
• 400 invalid_language არასწორი ენის შემთხვევაში.
• 413 invalid_audio_size ცარიელი ან მეტისმეტად დიდი ფაილის შემთხვევაში.
• 400 invalid_job არასწორი ფორმატის დავალების ID-ის შემთხვევაში.

ამ ჰოსტზე მეტყველების ტექსტად გარდაქმნის სერვისის პასუხების გარე სტრუქტურაა {"status":{"code":HTTP_STATUS},"response":{...}}. გაითვალისწინეთ, რომ status ობიექტია და არა სტრიქონი. წარმატების შემთხვევაში response შეიცავს იმავე ობიექტს, რასაც data ძირითად ჰოსტზე, ამიტომ დავალების ID არის response.id. შეცდომის შემთხვევაში response.code შეიცავს შეცდომის კოდს; შეტყობინება და მოთხოვნის ID არ შედის. ავთენტიფიკაციის შეცდომებს (401) ჰოსტის საერთო შესვლის შემოწმება აბრუნებს და პასუხის სხეული შეიძლება განსხვავდებოდეს, ამიტომ პარსერით დამუშავებამდე შეამოწმეთ HTTP სტატუსი. ჰოსტებს შორის ნუ აურევთ ატვირთვის კოდირებას ან პასუხის პარსერს.

ამ ჰოსტზე შეფასებისთვის იგივე multipart ველები POST მეთოდით გაგზავნეთ მისამართზე /v3/speech_to_text/estimate. იდემპოტენტურობის გასაღები საჭირო არ არის, ხოლო შეფასება მოცემულია ობიექტში response.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'