งานถอดเสียงและแปลภาษา

ในตัวอย่างด้านล่าง ให้แทน SERVICE ด้วย speech_to_text หรือ translate และแทน JOB_ID ด้วย UUID ที่ได้รับกลับมา ทุกการดำเนินการต้องใช้ข้อมูลรับรองของบัญชีคุณตามที่อธิบายในหัวข้อ การยืนยันตัวตน และจำกัดขอบเขตอยู่ในบัญชีเจ้าของงาน คุณอ่านงานได้จากโฮสต์ API ใดก็ได้ในสองโฮสต์ แต่แต่ละโฮสต์ใช้โครงสร้างชั้นนอกของคำตอบต่างกัน จึงควรใช้โฮสต์เดียวกันอย่างสม่ำเสมอ

บน api.multitel.net ข้อผิดพลาดในการยืนยันตัวตน (401) จะถูกส่งกลับก่อนใช้โครงสร้างชั้นนอกนี้ และอาจมีเนื้อความต่างออกไป จึงควรตรวจสอบสถานะ HTTP ก่อนแยกวิเคราะห์คำตอบ

การยืนยันตัวตน

ทุกคำขอต้องมีข้อมูลรับรองของบัญชีคุณ งาน คีย์ป้องกันการทำซ้ำ (idempotency) ขีดจำกัด การใช้งาน และค่าบริการเป็นของบัญชีที่เป็นเจ้าของข้อมูลรับรองนั้น ข้อมูลเหล่านี้ใช้ร่วมกันระหว่างข้อมูลรับรองทั้งหมดของบัญชีบนทั้งสองโฮสต์ ไม่ว่าจะใช้ข้อมูลรับรองชุดใดส่งคำขอ

• 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 เมื่อมี หากข้อมูลหรือข้อมูลรับรองไม่ถูกต้อง ให้แก้สาเหตุก่อน อย่าส่งคีย์ใหม่ซ้ำๆ ขณะที่งานก่อนหน้ายังอยู่ในคิว