API chuyển giọng nói thành văn bản cho âm thanh đã ghi

API chuyển giọng nói thành văn bản của Hushscript nhận âm thanh đã ghi qua /v1/, sau đó cho phép script của bạn kiểm tra job định kỳ và đọc bản phiên âm. Đây là quy trình phiên âm trực tuyến, không phải endpoint truyền trực tiếp hay gọi mô hình nhận dạng thuần túy. Máy chủ MCP dùng cùng tài khoản, số dư và bearer token khi client của bạn ưu tiên công cụ hơn lệnh gọi HTTP.

Chuyển âm thanh và video thành văn bản qua API

API phiên âm âm thanh nhận file âm thanh đã chuẩn bị, bao gồm giọng nói đã ghi. Để tích hợp STT (speech-to-text), hãy gửi file đã ghi; không hỗ trợ truyền trực tiếp từ micro. Để phiên âm video, hãy tải lên nguyên trạng file MP4 hoặc MOV có track âm thanh: máy chủ đọc track âm thanh và bỏ qua phần video. Với mọi định dạng video khác, hãy trích xuất âm thanh trước; API không nhận URL video. Quy trình trong trình duyệt được giải thích tại chuyển video thành văn bản.

Bắt đầu nhanh

API cần token truy cập cá nhân, và có hai cách để có token. Bạn tạo token trong mục Tạo token mới trên trang MCP trong tài khoản, chọn scope và quyết định liệu token có được mua phút hay không. Hoặc một agent mở tài khoản riêng mà không có chủ tài khoản là con người: POST /v1/agent/accounts bắt đầu đăng ký trả phí, còn POST /v1/agent/accounts/{signup_id}/claim đổi bí mật xác nhận dùng một lần lấy tài khoản thực và token đầu tiên. Trong cả hai trường hợp, token chỉ hiển thị một lần và có dạng hsr1:<region>:pat.<id>.<secret>. Token được cấp qua đăng nhập OAuth của máy chủ MCP cũng dùng được tại đây; xem Kết nối. Token không thể tạo, liệt kê hay thu hồi token khác, và mỗi tài khoản có tối đa 25 token đang hoạt động. Toàn bộ quy trình tài khoản agent, bao gồm xoay vòng thông tin xác thực, nằm trong hướng dẫn Sử dụng tự động.

Khi có token, hãy gọi API trực tiếp. Ví dụ này mô tả tài khoản cá nhân mới trước khi xác minh thẻ hoặc mua phút; tài khoản do agent tạo bắt đầu với gói phút đã trả tiền:

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
  }
}

Phản hồi cho biết số dư tính bằng giây, số giây đang được giữ cho job đang chạy, credits_expire_at (luôn là null vì phút không hết hạn), có thẻ đã lưu hay chưa, vùng dữ liệu và các giới hạn tiếp nhận (max_active_jobs, max_daily_seconds và phần đã dùng). Giới hạn hằng ngày là hạn mức hiện có hiệu lực của tài khoản, không phải giá trị để ghi cố định trong mã. POST /v1/uploads kiểm tra số phút khả dụng, không kiểm tra thẻ: nếu không đủ, lệnh gọi trả về 3001 insufficient_balance.

API chuyển giọng nói thành văn bản có miễn phí không?

Không có gói API miễn phí chung, nhưng bạn có thể thử quy trình trước khi viết mã: bản xem trước công khai phiên âm tối đa năm phút từ một bản ghi trước khi đăng nhập. Tài khoản cá nhân đủ điều kiện sau đó nhận 30 phút miễn phí sau khi xác minh thẻ (xem bảng giá để biết cách hoạt động); tài khoản do agent tạo bỏ qua phút chào mừng và bắt đầu với gói đã mua khi đăng ký. Trong cả hai trường hợp, một job API đầy đủ đều cần tài khoản và số phút.

Tự động hóa toàn bộ quy trình

Các lệnh gọi /v1/ giống nhau dùng được với token do bạn tạo trong ứng dụng hoặc do agent nhận sau khi đăng ký trả phí (xem Sử dụng tự động). Việc lưu thẻ cần Checkout do Stripe lưu trữ trong trình duyệt; agent có thể điều khiển trình duyệt đó. Các lần mua ngoài phiên sau này vẫn có thể bị từ chối nếu ngân hàng phát hành thẻ yêu cầu xác thực.

1. Đọc tài khoản. GET /v1/account. Nếu cần mua phút và card_on_file là false, hãy lưu thẻ trước.

2. Lưu thẻ một lần. POST /v1/billing/setup-session trả về checkout_url, session_id và 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"
   }

   Mở URL trong trình duyệt bạn điều khiển và hoàn tất trang do Stripe lưu trữ; không bị tính phí và Hushscript không thấy thông tin thẻ. Sau đó, GET /v1/billing/cards liệt kê thẻ cùng id. POST /v1/billing/cards/default đổi thẻ mặc định nếu tài khoản có nhiều thẻ.

3. Mua phút. GET /v1/billing/packs liệt kê năm gói với id, seconds, amount và currency:

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

   POST /v1/billing/purchase với pack, quick_payment_method_id (id của thẻ đã lưu) và idempotency_key tính phí thẻ ngoài phiên và trả về balance_seconds mới:

   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 }

   Lệnh gọi cần scope billing, bật thanh toán trên token và bật thanh toán cho tài khoản. Nội dung yêu cầu không có id thẻ, hoặc thẻ bị từ chối, sẽ bị từ chối với 4021 pat_purchase_requires_app; thẻ mà ngân hàng phát hành yêu cầu xác thực thêm sẽ bị từ chối với 4023 pat_purchase_requires_authentication. Cả hai trường hợp đều không mở một trang không ai có thể hoàn tất.

4. Tải lên. POST /v1/uploads với size_bytes, duration_seconds (15 giây đến 10 giờ), title tùy chọn, transcription_options, matter_code và 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 là văn bản tự do dài tối đa 64 ký tự, chỉ có ý nghĩa với token thuộc một workspace: mã này hiển thị cùng job trong sổ cái và báo cáo sử dụng của workspace đó. Workspace có chính sách mã hồ sơ bắt buộc sẽ từ chối lượt tải lên thiếu mã, với org_matter_code_required. client_code được chấp nhận nhưng bỏ qua, vì khách hàng là thuộc tính của hồ sơ do quản trị viên workspace thiết lập.

   Lệnh gọi giữ một khoản tín dụng và trả về job_id cùng trang đầu tiên chứa URL các phần đã ký sẵn:

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

   PUT từng phần đến URL tương ứng (mặc định mỗi phần 32 MiB, phần cuối nhỏ hơn):

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

   Lấy các trang tiếp theo từ GET /v1/uploads/{job}/part-urls?start=<n> và gọi POST /v1/uploads/{job}/heartbeat trước khi chạm thời gian chờ 20 phút không hoạt động trong quá trình truyền dài. Khi URL đã ký sẵn không khả dụng, hoặc một phần bị lỗi, PUT /v1/uploads/{job}/parts/{n} gửi byte của phần đó qua API; PUT lặp lại thay thế phần đó, nên có thể thử lại an toàn. Được hỗ trợ: mp3, m4a, mp4 hoặc mov (dùng track âm thanh, bỏ qua track video), wav, flac, ogg hoặc opus, được kiểm tra trên máy chủ; với mọi định dạng video khác, hãy trích xuất âm thanh trước khi tải lên.

5. Bắt đầu và chờ. POST /v1/uploads/{job}/complete với n và etag của từng phần đã gửi đến URL ký sẵn (bỏ parts khi mọi phần đều được gửi qua 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\"" }
       ]
     }'

   Sau đó kiểm tra định kỳ GET /v1/jobs/{id}: state đi qua uploading, queued và processing đến done hoặc failed; job hoàn tất có 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. Đọc kết quả. GET /v1/transcripts/{id} trả về metadata và toàn bộ nội dung, cùng tên người nói, ngôn ngữ được phát hiện, thẻ và ngày tự động xóa:

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

   GET /v1/transcripts phân trang danh sách.

Các tùy chọn phiên âm giống hệt ứng dụng: language_code hoặc tự động phát hiện ngôn ngữ, speaker_detection, medical_mode (cần language_code là en, es, fr hoặc de, tính thêm +100%), translation_targets (+25% cho mỗi ngôn ngữ), multichannel, keyterms_prompt, prompt dạng văn bản tự do và dictionary_ids, prompt_preset_id đã lưu mà GET /v1/transcription-context liệt kê.

Một số chức năng tài khoản vẫn chỉ có qua MCP. Nhập từ liên kết, chỉnh sửa hoặc xóa bản phiên âm, Insights, xuất file, lưu từ điển và mẫu lời nhắc, cùng cài đặt tài khoản chưa có route /v1/; máy chủ MCP hỗ trợ tất cả bằng cùng token.

Xác thực

Mỗi lệnh gọi /v1/ mang bearer token trong header Authorization, được kiểm tra theo cùng các scope mà máy chủ MCP sử dụng:

Lệnh gọi ngoài scope của token thất bại với pat_scope_missing, HTTP 403. Scope billing cũng không hoạt động trừ khi thanh toán được bật cả trên token và cho tài khoản. Lệnh gọi thanh toán khi một trong hai công tắc tắt sẽ thất bại với cùng lỗi pat_scope_missing; cấp lại token không bật công tắc của tài khoản. Token không thể tạo, liệt kê hay thu hồi token, và tài khoản có tối đa 25 token đang hoạt động.

Bên gọi có thể chọn 11 scope này. pat:rotate là scope riêng được cấp cho token đầu tiên của tài khoản agent và các token kế nhiệm sau xoay vòng; nó cho phép token tự thay thế, không quản lý token khác. Bạn không thể chọn scope này khi tạo token trong ứng dụng.

Endpoint

Tài liệu OpenAPI production liệt kê 38 thao tác phương thức/đường dẫn trên 37 đường dẫn. Mỗi thao tác bên dưới yêu cầu scope được ghi:

/v1/agent/accounts mở đăng ký không có giao diện khi chưa có token, /v1/agent/accounts/{signup_id}/claim chuyển đăng ký đã trả phí thành tài khoản thực và token đầu tiên, còn /v1/agent/credentials/rotate cấp token kế nhiệm cho token đang gọi và vô hiệu hóa token đó khi token kế nhiệm được dùng lần đầu, không tác động đến thông tin xác thực khác của tài khoản. Hướng dẫn Sử dụng tự động mô tả cả ba bước từ đầu đến cuối.

Mỗi danh sách nhận limit và cursor không cần diễn giải, rồi trả về next_cursor có giá trị null ở trang cuối. Gửi lại cursor nguyên trạng; nó mã hóa vị trí để không bỏ sót hay lặp lại trang khi có hàng mới giữa các lệnh gọi.

Định nghĩa đầy đủ, hiện hành, cùng tham số và schema phản hồi cho mỗi thao tác, nằm trong tài liệu OpenAPI: dùng tài liệu này làm nguồn chuẩn thay cho bảng trên. Mọi bearer token đều truy cập được, bất kể scope, nên client có thể lấy tài liệu bằng thông tin xác thực sẵn có.

Giao diện MCP

Bạn thích công cụ hơn HTTP thuần túy? Máy chủ MCP cung cấp cùng tài khoản qua 56 công cụ thay cho các endpoint này, dành cho client dùng MCP thay vì REST. Máy chủ chỉ công bố công cụ mà scope của token đã kết nối cho phép.

Giới hạn

Yêu cầu dùng token của tài khoản con người bị giới hạn ở 1.200 mỗi phút cho mỗi token. Các token xoay vòng của tài khoản agent dùng chung hạn mức đó trên toàn tài khoản. Các route thanh toán gọi Stripe có hạn mức chặt hơn, 60 mỗi phút cho mỗi tài khoản khi bên gọi dùng PAT: tạo phiên lưu thẻ, mua phút, đổi thẻ mặc định, xóa thẻ và truy vấn danh sách thẻ khi không có dữ liệu trong bộ nhớ đệm. Giới hạn tốc độ thông thường trả về 429 rate_limited cùng Retry-After tính bằng giây; hãy chờ đủ thời gian đó trước khi thử lại. Giao dịch mua của tài khoản agent hoặc qua PAT của tài khoản con người có hạn mức 3 lần thử trong mỗi khoảng 24 giờ liên tục cho mỗi tài khoản. Lần mua khi đăng ký của agent cũng được tính; thẻ bị từ chối hoặc lỗi sau khi đã giữ lượt thử cũng được tính. Giao dịch mua qua phiên trình duyệt của con người được miễn hạn mức này. Từ chối do hết lượt trả về HTTP 429 với 4038 agent_purchase_capped và Retry-After. Bản ghi có thể dài từ 15 giây đến 10 giờ. GET /v1/account báo các giới hạn tiếp nhận hiện tại của tài khoản (max_active_jobs, max_daily_seconds).

Sandbox

Không có sandbox phiên âm chung: lệnh gọi /v1/ thông thường chạy trên tài khoản thực, và giao dịch mua tiêu tiền thật. Ngoại lệ là kiểm tra đăng ký: POST /v1/agent/accounts nhận dry_run: true, trả về id đăng ký dry_ không thể dùng để xác nhận tài khoản, và không mở phiên Stripe hay tài khoản.

Lỗi

Lỗi là nội dung JSON chứa code dạng số ổn định và slug error, với trạng thái HTTP như dưới đây. Nội dung lỗi /v1/ có cấu trúc cố định: error, code và một tập khóa chi tiết cố định. Cấu trúc lỗi /api không cố định và có thể chứa thêm thông tin. Các mã mà bên gọi tự động phải xử lý:

Tài liệu OpenAPI nêu chính xác mã lỗi mỗi thao tác có thể trả về, và máy chủ MCP công bố toàn bộ danh mục dưới dạng tài nguyên hushscript://error-codes.