API สำหรับนักพัฒนาของ Hushscript

Hushscript ยังตอบคำขอ REST ธรรมดาได้ด้วย สำหรับเอเจนต์และสคริปต์ที่อยากเรียก เอนด์พอยต์ HTTP มากกว่าจะรันไคลเอนต์ MCP เป็นบัญชีเดียวกัน ยอดคงเหลือ เดียวกัน และโทเคนแบบ bearer เดียวกันตลอดทั้งหมด: ไม่มีสิ่งใดในนี้เปลี่ยนแปลง วิธีคิดราคาหรือจัดเก็บการถอดเสียง

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

API ต้องใช้โทเคนเข้าถึงส่วนบุคคล และมีสองวิธีในการมีโทเคนนั้น บุคคลสร้างโทเคน ได้ภายใต้ Tokens ในหน้า 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": 3,
    "max_daily_seconds": 36000,
    "active_jobs": 0,
    "daily_seconds_used": 0
  }
}

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

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

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

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, และ 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"
     }'

   คำขอนี้จะพักเครดิตไว้และตอบกลับ 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, wav, flac, ogg หรือ opus ขนาดไม่เกิน 5 GB ตรวจสอบที่ฝั่งเซิร์ฟเวอร์; แยกแทร็กเสียงออกจากวิดีโอก่อนอัปโหลด

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\"" }
       ]
     }'

   จากนั้น poll 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 ตัว

เอนด์พอยต์

ใช้งานได้แล้ววันนี้ แต่ละรายการถูกควบคุมด้วยขอบเขตที่ระบุไว้:

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

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

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

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

ต้องการใช้เครื่องมือแทน HTTP ดิบๆ หรือไม่? เซิร์ฟเวอร์ MCP นำบัญชี เดียวกันนี้มาไว้หลังเครื่องมือ 51 รายการแทนเอนด์พอยต์เหล่านี้ สำหรับไคลเอนต์ ที่พูดภาษา MCP อยู่แล้วแทนที่จะเป็น REST

ขีดจำกัด

คำขอที่ทำด้วยโทเคนถูกจำกัดไว้ที่ 1,200 ครั้งต่อนาทีต่อโทเคน POST /v1/billing/setup-session และ POST /v1/billing/purchase ใช้ขีด จำกัดที่เข้มกว่าร่วมกันคือ 60 ครั้งต่อนาทีต่อบัญชี ก่อนที่จะเรียก Stripe คำขอที่ถูกปฏิเสธจะตอบกลับด้วย 429 rate_limited พร้อมส่วนหัว Retry-After ที่ระบุเวลาที่ต้องรอเป็นวินาที ให้รอตามเวลานั้นก่อนลองใหม่ การอัปโหลดถูกจำกัดไว้ที่ 5 GB และ 10 ชั่วโมง โดยมีขั้นต่ำ 15 วินาที และ ขีดจำกัดการรับงานของบัญชีเอง (max_active_jobs, max_daily_seconds) จะ ถูกรายงานโดย GET /v1/account

แซนด์บ็อกซ์

ไม่มีโหมด dry-run: ทุกคำขอ /v1/ ทำงานกับบัญชีจริง และการซื้อนาทีใช้เงินจริง

ข้อผิดพลาด

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

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