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 ก่อนแยกวิเคราะห์ อย่าสลับการเข้ารหัสอัปโหลดหรือตัวแยกวิเคราะห์ข้อมูลตอบกลับระหว่างโฮสต์

หากต้องการประเมินบนโฮสต์นี้ ให้ POST ฟิลด์ multipart เดิมไปที่ /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'