API ถอดเสียงเป็นข้อความจากเสียงบันทึก

API ถอดเสียงเป็นข้อความของ Hushscript รับเสียงบันทึกผ่าน /v1/ แล้วให้สคริปต์ของคุณตรวจสอบงานเป็นระยะและอ่านข้อความถอดเสียงได้ นี่คือขั้นตอนถอดเสียงออนไลน์ ไม่ใช่เอนด์พอยต์สำหรับสตรีมสดหรือเรียกโมเดลรู้จำเสียงโดยตรง เซิร์ฟเวอร์ MCP ใช้บัญชี ยอดคงเหลือ และโทเคนแบบ bearer เดียวกัน เมื่อไคลเอนต์ของคุณต้องการใช้เครื่องมือแทนการเรียก HTTP

ถอดเสียงจากเสียงและวิดีโอผ่าน API

API ถอดเสียงรับไฟล์เสียงที่เตรียมไว้แล้ว รวมถึงเสียงพูดที่บันทึกไว้ สำหรับการเชื่อมต่อ STT (speech-to-text) ให้ส่งไฟล์บันทึก เพราะไม่รองรับการสตรีมจากไมโครโฟนแบบสด หากต้องการถอดเสียงวิดีโอ ให้อัปโหลดไฟล์ MP4 หรือ MOV ที่มีแทร็กเสียงได้ตามเดิม เซิร์ฟเวอร์จะอ่านแทร็กเสียงและข้ามส่วนวิดีโอ หากเป็นรูปแบบวิดีโออื่น ให้แยกเสียงออกมาก่อน API ไม่รับ URL วิดีโอ ดูขั้นตอนในเบราว์เซอร์ได้ที่ ถอดข้อความจากวิดีโอ

เริ่มต้นใช้งาน

API ต้องใช้โทเคนเข้าถึงส่วนบุคคล ซึ่งมีสองวิธีในการรับโทเคน บุคคลสร้างโทเคนได้ใต้ สร้างโทเคนใหม่ ใน หน้า MCP ในบัญชี เลือกขอบเขตสิทธิ์ และกำหนดว่าโทเคนจะซื้อนาทีได้หรือไม่ หรือเอเจนต์เปิดบัญชีของตัวเองโดยไม่มีมนุษย์เป็นเจ้าของบัญชี: POST /v1/agent/accounts เริ่มการสมัครแบบชำระเงิน และ POST /v1/agent/accounts/{signup_id}/claim ใช้รหัสลับเปิดใช้งานบัญชีที่ใช้ได้ครั้งเดียวแลกเป็นบัญชีจริงและโทเคนแรก ไม่ว่ารับด้วยวิธีใด โทเคนจะแสดงเพียงครั้งเดียวและมีรูปแบบ hsr1:<region>:pat.<id>.<secret> โทเคนที่สร้างผ่านการเข้าสู่ระบบ OAuth ของเซิร์ฟเวอร์ MCP ก็ใช้ได้ที่นี่ ดู เชื่อมต่อ โทเคนไม่สามารถสร้าง แสดงรายการ หรือเพิกถอนโทเคนอื่นได้ และบัญชีหนึ่งมีโทเคนที่ใช้งานได้สูงสุด 25 ตัว ดูขั้นตอนบัญชีเอเจนต์ทั้งหมด รวมถึงการหมุนเวียนข้อมูลรับรอง ได้ที่ การถอดเสียงอัตโนมัติ

เมื่อมีโทเคนแล้ว คุณเรียก API ได้โดยตรง ตัวอย่างนี้แสดงบัญชีส่วนตัวใหม่ก่อนยืนยันบัตรหรือซื้อแพ็กเกจ ส่วนบัญชีที่เอเจนต์สร้างจะเริ่มด้วยแพ็กเกจนาทีที่ชำระเงินไว้:

curl https://api.hushscript.com/v1/account \
  -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

{
  "balance_seconds": 0,
  "held_seconds": 0,
  "credits_expire_at": null,
  "card_on_file": false,
  "data_region": "eu",
  "limits": {
    "max_active_jobs": 50,
    "max_daily_seconds": 144000,
    "active_jobs": 0,
    "used_today_seconds": 0
  }
}

คำตอบนี้แสดงยอดคงเหลือเป็นวินาที วินาทีที่พักไว้สำหรับงานที่กำลังดำเนินการ credits_expire_at (เป็น null เสมอ เพราะนาทีไม่มีวันหมดอายุ) สถานะบัตรที่บันทึกไว้ ภูมิภาคข้อมูล และขีดจำกัดการรับงาน (max_active_jobs, max_daily_seconds และปริมาณที่ใช้ไปแล้ว) ขีดจำกัดรายวันคือขีดจำกัดที่มีผลกับบัญชีในปัจจุบัน ไม่ใช่ค่าที่ควรกำหนดตายตัวในโค้ด POST /v1/uploads ตรวจสอบนาทีที่ใช้ได้ ไม่ใช่บัตร หากนาทีไม่พอจะตอบกลับด้วย 3001 insufficient_balance

API ถอดเสียงเป็นข้อความใช้ฟรีหรือไม่?

ไม่มี API ระดับใช้ฟรีทั่วไป แต่คุณลองขั้นตอนก่อนเขียนโค้ดได้: ตัวอย่างถอดเสียง สาธารณะถอดเสียงได้สูงสุดห้านาทีจากไฟล์บันทึกหนึ่งไฟล์ก่อนเข้าสู่ระบบ จากนั้นบัญชีส่วนตัวที่มีสิทธิ์จะได้รับฟรี 30 นาทีหลังยืนยันบัตร (ดูวิธีที่หน้า ราคา) บัญชีที่เอเจนต์สร้างจะไม่ได้รับนาทีต้อนรับ แต่เริ่มด้วยแพ็กเกจที่ซื้อตอนสมัคร ไม่ว่ากรณีใด งาน API เต็มรูปแบบต้องมีบัญชีและนาที

ทำให้เป็นอัตโนมัติตั้งแต่ต้นจนจบ

คำขอ /v1/ ชุดเดียวกันใช้ได้กับโทเคนที่บุคคลสร้างในแอป หรือโทเคนที่เอเจนต์ได้รับเมื่อเปิดใช้งานบัญชีหลังสมัครแบบชำระเงิน (ดู การถอดเสียงอัตโนมัติ) การบันทึกบัตรต้องทำผ่าน Checkout แบบโฮสต์ในเบราว์เซอร์ ซึ่งเอเจนต์ควบคุมได้ การซื้อแบบ off-session ในภายหลังยังอาจถูกปฏิเสธหากผู้ออกบัตรต้องการการยืนยันตัวตน

1. อ่านข้อมูลบัญชี GET /v1/account หากต้องซื้อนาทีและ card_on_file เป็น false ให้บันทึกบัตรก่อน

2. บันทึกบัตรครั้งเดียว POST /v1/billing/setup-session ตอบกลับ checkout_url, session_id และ expires_at:

   curl -X POST https://api.hushscript.com/v1/billing/setup-session \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8",
     "session_id": "seti_1PxYzQ2eZvKYlo2C",
     "expires_at": "2026-09-11T15:45:00Z"
   }

   เปิด URL ในเบราว์เซอร์ที่คุณควบคุมและทำขั้นตอนในหน้า Stripe แบบโฮสต์ให้เสร็จ ไม่มีการเรียกเก็บเงิน และ Hushscript ไม่เห็นข้อมูลบัตร จากนั้น GET /v1/billing/cards จะแสดงรายการบัตรพร้อม id หากบัญชีมีหลายใบ ใช้ POST /v1/billing/cards/default เปลี่ยนบัตรเริ่มต้น

3. ซื้อนาที GET /v1/billing/packs แสดงแพ็กเกจทั้งห้าพร้อม id, seconds, amount และ currency:

   curl https://api.hushscript.com/v1/billing/packs \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   POST /v1/billing/purchase พร้อม pack, quick_payment_method_id (id ของบัตรที่บันทึกไว้) และ idempotency_key จะเรียกเก็บเงินจากบัตรแบบ off-session และตอบกลับ balance_seconds ใหม่:

   curl -X POST https://api.hushscript.com/v1/billing/purchase \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "pack": "300min",
       "quick_payment_method_id": "pm_2QeT4bY7uX9mK3nP",
       "idempotency_key": "purchase-2026-09-11-02"
     }'

   { "balance_seconds": 18000 }

   คำขอนี้ต้องมีขอบเขต billing และเปิดใช้การเรียกเก็บเงินทั้งบนโทเคนและบัญชี หากเนื้อหาคำขอไม่มี id ของบัตร หรือบัตรถูกปฏิเสธ จะตอบกลับ 4021 pat_purchase_requires_app หากผู้ออกบัตรต้องการการยืนยันตัวตนเพิ่มเติม จะตอบกลับ 4023 pat_purchase_requires_authentication ทั้งสองกรณีไม่เปิดหน้าเว็บที่ไม่มีใครทำต่อให้เสร็จได้

4. อัปโหลด POST /v1/uploads พร้อม size_bytes, duration_seconds (15 วินาทีถึง 10 ชั่วโมง), title ที่ระบุหรือไม่ก็ได้, transcription_options, matter_code และ idempotency_key:

   curl -X POST https://api.hushscript.com/v1/uploads \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "size_bytes": 41943040,
       "duration_seconds": 1200,
       "title": "Q3 board call",
       "transcription_options": { "speaker_detection": true },
       "idempotency_key": "upload-2026-09-11-02"
     }'

   matter_code เป็นข้อความอิสระยาวไม่เกิน 64 อักขระ และมีผลเฉพาะกับโทเคนที่เป็นของพื้นที่ทำงาน โดยแสดงคู่กับงานในบันทึกรายการและรายงานการใช้งานของพื้นที่ทำงาน หากนโยบายเรื่องงานกำหนดให้ต้องระบุรหัส พื้นที่ทำงานจะปฏิเสธการอัปโหลดที่ไม่มีรหัสด้วย org_matter_code_required ส่วน client_code จะรับไว้แต่ไม่นำไปใช้ เพราะลูกค้าเป็นข้อมูลของเรื่องงานที่แอดมินพื้นที่ทำงานกำหนด

   คำขอนี้จะพักเครดิตไว้และตอบกลับ job_id พร้อมหน้าแรกของ URL ส่วนไฟล์ที่ลงลายเซ็นไว้ล่วงหน้า:

   {
     "job_id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "part_urls": [
       { "n": 1, "url": "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." }
     ]
   }

   ส่งแต่ละส่วนด้วย PUT ไปยัง URL ของส่วนนั้น (ค่าเริ่มต้นคือส่วนละ 32 MiB โดยส่วนสุดท้ายเล็กกว่า):

   curl -X PUT "https://r2.hushscript.com/uploads/job_5e2a91cf.../part-1?X-Amz-Signature=..." \
     --data-binary @part-01.bin

   ดึงหน้าถัดไปจาก GET /v1/uploads/{job}/part-urls?start=<n> และเรียก POST /v1/uploads/{job}/heartbeat ก่อนถึงเวลาหมดอายุจากการไม่มีกิจกรรม 20 นาที โดยเผื่อเวลาไว้ระหว่างการโอนที่ใช้เวลานาน หากใช้ URL ที่ลงลายเซ็นล่วงหน้าไม่ได้ หรือส่งส่วนใดไม่สำเร็จ ให้ใช้ PUT /v1/uploads/{job}/parts/{n} ส่งไบต์ของส่วนนั้นผ่าน API แทน การส่ง PUT ซ้ำจะแทนที่ส่วนนั้น จึงลองใหม่ได้อย่างปลอดภัย รองรับ: mp3, m4a, mp4 หรือ mov (ใช้แทร็กเสียง ข้ามแทร็กวิดีโอ), wav, flac, ogg หรือ opus ซึ่งเซิร์ฟเวอร์จะตรวจสอบ หากเป็นรูปแบบวิดีโออื่น ให้แยกเสียงออกมาก่อนอัปโหลด

5. เริ่มและรอ POST /v1/uploads/{job}/complete พร้อม n และ etag ของทุกส่วนที่ส่งไปยัง URL ที่ลงลายเซ็นไว้ล่วงหน้า (ละ parts หากส่งทุกส่วนผ่าน API):

   curl -X POST https://api.hushscript.com/v1/uploads/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8/complete \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293" \
     -H "Content-Type: application/json" \
     -d '{
       "parts": [
         { "n": 1, "etag": "\"9f86d081884c7d65\"" }
       ]
     }'

   จากนั้นตรวจสอบ GET /v1/jobs/{id} เป็นระยะ: state เปลี่ยนจาก uploading ผ่าน queued และ processing ไปเป็น done หรือ failed งานที่เสร็จแล้วมี transcript_id:

   curl https://api.hushscript.com/v1/jobs/job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   {
     "id": "job_5e2a91cf4d7b6081a9f3c2e4b5d6a7c8",
     "state": "done",
     "transcript_id": "trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9"
   }

6. อ่านผลลัพธ์ GET /v1/transcripts/{id} ตอบกลับเมทาดาทาและเนื้อหาทั้งหมด พร้อมชื่อผู้พูด ภาษาที่ตรวจพบ แท็ก และวันลบอัตโนมัติ:

   curl https://api.hushscript.com/v1/transcripts/trs_2b6e1d4a9f7c3088a1b2c3d4e5f6a7b9 \
     -H "Authorization: Bearer hsr1:eu:pat.7f3a9c.2b6e1d4a9f2c88b1a3d4e5f60718293"

   GET /v1/transcripts แสดงรายการแบบแบ่งหน้า

ตัวเลือกการถอดเสียงตรงกับแอปทุกตัว: language_code หรือการตรวจหาภาษาอัตโนมัติ, speaker_detection, medical_mode (ต้องระบุ language_code เป็น en, es, fr หรือ de และคิดเพิ่ม +100%), translation_targets (+25% ต่อภาษา), multichannel, keyterms_prompt, prompt แบบข้อความอิสระ รวมถึง dictionary_ids และ prompt_preset_id ที่บันทึกไว้และแสดงรายการผ่าน GET /v1/transcription-context

บางส่วนของบัญชียังใช้ได้ผ่าน MCP เท่านั้น การนำเข้าจากลิงก์ การแก้ไขหรือลบข้อความถอดเสียง Insights การส่งออก การบันทึกพจนานุกรมและพรอมต์สำเร็จรูป และการตั้งค่าบัญชียังไม่มีเส้นทาง /v1/ เซิร์ฟเวอร์ MCP รองรับทั้งหมดด้วยโทเคนเดียวกัน

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

ทุกคำขอ /v1/ ส่งโทเคนแบบ bearer ในส่วนหัว Authorization โดยตรวจสอบกับขอบเขตสิทธิ์ชุดเดียวกับที่เซิร์ฟเวอร์ MCP ใช้:

คำขอที่อยู่นอกขอบเขตของโทเคนจะล้มเหลวด้วย pat_scope_missing ที่สถานะ 403 ขอบเขต billing ก็ใช้ไม่ได้จนกว่าจะเปิดใช้การเรียกเก็บเงินทั้งบนโทเคนและบัญชี หากสวิตช์ใดปิดอยู่ คำขอเรียกเก็บเงินจะล้มเหลวด้วย pat_scope_missing เช่นกัน การสร้างโทเคนใหม่ไม่ได้เปิดสวิตช์ของบัญชี โทเคนไม่สามารถสร้าง แสดงรายการ หรือเพิกถอนโทเคนได้ และบัญชีหนึ่งมีโทเคนที่ใช้งานได้สูงสุด 25 ตัว

ผู้เรียกเลือกขอบเขตทั้ง 11 รายการนี้ได้ ส่วน pat:rotate เป็นขอบเขตแยกที่มอบให้โทเคนแรกของบัญชีเอเจนต์และโทเคนที่สืบต่อจากการหมุนเวียน โดยให้โทเคนแทนที่ตัวเองได้ ไม่ใช่จัดการโทเคนอื่น คุณเลือกขอบเขตนี้ไม่ได้เมื่อสร้างโทเคนในแอป

เอนด์พอยต์

เอกสาร OpenAPI ของระบบจริงระบุ 38 การดำเนินการตามเมธอด/พาธใน 37 พาธ แต่ละการดำเนินการด้านล่างต้องมีขอบเขตสิทธิ์ที่ระบุ:

/v1/agent/accounts เริ่มการสมัครที่เอเจนต์ดำเนินการได้โดยยังไม่มีโทเคน /v1/agent/accounts/{signup_id}/claim เปิดใช้งานบัญชีจากการสมัครที่ชำระเงินแล้วเป็นบัญชีจริงพร้อมโทเคนแรก และ /v1/agent/credentials/rotate สร้างโทเคนที่สืบต่อจากโทเคนที่เรียก และยกเลิกโทเคนนั้นเมื่อโทเคนที่สืบต่อถูกใช้ครั้งแรก โดยไม่แตะข้อมูลรับรองอื่นในบัญชี ดูทั้งสามขั้นตอนตั้งแต่ต้นจนจบได้ที่ การถอดเสียงอัตโนมัติ

ทุกรายการรับ limit และ cursor ที่ผู้เรียกไม่ต้องตีความ แล้วตอบกลับ next_cursor ซึ่งเป็น null ในหน้าสุดท้าย ส่ง cursor กลับโดยไม่เปลี่ยนแปลง เพราะค่าดังกล่าวเข้ารหัสตำแหน่งไว้ จึงไม่ข้ามหรือแสดงหน้าซ้ำเมื่อมีแถวใหม่เข้ามาระหว่างคำขอ

นิยามฉบับเต็มที่เป็นปัจจุบัน พร้อมพารามิเตอร์และสคีมาคำตอบของทุกการดำเนินการ อยู่ใน เอกสาร OpenAPI ให้ยึดเอกสารนี้เป็นแหล่งอ้างอิงเหนือกว่าตารางนี้ โทเคนแบบ bearer ใดก็เข้าถึงได้โดยไม่จำกัดขอบเขต ไคลเอนต์จึงดึงเอกสารด้วยข้อมูลรับรองที่มีอยู่ได้

อินเทอร์เฟซ MCP

ต้องการใช้เครื่องมือแทน HTTP โดยตรงหรือไม่? เซิร์ฟเวอร์ MCP ให้เข้าถึงบัญชีเดียวกันผ่านเครื่องมือ 56 รายการแทนเอนด์พอยต์เหล่านี้ สำหรับไคลเอนต์ที่รองรับ MCP อยู่แล้วแทน REST โดยประกาศเฉพาะเครื่องมือที่ขอบเขตของโทเคนที่เชื่อมต่ออนุญาต

ขีดจำกัด

คำขอที่ใช้โทเคนของบัญชีบุคคลจำกัดที่ 1,200 ครั้งต่อนาทีต่อโทเคน โทเคนที่หมุนเวียนของบัญชีเอเจนต์ใช้โควตานี้ร่วมกันทั้งบัญชี เส้นทางเรียกเก็บเงินที่เรียก Stripe ใช้ขีดจำกัดที่เข้มกว่าร่วมกัน คือ 60 ครั้งต่อนาทีต่อบัญชีสำหรับผู้เรียกด้วย PAT: เซสชันตั้งค่า การซื้อ การเปลี่ยนบัตรเริ่มต้น การลบบัตร และกรณีที่ไม่พบรายการบัตรในแคช การจำกัดอัตราทั่วไปตอบกลับ 429 rate_limited พร้อม Retry-After เป็นวินาที ให้รอตามนั้นก่อนลองใหม่ การซื้อของบัญชีเอเจนต์หรือด้วย PAT ของบัญชีบุคคลใช้เพดานร่วมกันที่ 3 ครั้งต่อช่วง 24 ชั่วโมงแบบต่อเนื่องต่อบัญชี การซื้อตอนสมัครของเอเจนต์นับรวมด้วย รวมถึงการปฏิเสธหรือข้อผิดพลาดหลังกันโควตาความพยายามซื้อไว้แล้ว การซื้อผ่านเซสชันเบราว์เซอร์ของบุคคลได้รับยกเว้น การปฏิเสธเพราะถึงเพดานตอบกลับ HTTP 429 พร้อม 4038 agent_purchase_capped และ Retry-After ไฟล์บันทึกยาวได้ตั้งแต่ 15 วินาทีถึง 10 ชั่วโมง GET /v1/account รายงานขีดจำกัดการรับงานปัจจุบันของบัญชี (max_active_jobs, max_daily_seconds)

แซนด์บ็อกซ์

ไม่มีแซนด์บ็อกซ์ทั่วไปสำหรับการถอดเสียง: คำขอ /v1/ ปกติทำงานกับบัญชีจริง และการซื้อใช้เงินจริง ข้อยกเว้นคือการตรวจสอบการสมัคร: POST /v1/agent/accounts รับ dry_run: true ตอบกลับ id การสมัคร dry_ ที่ใช้เปิดใช้งานบัญชีไม่ได้ และไม่เปิดเซสชัน Stripe หรือบัญชี

ข้อผิดพลาด

ข้อผิดพลาดเป็นเนื้อหา JSON ที่มี code ตัวเลขคงที่และ slug ของ error พร้อมสถานะ HTTP ตามตารางด้านล่าง เนื้อหาข้อผิดพลาด /v1/ มีโครงสร้างที่กำหนดตายตัว: error, code และชุดคีย์รายละเอียดที่กำหนดไว้ รูปแบบข้อผิดพลาด /api ไม่ได้กำหนดตายตัวและอาจมีข้อมูลเพิ่มเติม รหัสที่ผู้เรียกอัตโนมัติต้องจัดการมีดังนี้:

เอกสาร OpenAPI ระบุรหัสที่แต่ละการดำเนินการคืนค่าได้อย่างแน่นอน และเซิร์ฟเวอร์ MCP เผยแพร่รายการรหัสทั้งหมดผ่านทรัพยากร hushscript://error-codes