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 เดิม หากไม่มีส่วนหัว ยังยอมรับสตริง idempotency_key ในเนื้อหา JSON ด้วย ฟิลด์เพิ่มเติมอื่นถูกปฏิเสธด้วย 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.