ტექსტის თარგმნის API

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

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

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

ჰოსტზე api.multi.tel ყველა გზა ასევე ხელმისაწვდომია პრეფიქსით /v1/translate პრეფიქსის ნაცვლად /v3/translate. ჰოსტზე api.multitel.net გამოიყენეთ /v3/translate გზები.

სერვისის ინფორმაციის პასუხი მოიცავს შემდეგ მონაცემებს: enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages და ratesNanosPerCharacter. cpuLanguages მიუთითებს სტანდარტული თარგმნისთვის მიღებული ძირითადი ენების კოდებს. ველი ratesNanosPerCharacter გვაწვდის თითოეული ძრავისთვის დაყენებულ ფასს საწყისი ტექსტის თითო კოდურ წერტილზე, აშშ დოლარის მემილიარდედებში: მნიშვნელობა 5000 ნიშნავს $5-ს მილიონ კოდურ წერტილზე. პასუხი არ გვაწვდის ინფორმაციას, ხელმისაწვდომია თუ არა ამჟამად გაუმჯობესებული თარგმნა; გაუმჯობესებული თარგმნის შეფასება აბრუნებს 503-ს, როდესაც ის ხელმისაწვდომი არ არის. ინფორმაციის წაკითხვა უფასოა.

ტექსტის თარგმნა

გაგზავნეთ JSON სათაურით Content-Type: application/json მისამართზე POST https://api.multi.tel/v3/translate. თითოეულ დავალებას ერთი სამიზნე ენა აქვს, ამიტომ თითოეული სამიზნისთვის ცალკე დავალება გაგზავნეთ.

ენისა და რეგიონის კოდები არის BCP 47 ტეგები, რომლებიც 2-დან 63-მდე ასოს, ციფრსა და დეფისს შეიცავს. ისინი კანონიკურ ფორმას იღებს, ამიტომ en-us ჩაიწერება როგორც en-US. არასწორი ტეგები, აგრეთვე und, mul ან zxx, აბრუნებს 400 invalid_translation_language. სტანდარტული თარგმნის ხელმისაწვდომობა ძირითადი ენის მიხედვით მოწმდება, ხოლო nb და nn ითვლება როგორც no. რეგიონული სამიზნე კოდი, მაგალითად fr-CA, მიიღება და ინახება, მაგრამ სტანდარტული შედეგი ძირითად ენას ემყარება და რეგიონული თავისებურებების ასახვა გარანტირებული არ არის.

ამ ჰოსტზე მოთხოვნის სხეულის ზომა 128 KiB-ს არ უნდა აღემატებოდეს. ტექსტი გაგზავნეთ UTF-8 კოდირებით და არა თითოეული არა-ASCII სიმბოლოს \u მიმდევრობით ჩაწერით, რამაც 20,000-სიმბოლოიანი მოთხოვნა შეიძლება ლიმიტს გადააცილოს.

სხეულში მხოლოდ ეს ოთხი ველი მიიღება. ნებისმიერი სხვა თვისება უარყოფილია პასუხით 400 invalid_translation_request, მათ შორის idempotency_key, მფლობელის ID-ები, უფასო დამუშავების ნიშნულები და სეგმენტების მასივები.

იდემპოტენტურობა და ხელახლა გამოყენება

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

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

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

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

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

ახალი დავალება აბრუნებს HTTP 202-ს. მაგალითის ტექსტი 57 კოდურ წერტილს შეიცავს, ამიტომ მილიონ კოდურ წერტილზე $5-ის შემთხვევაში მისი ღირებულებაა $0.000285. შემოკლებული პასუხი (იდენტიფიკატორი მაგალითია):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

გაგზავნამ ასევე შეიძლება დააბრუნოს 402 insufficient_balance, როდესაც წინასწარ გადახდილი ბალანსი ამ დავალებასა და თქვენს სხვა დაუსრულებელ დავალებებს ერთად ვერ ფარავს, და 429 translation_queue_full, როდესაც თქვენს ანგარიშს ან სერვისს მეტისმეტად ბევრი დაუსრულებელი დავალება აქვს. შემდეგ შემთხვევებში ბრუნდება 503:

• paid_translation_not_enabled, როდესაც ფასიანი თარგმნა გამორთულია.
• translation_unavailable გაუმჯობესებული თარგმნის მოთხოვნისთვის, როდესაც გაუმჯობესებული თარგმნა ხელმისაწვდომი არ არის.
• translation_pricing_unavailable, როდესაც არჩეული ძრავისთვის ფასი დაყენებული არ არის.

პასუხების 429 და 503 შემთხვევაში მოგვიანებით ხელახლა სცადეთ იმავე გასაღებით.

ხარისხის არჩევა

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

სტანდარტული თარგმნა CPU-ზე მომუშავე დამმუშავებლებში სრულდება. გაუმჯობესებული თარგმნა ტექსტს დაყენებულ გარე AI სერვისს უგზავნის. მისი შედეგიც შესამოწმებელია; სერვისი არ იძლევა გარანტიას, რომ ერთი ძრავა ყველა ენობრივი წყვილისა თუ ტიპის ტექსტისთვის უფრო ზუსტია.

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

გამოიყენეთ GET /v3/translate იმავე API ჰოსტზე მიმდინარე ხელმისაწვდომობის, სტანდარტული თარგმნის მხარდაჭერილი ენებისა და დაყენებული ფასების შესამოწმებლად. სტანდარტული მოთხოვნა, რომლის საწყისი ან სამიზნე ძირითადი ენა არ არის სიაში cpuLanguages, აბრუნებს 422 translation_language_pair_unavailable. როდესაც ველი source_language მითითებულია და მისი ძირითადი ენა სამიზნისას ემთხვევა, მოთხოვნა აბრუნებს 409 translation_same_language დავალების შექმნის ნაცვლად. გაუმჯობესებული თარგმნა ცალკე ირთვება: როდესაც ის მიუწვდომელია, გაუმჯობესებული თარგმნის დავალებების გაგზავნა და შეფასებები აბრუნებს 503-ს.

ჯერ შეაფასეთ

ჰოსტზე api.multi.tel იგივე JSON სხეული გაგზავნეთ მისამართზე POST /v3/translate/estimate. იდემპოტენტურობის გასაღები საჭირო არ არის. შეფასება იმავე ვალიდაციას იყენებს, 422 და 409 შემოწმებების ჩათვლით, მაგრამ არ ქმნის დავალებას, არ თარგმნის ტექსტს, არ ჯავშნის თანხას, არ ამოწმებს თქვენს ბალანსს და არ ჩამოჭრის თანხას თქვენი ანგარიშიდან. იგი აბრუნებს HTTP 200-ს შემდეგი ველებით: estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd და costUsd ობიექტში data. ზემოთ მოცემულ მაგალითში ველის costUsd მნიშვნელობაა 0.000285000 სტანდარტული ფასით. როდესაც გაუმჯობესებული თარგმნა ხელმისაწვდომი არ არის, გაუმჯობესებული თარგმნის შეფასება აბრუნებს 503 service_unavailable. შეფასებები ამჟამად დაყენებულ ფასს იყენებს. დავალების ფასი მისი შექმნისას ფიქსირდება და საფასურიც ამ ფასით ირიცხება.

თარგმანის მიღება

ახალი გაგზავნა აბრუნებს HTTP 202-ს, ხოლო არსებული ან ხელახლა გამოყენებული დავალება — HTTP 200-ს. შეინახეთ data.id და მიჰყევით დოკუმენტს „დავალებებთან მუშაობის წესი“. დავალების ობიექტი შეიცავს შემდეგ ველებს:

• id, status, engine, sourceLocale და targetLocale.
• sourceCharacters, costUsd, costIsEstimate და pricePerMillionCharactersUsd.
• progress და createdAt.
• modelVersion, დამუშავების ვერსიის გაუმჭვირვალე სტრიქონი.
• duplicate ხელახლა გამოყენებული დავალებების პასუხებში.
• failureCode წარუმატებელი დავალებებისთვის: translation_failed, translation_timeout, input_failed ან worker_lease_lost.

წარუმატებელი დავალების ველის costUsd მნიშვნელობა ნულია.

დასრულებულ დავალებას აქვს data.result შემდეგი ველებით: sourceLocale (ცარიელია, თუ საწყისი ენა არ იყო მითითებული), targetLocale, ნათარგმნი text (სეგმენტების ტექსტი, ხაზის წყვეტებით შეერთებული) და segments. ამ API-ით გაგზავნილი ტექსტისთვის ველი segments შეიცავს ერთ ჩანაწერს ნათარგმნი ველით text და სამიზნე ენის ველით language. გადახდის მომლოდინე დავალებების შედეგები ანგარიშსწორებამდე არ გაიცემა.

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

თავსებადობის საბოლოო წერტილი POST https://api.multitel.net/v3/translate იღებს იმავე JSON ველებსა და იმავე Idempotency-Key სათაურს. სათაურის არარსებობისას იგი JSON სხეულში ასევე იღებს სტრიქონს idempotency_key. ნებისმიერი სხვა დამატებითი ველი უარყოფილია პასუხით 400 unsupported_translation_option. ამ ჰოსტზე დაუმუშავებელი სხეულის ზომა შეიძლება იყოს არაუმეტეს 256,000 ბაიტისა, ხოლო 20,000 კოდურ წერტილზე გრძელი ტექსტი აბრუნებს 413 translation_too_large და არა 400-ს. ცარიელი ველი source_language გამოტოვებულად ითვლება. პასუხი 429 შეიცავს Retry-After: 15. ეს ჰოსტი ასევე აბრუნებს შემდეგ შეცდომებს:

• 400 json_body_required როდესაც სხეული არ არის, არასწორი JSON-ია ან JSON სკალარული მნიშვნელობაა. გაგზავნეთ JSON ობიექტი.
• 400 invalid_translation_options როდესაც text, target_language ან engine არ არის, ცარიელია ან სტრიქონი არ არის, ან ველი source_language სტრიქონი არ არის.
• 400 invalid_translation_text მხოლოდ თეთრი სივრცისგან შემდგარი ტექსტის შემთხვევაში.
• 400 invalid_translation_engine უცნობი ძრავის შემთხვევაში.
• 400 idempotency_key_required გასაღების არარსებობის, ცარიელი ან მეტისმეტად გრძელი გასაღების, ან არასტრიქონული ველის idempotency_key შემთხვევაში.
• 400 invalid_job არასწორი ფორმატის დავალების ID-ის შემთხვევაში.

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