მეტყველების დამუშავებისა და თარგმნის დავალებები

ქვემოთ მოცემულ მაგალითებში SERVICE შეცვალეთ მნიშვნელობით speech_to_text ან translate, ხოლო JOB_ID — დაბრუნებული UUID-ით. ყველა ოპერაცია მოითხოვს თქვენი ანგარიშის ავთენტიფიკაციის მონაცემებს, როგორც აღწერილია განყოფილებაში ავთენტიფიკაცია, და შემოიფარგლება დავალების მფლობელი ანგარიშით. დავალების წაკითხვა შესაძლებელია ორივე API ჰოსტიდან, თუმცა თითოეული პასუხის საკუთარ გარე სტრუქტურას იყენებს, ამიტომ თანმიმდევრულად გამოიყენეთ ერთი და იგივე ჰოსტი.

ჰოსტზე api.multitel.net ავთენტიფიკაციის შეცდომები (401) ბრუნდება ამ გარე სტრუქტურის გამოყენებამდე და შეიძლება ჰქონდეს განსხვავებული შიგთავსი, ამიტომ პასუხის გარჩევამდე შეამოწმეთ HTTP სტატუსი.

ავთენტიფიკაცია

ყოველი მოთხოვნა უნდა შეიცავდეს თქვენი ანგარიშის ავთენტიფიკაციის მონაცემებს. დავალებები, იდემპოტენტურობის გასაღებები, შეზღუდვები, გამოყენება და საფასურები ეკუთვნის ანგარიშს, რომელიც ფლობს ამ მონაცემებს. ისინი საერთოა ამ ანგარიშის ყველა ავთენტიფიკაციის მონაცემისთვის ორივე ჰოსტზე, იმის მიუხედავად, რომელი მონაცემებით იგზავნება მოთხოვნა.

• HTTP Basic (Authorization: Basic ან curl --user). მიიღება პაროლის ტიპის API ანგარიშის, ქვეანგარიშის ან თქვენი ანგარიშის შესვლის მონაცემები. გირჩევთ ცალკე API ანგარიშის გამოყენებას. მომხმარებლის სახელი არ უნდა შეიცავდეს ორწერტილს და არც მომხმარებლის სახელი და არც პაროლი არ უნდა იყოს ცარიელი.
• Bearer ტოკენი (Authorization: Bearer YOUR_TOKEN). მიიღება ტოკენის ტიპის API ანგარიშისთვის. ტოკენიან API ანგარიშებს აუცილებლად უნდა ჰქონდეს IP შეზღუდვა და მოთხოვნები დაშვებული მისამართიდან უნდა მოდიოდეს. ორივე API ჰოსტი იღებს ანგარიშისთვის განსაზღვრულ IPv4 მისამართებსა და CIDR დიაპაზონებს. ტოკენის Basic პაროლად გაგზავნა შეუძლებელია. დარწმუნდით, რომ თქვენი ტოკენი მუშაობს იმ ჰოსტზე, რომელსაც იყენებთ.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

თუ API ანგარიში შეზღუდულია IP მისამართით, მოთხოვნები გაგზავნეთ დაშვებული მისამართიდან. ავთენტიფიკაციის მონაცემების არქონის ან არასწორი მონაცემების შემთხვევაში ბრუნდება 401. ჰოსტზე api.multitel.net მოქმედი მონაცემები, რომლებითაც ამ სერვისების გამოყენება შეუძლებელია, მაგალითად ტოკენიანი ანგარიშის Basic ფორმით გაგზავნილი მონაცემები, აბრუნებს 403-ს და კოდს unsupported_transcription_principal ან unsupported_translation_principal. ერთი მისამართიდან ავთენტიფიკაციის განმეორებითმა წარუმატებელმა მცდელობებმა ჰოსტზე api.multitel.net შეიძლება გამოიწვიოს ამ მისამართის დაბლოკვა, ამიტომ ხელახლა ცდამდე შეასწორეთ ავთენტიფიკაციის მონაცემები.

პერიოდულად შეამოწმეთ დასრულება

გაგზავნეთ მოთხოვნა GET /v3/SERVICE/JOB_ID. გირჩევთ სტატუსი შეამოწმოთ არაუმეტეს ერთხელ ყოველ 3 წამში. პასუხის გარე სტრუქტურა აღწერს მოთხოვნას; დამუშავების დასრულების დასადგენად შეამოწმეთ მასში მოთავსებული დავალების ველი status.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

ჰოსტზე api.multitel.net დააყენეთ HOST მნიშვნელობაზე https://api.multitel.net და წაიკითხეთ .response.id ნაცვლად ველისა .data.id.

უსაფრთხოდ გაიმეორეთ გაურკვეველი შედეგის მქონე მოთხოვნები

თუ გაგზავნის მოლოდინის დრო ამოიწურა ან დაბრუნდა 429 ან 5xx სტატუსი, ხელახლა გაგზავნეთ იგივე შემავალი მონაცემები იმავე იდემპოტენტურობის გასაღებით. ნებისმიერი ჰოსტის პასუხი შეიძლება დაიკარგოს ან შეცდომით ჩანაცვლდეს დავალების მიღების შემდეგ; იგივე გასაღებით ხელახლა გაგზავნა აბრუნებს დავალებას, თუ ის არსებობს. გასაღების სხვა შემავალი მონაცემებით ხელახლა გამოყენება აბრუნებს 409-ს და კოდს idempotency_conflict. ზოგი შეცდომა ყოველ მცდელობაზე მეორდება, მაგალითად 503, როცა ფასიანი სერვისი გამორთულია, ან 500 აუდიოფაილისთვის, რომლის წაკითხვაც შეუძლებელია, ამიტომ რამდენიმე მცდელობის შემდეგ შეჩერდით.

გასაღების შეცვლას სხვადასხვა სერვისში განსხვავებული შედეგი აქვს.

• მეტყველების ტექსტად გარდაქმნისას ახალი გასაღები ქმნის ახალ დავალებას, რომელსაც წარმატებული დამუშავების შემთხვევაში ცალკე საფასური ერიცხება. თავდაპირველი გასაღები კვლავ აბრუნებს თავდაპირველ დავალებას, დამუშავების განახლების შემდეგაც.
• თარგმნისას ახალი გასაღები იდენტური შიგთავსით აბრუნებს შესაბამის რიგში მდგომ, მიმდინარე, დასრულებულ ან გადახდის მომლოდინე დავალებას, ახალი საფასურის გარეშე. ახალი დავალება იქმნება, თუ წინა წარუმატებელი იყო ან დამუშავების ვერსია შეიცვალა. დამუშავების ვერსიის შეცვლის შემდეგ თავდაპირველი გასაღებით თარგმნის გამეორება აბრუნებს 409-ს, ამიტომ შეინახეთ თავდაპირველი დავალების ID და პირდაპირ წაიკითხეთ დავალება.

მიიღეთ შედეგი თანხის დამატების შემდეგ

თუ დავალების სტატუსია awaiting_payment, დაამატეთ თანხა ისე, რომ ბალანსი სულ მცირე უტოლდებოდეს დავალების costUsd მნიშვნელობას, დამრგვალებულს ზემოთ უახლოეს $0.00001-ის ჯერადამდე, შემდეგ გაგზავნეთ POST /v3/SERVICE/JOB_ID/settle. თანხა იჭრება $0.00001-ის მთლიანი ნაბიჯებით და მოიცავს იმავე სერვისის წინა დავალებებიდან გადმოტანილ ნაშთსაც, ამიტომ ჩამოჭრილი თანხა შეიძლება აღემატებოდეს costUsd მნიშვნელობას $0.00001-ზე ნაკლები სხვაობით. ჰოსტზე api.multi.tel გაგზავნეთ JSON {} ან ცარიელი შიგთავსი; შიგთავსში ნებისმიერი თვისება უარყოფილია 400-ით. ჰოსტი api.multitel.net უგულებელყოფს შიგთავსს. ანგარიშსწორება გასცემს შენახულ შედეგს ტრანსკრიფციის ან თარგმნის ხელახლა შესრულების გარეშე. პასუხი შეიცავს დავალებას; დარწმუნდით, რომ მისი სტატუსია completed. თუ ბალანსი კვლავ არასაკმარისია, დავალების სტატუსი რჩება awaiting_payment და პასუხი კვლავ HTTP 200-ია.

მეტყველების ტექსტად გარდაქმნისას უკვე დასრულებული დავალების ანგარიშსწორება აბრუნებს მას ნიშნით duplicate: true, ხოლო რიგში მდგომი, მიმდინარე ან წარუმატებელი დავალების ანგარიშსწორება აბრუნებს 409-ს და კოდს transcription_not_awaiting_payment. თარგმნისას ნებისმიერი სხვა სტატუსის მქონე დავალების ანგარიშსწორება აბრუნებს დავალებას უცვლელად. ანგარიშსწორება ხელმისაწვდომია მხოლოდ ფასიანი დამუშავების ჩართვისას (სხვა შემთხვევაში 503). გადახდის მომლოდინე დავალებები ითვლება დაჯავშნილ ხარჯად, ამიტომ წინასწარ გადახდილ ანგარიშებზე მათ შეუძლიათ ახალი ფასიანი დავალებების გაგზავნის დაბლოკვა 402-ით, სანამ ანგარიშსწორება არ მოხდება.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

შეამოწმეთ გამოყენება

გამოიყენეთ GET /v3/SERVICE/usage. არასავალდებულო პარამეტრები from და to არის UTC თარიღები ფორმატში YYYY-MM-DD და ორივე სასაზღვრო თარიღი შედის დიაპაზონში. გამოტოვებისას from ნაგულისხმევად არის დღევანდელ დღემდე 30 დღით ადრე არსებული თარიღი, ხოლო to — დღევანდელი თარიღი (UTC). to არ უნდა იყოს უფრო ადრე, ვიდრე from, ხოლო თარიღებს შორის სხვაობა არ უნდა აღემატებოდეს 366 დღეს (მაქსიმუმ 367 თარიღი). არასწორი კალენდარული თარიღები, შებრუნებული ან უფრო გრძელი დიაპაზონი აბრუნებს 400-ს, ისევე როგორც სხვა მოთხოვნის პარამეტრები ჰოსტზე api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

პასუხი შეიცავს mode, currency (USD), from, to და days ველებს; ბოლო ველი არის სია, დალაგებული უახლესიდან უძველესამდე.

• მეტყველების ტექსტად გარდაქმნის ჩანაწერები დაჯგუფებულია თარიღისა და წყაროს მიხედვით. ისინი შეიცავს date, source (api ან hpbx Hosted PBX-ის ჩანაწერებისთვის), files, audioSeconds, billedSeconds, accruedUsd და debitedUsd ველებს.
• თარგმნის ჩანაწერები დაჯგუფებულია თარიღის, წყაროსა და ძრავის მიხედვით. ისინი შეიცავს date, source, engine, jobs, sourceCharacters, accruedUsd და debitedUsd ველებს.

accruedUsd არის ზუსტი ხარჯი ცხრა ათწილადი ნიშნით, ხოლო debitedUsd — ჩამოჭრილი თანხა ხუთი ათწილადი ნიშნით. გამოყენება აღირიცხება იმ UTC თარიღით, როცა თითოეული დავალების საფასურის ანგარიშსწორება მოხდა, ამიტომ რიგში მდგომი, მიმდინარე, წარუმატებელი და გადახდის მომლოდინე დავალებები არ ჩანს.

შეზღუდვები

თითოეულ ანგარიშს შეიძლება ჰქონდეს მეტყველების ტექსტად გარდაქმნისა და თარგმნის ჯამში მაქსიმუმ 50 დაუსრულებელი დავალება: რიგში მდგომი, მიმდინარე ან გადახდის მომლოდინე, Hosted PBX-ის ჩანაწერების დამუშავების ჩათვლით. ამ ზღვრის ან სერვისის საერთო წარმადობის ამოწურვისას გაგზავნის მოთხოვნები აბრუნებს 429-ს და კოდს transcription_queue_full ან translation_queue_full. ჰოსტი api.multi.tel ასევე ზღუდავს თითოეული კლიენტის IP მისამართს წუთში 300 მოთხოვნამდე, ამ ჰოსტისადმი ყველა მოთხოვნის ჯამურად დათვლით. ამ შეზღუდვისას ბრუნდება 429 სიხშირის შეზღუდვის სათაურებითა და ჩვეულებრივი ტექსტური შიგთავსით, JSON შეცდომის გარე სტრუქტურის ნაცვლად.

დაამუშავეთ მოთხოვნის შეცდომები

ძირითად ჰოსტზე წარუმატებელი მოთხოვნები აბრუნებს HTTP შეცდომის სტატუსსა და JSON-ს ველებით status: "error", code, message და requestId. ყოველი პასუხი ასევე შეიცავს X-Request-ID სათაურს. შეგიძლიათ საკუთარი მნიშვნელობა მიუთითოთ; 128 სიმბოლოზე გრძელი მნიშვნელობები იჭრება. თავსებადობის ჰოსტი აბრუნებს მხოლოდ შეცდომის კოდს ველში response.code. ჟურნალში შეიტანეთ მოთხოვნის ID, როცა ხელმისაწვდომია, და შეცდომის კოდი, მაგრამ არ შეიტანოთ აუდიო, ტექსტი ან ავთენტიფიკაციის მონაცემები.

გავრცელებული სტატუსები:

იხელმძღვანელეთ დაბრუნებული შეცდომის კოდით და ნუ ჩათვლით, რომ შემავალი მონაცემების შემოწმების ყველა შეცდომას ერთი სტატუსი აქვს.

429-ის ან 503-ის შემთხვევაში დაელოდეთ და ხელახლა სცადეთ მზარდი ლოდინის ინტერვალითა და იმავე გაგზავნის გასაღებით; გაითვალისწინეთ Retry-After სათაური, თუ არსებობს. არასწორი შემავალი ან ავთენტიფიკაციის მონაცემების შემთხვევაში ჯერ მიზეზი გამოასწორეთ. ნუ გაგზავნით განმეორებით ახალ გასაღებებს, სანამ წინა დავალებები კვლავ რიგშია.