API dành cho nhà phát triển Hushscript

Hushscript cũng trả lời các lệnh gọi REST thuần túy, dành cho agent và script muốn gọi một endpoint HTTP hơn là chạy một client MCP. Xuyên suốt vẫn là cùng tài khoản, cùng số dư, và cùng bearer token: không có gì ở đây làm thay đổi cách tính giá hay lưu trữ của việc phiên âm.

Bắt đầu nhanh

API cần một personal access token, và có hai cách để có được một token. Một con người tạo ra một token dưới mục Tokens trên trang MCP trong tài khoản, chọn các scope của nó, và quyết định liệu nó có được mua phút hay không. Hoặc một agent tự mở tài khoản của riêng mình mà không cần con người nào: POST /v1/agent/accounts bắt đầu một lượt đăng ký có trả phí, và POST /v1/agent/accounts/{signup_id}/claim đổi bí mật xác nhận dùng một lần của nó lấy một tài khoản thật và một token đầu tiên. Dù theo cách nào, token chỉ hiện ra một lần duy nhất và có dạng hsr1:<region>:pat.<id>.<secret>. Một token được tạo qua đăng nhập OAuth của máy chủ MCP cũng dùng được ở đây; xem Kết nối. Một token không bao giờ có thể tạo, liệt kê hay thu hồi các token khác, và một tài khoản giữ tối đa 25 token đang hoạt động; toàn bộ luồng tài khoản agent, bao gồm việc 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, gọi thẳng 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
  }
}

Kết quả trả lời số dư tính bằng giây, số giây đang bị giữ bởi các job đang chạy, ngày hết hạn của credit, liệu có thẻ đã lưu hay không, khu vực dữ liệu, và các giới hạn nhận job (max_active_jobs, max_daily_seconds, cùng mức đã dùng). Một tài khoản mới bắt đầu với số dư bằng 0. POST /v1/uploads kiểm tra số dư, không phải thẻ: không có phút thì nó trả về 3001 insufficient_balance. Thẻ chính là cách số dư có được, vì lượt xác minh thẻ một lần trong ứng dụng mở khóa 30 phút miễn phí, và các gói phút được mua dựa trên một thẻ đã lưu.

Tự động hóa từ đầu đến cuối

Mọi thứ sau khi tài khoản đã tồn tại đều chạy mà không cần con người, bất kể tài khoản đó được một con người mở trong ứng dụng hay một agent mở qua /v1/agent/accounts (xem Sử dụng tự động). Chỉ còn lại đúng một bước trình duyệt, và một agent có thể tự điều khiển trình duyệt đó.

1. Đọc tài khoản. GET /v1/account. Nếu 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 một trình duyệt bạn kiểm soát và hoàn tất trang Stripe được lưu trữ sẵn; không có gì bị tính phí và Hushscript không bao giờ thấy thông tin thẻ. Sau đó GET /v1/billing/cards liệt kê thẻ đó cùng id của nó. POST /v1/billing/cards/default đổi thẻ mặc định nếu tài khoản giữ 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à một idempotency_key sẽ tính phí vào thẻ mà không cần thao tác trong 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 }

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

4. Tải lên. POST /v1/uploads với size_bytes, duration_seconds (từ 15 giây đến 10 giờ), một title tùy chọn, transcription_options, và một 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"
     }'

   Lệnh gọi này đặt một khoản giữ credit và trả về một job_id cùng trang đầu tiên của các URL phần đã ký sẵn (presigned):

   {
     "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 lên URL của nó (mỗi phần 32 MiB theo mặc định, 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 trong khoảng thời gian còn đủ an toàn so với giới hạn nhàn rỗi 20 phút khi truyền tải kéo dài. Khi các 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 các byte của phần đó qua chính API thay thế; một PUT lặp lại sẽ thay thế phần đó, nên việc thử lại luôn an toàn. Chỉ nhận audio: mp3, m4a, wav, flac, ogg, hoặc opus, tối đa 5 GB, được kiểm tra trên server; hãy tách track audio ra khỏi video 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 mỗi phần bạn đã gửi tới một URL đã ký sẵn (bỏ qua 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 đó liên tục hỏi GET /v1/jobs/{id}: state đi qua uploading, queued, và processing rồi tới done hoặc failed, và một job hoàn tất mang theo một 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ữ đã phát hiện, thẻ gắn, 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 như trong ứng dụng: language_code hoặc tự động phát hiện, speaker_detection, medical_mode (cần language_code thuộc en, es, fr, hoặc de, tính phí thêm 100%), translation_targets (thêm 25% cho mỗi ngôn ngữ), multichannel, keyterms_prompt, một prompt dạng văn bản tự do, và các dictionary_ids cùng prompt_preset_id đã lưu mà GET /v1/transcription-context liệt kê.

Một phần tài khoản vẫn chỉ khả dụng 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, và cài đặt tài khoản đều chưa có route /v1/ nào; máy chủ MCP bao phủ toàn bộ những việc đó bằng cùng một token.

Xác thực

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

Một lệnh gọi ngoài các scope của token sẽ thất bại với pat_scope_missing, mã 403. Scope billing cũng vô hiệu cho đến khi chủ tài khoản bật thanh toán cho tài khoản đó trong ứng dụng; một lệnh gọi thanh toán trên một tài khoản chưa bật công tắc đó sẽ thất bại với cùng pat_scope_missing, và việc tạo lại token không xóa bỏ tình trạng đó. Một token không thể tạo, liệt kê hay thu hồi các token khác, và một tài khoản giữ tối đa 25 token đang hoạt động.

Endpoint

Đang hoạt động ngay hôm nay, mỗi endpoint được canh giữ bởi scope tương ứng:

/v1/agent/accounts mở một lượt đăng ký không cần giao diện mà chưa có token nào, /v1/agent/accounts/{signup_id}/claim biến một lượt đăng ký đã thanh toán thành một tài khoản thật và token đầu tiên của nó, và /v1/agent/credentials/rotate tạo ra một token kế nhiệm cho token đang gọi và thu hồi token đó, không chạm đến bất kỳ thông tin xác thực nào khác trên tài khoản. Hướng dẫn Sử dụng tự động trình bày cả ba từ đầu đến cuối.

Mọi danh sách đều nhận một limit và một cursor không rõ nghĩa, và trả về một next_cursor có giá trị null ở trang cuối. Gửi lại cursor y nguyên; nó mã hóa vị trí, nên một trang không bao giờ bị bỏ sót hay lặp lại khi có dòng mới xuất hiện giữa các lệnh gọi.

Định nghĩa đầy đủ, cập nhật, với tham số và schema phản hồi cho mọi thao tác, là tài liệu OpenAPI: hãy coi đó là nguồn sự thật đáng tin hơn bảng trên. Tài liệu này được phục vụ cho bất kỳ bearer token nào bất kể scope, nên một client có thể lấy nó bằng chính thông tin xác thực mình đang có.

Giao diện MCP

Thích dùng công cụ hơn là HTTP thuần túy? Máy chủ MCP đặt cùng tài khoản đó phía sau 51 công cụ thay vì các endpoint này, dành cho một client đã nói sẵn MCP thay vì REST.

Giới hạn

Các lệnh gọi bằng token bị giới hạn ở 1.200 lệnh mỗi phút cho mỗi token. POST /v1/billing/setup-session và POST /v1/billing/purchase dùng chung một hạn mức chặt hơn, 60 lệnh mỗi phút cho mỗi tài khoản, trước cả lệnh gọi Stripe mà chúng sẽ thực hiện. Một yêu cầu bị từ chối trả về 429 rate_limited kèm header Retry-After nêu rõ thời gian chờ tính bằng giây; hãy chờ đúng khoảng đó trước khi thử lại. Tải lên bị giới hạn ở 5 GB và 10 giờ, với mức tối thiểu 15 giây, và các giới hạn nhận job riêng của tài khoản (max_active_jobs, max_daily_seconds) được báo cáo bởi GET /v1/account.

Sandbox

Không có chế độ dry-run: mọi lệnh gọi /v1/ đều chạy trên một tài khoản thật, và việc mua phút tiêu tiền thật.

Lỗi

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

Tài liệu OpenAPI nêu rõ mã lỗi chính xác mà 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.