Chuyển thành văn bản tự động cho agent và script

Phiên âm tự động trong Hushscript chuyển một bản ghi âm thanh có sẵn thành bản phiên âm có thể chỉnh sửa. Trong ứng dụng trên trình duyệt, bạn cũng có thể bắt đầu với video trên thiết bị: Hushscript chuẩn bị âm thanh ngay trên thiết bị và chỉ gửi âm thanh đó để nhận dạng trực tuyến. Bạn tự xem lại và sửa kết quả: đây không phải dịch vụ phiên âm được con người hiệu đính hay chứng nhận.

Cách chuyển thành văn bản tự động hoạt động

1. Chuẩn bị bản ghi. Dùng file âm thanh, nhập liên kết âm thanh được hỗ trợ hoặc ghi âm giọng nói trong ứng dụng trên trình duyệt. Với bản ghi video, chọn file trên thiết bị để ứng dụng chuẩn bị âm thanh tại chỗ.
2. Gửi và chờ bản phiên âm. Ứng dụng xử lý việc tải lên và trạng thái. Agent có thể tải âm thanh đã chuẩn bị lên từng phần qua REST API hoặc dùng công cụ MCP trong phạm vi quyền được cấp, rồi kiểm tra tác vụ cho đến khi bản phiên âm sẵn sàng.
3. Xem lại và xuất. Chỉnh sửa bản phiên âm và nhãn người nói trong ứng dụng hoặc lấy văn bản qua API. Token của agent cũng có thể xuất bản phiên âm trong phạm vi quyền được cấp.

Phần mềm chuyển thành văn bản tự động cho âm thanh và video

Phần mềm phiên âm tự động của Hushscript chuyển lời nói đã ghi thành văn bản có thể tìm kiếm, chỉnh sửa và xuất. Mục ghi âm trong ứng dụng cũng cho phép bạn ghi lại giọng nói trước khi phiên âm. Để tạo file ghi âm độc lập mà không phiên âm, dùng phần mềm ghi âm miễn phí.

Phiên âm video tự động dùng cùng quy trình văn bản sau khi ứng dụng trích xuất hoặc chuyển đổi âm thanh ngay trên thiết bị. Ví dụ tải lên qua REST bên dưới bắt đầu với âm thanh đã chuẩn bị; để đưa file video trên thiết bị vào ứng dụng, dùng quy trình trên trình duyệt tại chuyển video thành văn bản.

Tôi có thể thử chuyển thành văn bản tự động miễn phí không?

Có. Bản xem trước công khai phiên âm tối đa năm phút từ một file, liên kết âm thanh được hỗ trợ hoặc bản ghi trong trình duyệt trước khi đăng nhập; video trên thiết bị cũng dùng được sau khi trình duyệt chuẩn bị âm thanh. Phiên âm toàn bộ cần tài khoản: tài khoản cá nhân đủ điều kiện nhận 30 phút miễn phí sau khi xác minh thẻ (xem bảng giá để biết cách thực hiện), còn tài khoản máy không nhận phút chào mừng và bắt đầu với gói mua khi đăng ký.

Tự động hóa bản phiên âm bằng API hoặc MCP

Ứng dụng trên trình duyệt dành cho việc thao tác trực tiếp với bản ghi. Để tự động hóa bản phiên âm, REST API và máy chủ MCP cho phép agent tải lên âm thanh đã chuẩn bị, kiểm tra tác vụ, lấy bản phiên âm và xuất kết quả. Agent có thể mở tài khoản riêng bằng quy trình thanh toán trước, không cần người đứng tên tài khoản; trang thanh toán vẫn cần trình duyệt và ngân hàng phát hành thẻ có thể yêu cầu bước xác thực. Người dùng cũng có thể tạo token với phạm vi quyền cụ thể từ tài khoản hiện có trong ứng dụng. Hướng dẫn này theo dõi tài khoản máy từ đăng ký đến xoay vòng thông tin xác thực.

Đăng ký

POST /v1/agent/accounts mở một lượt đăng ký không cần giao diện (headless). Chưa có tài khoản nào, chưa có cookie, và chưa có token nào: chỉ có một giao dịch mua đang chờ xử lý.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-10-20",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email chỉ dùng để nhận biên lai và thông báo, không bao giờ dùng để đăng nhập. pack_id là một trong các giá trị 45min, 300min, 900min, 1800min, 6000min; đừng bao giờ tự gửi amount hay currency; máy chủ xác định cả hai từ gói. Chỉ hai gói nhỏ nhất, 45min và 300min, mới có thể mua ngay khi đăng ký. Một pack_id lớn hơn sẽ bị từ chối, và phản hồi từ chối đó mang theo details.allowed_packs liệt kê những gì tài khoản này có thể mua ngay lúc này, để bên gọi có thể thử lại mà không cần đoán. Phần còn lại của bậc thang gói mở khóa theo thời gian, không theo khối lượng: xem Tài khoản mới có thể mua gì bên dưới. accept_terms_version phải khớp chính xác với phiên bản chính sách hiện tại của máy chủ, nếu không lệnh gọi sẽ thất bại với policy_version_stale, lỗi này nêu rõ giá trị hiện tại trong nội dung phản hồi. Gợi ý data_region (tùy chọn) chỉ được chấp nhận khi nó khớp với khu vực mà vị trí mạng của bạn đã xác định. dry_run: true (tùy chọn) xác thực mọi thứ mà không tạo phiên Stripe và không tính phí; signup_id của nó có tiền tố dry_ và không bao giờ có thể được xác nhận.

claim_secret chỉ được hiển thị đúng một lần, trong phản hồi này. Hushscript chỉ lưu giá trị băm của nó. Nếu mất nó trước khi gọi lệnh xác nhận, bạn mất lượt đăng ký: không có cách khôi phục bí mật xác nhận. Lượt đăng ký đã thanh toán nhưng chưa xác nhận sẽ được đưa vào quy trình hoàn tiền bên dưới; không thể khôi phục qua thao tác tra cứu.

Hoàn tất thanh toán trong trình duyệt của bạn

checkout_url là trang thanh toán do Stripe Checkout lưu trữ. Bước này cần trình duyệt, nhưng không nhất thiết phải do người dùng điều khiển: agent có thể tự thao tác bằng cơ chế tự động hóa của mình (điền thông tin thẻ, gửi và theo đường dẫn chuyển hướng). Dù theo cách nào, Hushscript cũng không bao giờ thấy chi tiết thẻ; Stripe mới là bên thấy. Thời hạn để hoàn tất bước này rồi xác nhận là 30 phút, chính là expires_at ở trên.

Một đợt quét chạy mỗi giờ kiểm tra các lượt đăng ký đã thanh toán nhưng chưa xác nhận sau cửa sổ xác nhận 30 phút và một giờ gia hạn bổ sung. Đợt quét thử hoàn tiền toàn bộ, vì số phút chỉ được ghi có khi xác nhận. Các lần hoàn tiền thất bại được thử lại và có thể cần xử lý thủ công; không có bảo đảm khoản hoàn tiền sẽ đến vào một thời điểm cụ thể.

Xác nhận tài khoản

POST /v1/agent/accounts/{signup_id}/claim biến một lượt đăng ký đã thanh toán nhưng chưa xác nhận thành một tài khoản thật sự, chỉ trong một lệnh gọi.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

Việc xác nhận tạo ra đúng một tài khoản, với danh tính đăng nhập được tạo tự động, không thể phân giải, và cấp đúng một lần gói đã thanh toán, dù lệnh gọi có bị thử lại bao nhiêu lần. Nó tạo ra một PAT: giá trị pat ở trên.

Nếu phản hồi bị mất, hãy gọi lại với cùng claim_secret. Trong vòng một giờ kể từ lúc xác nhận, và khi token đã cấp chưa từng được dùng, lệnh thử lại trả về 201 cho cùng tài khoản với cùng cấu trúc phản hồi và một pat mới. Token bị mất ngừng hoạt động. Sau lần dùng đầu tiên của token, hoặc sau một giờ đó, lệnh thử lại trả về agent_claim_invalid. Một lệnh thử lại trùng với lượt xác nhận vẫn đang chạy có thể nhận 429 rate_limited kèm header Retry-After; hãy thử lại sau khoảng chờ đó.

Token đầu tiên đó có thể phiên âm, đọc và chỉnh sửa bản phiên âm, xuất, đọc số dư tài khoản, mua phút và tự xoay vòng. Nó không cấp các scope Insights, ngữ cảnh, tổ chức hay ghi cài đặt. Máy chủ MCP chỉ cung cấp công cụ nằm trong phạm vi quyền của token.

Một bí mật xác nhận sai, một signup_id không tồn tại, một lượt đăng ký đã hoàn tiền, một lượt đã hết hạn, và một lần xác nhận lặp lại mà token đã được dùng hoặc đã quá một giờ đều trả về cùng một lỗi agent_claim_invalid. Bên gọi không có cách nào phân biệt các trường hợp đó từ phản hồi, đây là chủ ý. Chỉ khi bí mật xác nhận là đúng thì trạng thái thanh toán mới được xét đến: một Checkout Session chưa được quyết toán sẽ trả về wrong_state thay vào đó.

balance_seconds ở trên là toàn bộ số dư khởi điểm. Tài khoản agent không nhận được khoản thưởng chào mừng nào và không có phút miễn phí nào từ việc xác minh thẻ như tài khoản đầu tiên của một con người; chúng chỉ bắt đầu với đúng gói đã thanh toán, không hơn. Đây là chủ ý, không phải một khoảng thiếu sót: tài khoản đã được thanh toán trước khi nó tồn tại.

Mua thêm phút

Từ đây trở đi, tài khoản này hoạt động như bất kỳ tài khoản nào khác, qua giao diện /v1/ được mô tả đầy đủ tại /developers.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Lệnh này cần scope billing, đã được cấp trong phản hồi xác nhận ở trên. Việc xác nhận cũng bật quyền thanh toán cho token và tài khoản; token do người dùng tạo cần scope billing và cả hai công tắc thanh toán đều được bật. Các lệnh thanh toán bằng PAT dùng chung giới hạn chặt hơn là 60 yêu cầu mỗi phút cho mỗi tài khoản trên các route thanh toán gọi Stripe, trước khi thực hiện yêu cầu đến Stripe.

Tài khoản mới có thể mua gì

Quy mô gói được mở khóa theo thời gian từ khi thanh toán hoàn tất, không theo số tiền tài khoản đã chi. Một giao dịch mua chỉ được tính vào bậc tiếp theo khi nó đã qua 7 ngày kể từ ngày thanh toán của chính nó, vì vậy một tài khoản hoàn toàn mới không thể chạm tới các gói lớn bằng cách mua thật nhanh.

Một giao dịch mua bị từ chối sẽ nêu rõ tập hợp hiện tại trong details.allowed_packs thay vì thất bại một cách mù mờ. Lệnh gọi đăng ký áp dụng đúng hàng đầu tiên của bảng đó, đó là lý do vì sao hướng dẫn ở trên mua 300min chứ không phải một gói lớn hơn. Tách biệt với bậc thang này, giới hạn tiêu hao trong mỗi khoảng 24 giờ liên tục hạn chế tốc độ sử dụng số dư chưa qua khỏi cửa sổ tranh chấp. Giao dịch mua khi đăng ký được tính vào giới hạn ba lần thử mua trong mỗi khoảng 24 giờ liên tục của tài khoản; các lần thử bị từ chối sau bước giữ chỗ cũng được tính.

Chuyển thành văn bản

Tải lên và phiên âm dùng cùng luồng nhiều phần (multipart) như bất kỳ tài khoản nào khác. Ví dụ API gửi âm thanh đã chuẩn bị; nó không tải lên file video gốc trên thiết bị.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

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

PUT từng phần lên URL đã ký sẵn (presigned) của nó, sau đó POST tới /complete của cùng tác vụ đó kèm n và etag của mỗi phần đã gửi theo cách đó. Sau đó, kiểm tra trạng thái tác vụ định kỳ:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

Xoay vòng token

Một tài khoản máy không có mật khẩu và không có hộp thư dùng được, nên không có đường dẫn kiểu “quên mật khẩu” nếu một PAT bị lộ hoặc chỉ đơn giản là cần thay thế. Xoay vòng chính là đường dẫn đó.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

Lệnh gọi này không cần nội dung (body). Nó tạo ra token kế nhiệm cho token đã xác thực yêu cầu. Token kế nhiệm giữ nguyên scope, quyền thanh toán, tên, nhãn client và chính sách hết hạn của token trước đó. Route này chỉ chạm vào token của chính bên gọi: nó không thể liệt kê, tạo, hay thu hồi bất kỳ thông tin xác thực nào khác trên tài khoản. Đây là đường dẫn khôi phục thông tin xác thực duy nhất mà một tài khoản máy có, vì vậy hãy xoay vòng trước khi token cũ bị loại bỏ, không phải sau đó.

Token cũ không bị thu hồi ngay. Sau khi xoay vòng, nó chỉ dùng được cho một việc: gọi xoay vòng lần nữa. Điều đó kéo dài đến khi token mới thực hiện yêu cầu thành công đầu tiên hoặc đến khi qua một giờ, tùy mốc nào đến trước. Trên mọi route khác, token cũ trả về 401 ngay lập tức.

Nếu phản hồi mang token mới bị mất, hãy gọi xoay vòng lại bằng token cũ khi token mới chưa được dùng. Bạn nhận được một bí mật mới cho cùng pat_id, và bí mật mới trước đó ngừng hoạt động.

Hãy giữ token cũ cho đến khi token mới đã hoạt động một lần. Sau đó thực hiện ngay một lệnh gọi bằng token mới, chẳng hạn GET /v1/account. Yêu cầu thành công đầu tiên đó sẽ vô hiệu hóa token cũ vĩnh viễn.

Lỗi

Các lỗi này áp dụng cho các biện pháp kiểm soát đăng ký và mua gói của agent. Giới hạn mua cũng áp dụng cho giao dịch mua bằng PAT trên tài khoản của người dùng; giao dịch mua qua phiên đăng nhập của người dùng được miễn.

Khi bí mật xác nhận đã hợp lệ, một Checkout Session chưa thanh toán sẽ trả về wrong_state (4001) thay vì agent_claim_invalid. Danh mục đầy đủ nằm trong tài liệu OpenAPI.

Giới hạn

Các lệnh gọi bị giới hạn ở 1.200 lệnh mỗi phút. Với tài khoản agent, hạn mức thuộc về tài khoản, không phải từng token: mọi thông tin xác thực trong chuỗi xoay vòng dùng chung hạn mức, nên xoay vòng PAT không cấp hạn mức mới cho token kế nhiệm. Các lệnh thanh toán bằng PAT gọi Stripe dùng chung giới hạn chặt hơn là 60 lệnh mỗi phút cho mỗi tài khoản. Giới hạn này bao gồm thiết lập và mua gói, đổi hoặc xóa thẻ mặc định, cùng các lần lấy danh sách thẻ không có dữ liệu trong bộ nhớ đệm; việc kiểm tra diễn ra trước lệnh gọi Stripe. Giới hạn mua trong 24 giờ ở trên cũng được tính theo tài khoản, không phải từng thông tin xác thực.

Tìm hiểu thêm

Trang này trình bày vòng đời của tài khoản: mở một tài khoản, nạp tiền cho nó, và giữ cho thông tin xác thực của nó luôn còn hiệu lực. Để biết mọi việc tài khoản đó có thể làm tiếp theo, xem REST API, bao gồm toàn bộ tài liệu OpenAPI, hoặc máy chủ MCP cho cùng tài khoản đó qua các công cụ thay vì HTTP trực tiếp.