自動化使用

開設 Hushscript 帳戶過去至少需要一個人親自參與，如今情況不再如此。一套以付款為優先的流程，讓代理程式能自行開設帳戶、為帳戶儲值並運行帳戶，整個流程完全不需要任何人類帳戶擁有者。/developers 與 /mcp 記載了此帳戶接下來會使用的兩種介面；本頁則說明如何取得這樣一個帳戶。

註冊

POST /v1/agent/accounts 會開啟一次無人值守的註冊。此時尚無帳戶、無 Cookie，也無權杖，只有一筆待處理的購買。

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-08-01",
    "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 僅用於收據與通知，絕不作為登入方式。pack_id 必須是 45min、300min、900min、1800min、6000min 其中之一；切勿自行傳送 amount 或 currency，兩者都由伺服器依套餐自動推算。註冊時只能購買兩個最小的套餐，45min 與 300min。指定較大的 pack_id 會遭拒絕，拒絕回應會附上 details.allowed_packs，列出此帳戶目前可以購買的項目，讓呼叫端無須猜測即可重試。其餘等級則隨帳戶年齡解鎖，而非隨消費量解鎖，詳見下方的新帳戶可購買的內容。 accept_terms_version 必須與伺服器目前的政策版本完全一致，否則呼叫會以 policy_version_stale 失敗，並在回應內容中指出目前的版本值。選填的 data_region 提示，只有在與您網路位置已隱含的區域一致時才會被採用。選填的 dry_run: true 會驗證所有內容，但不會建立 Stripe 工作階段，也不會產生任何收費；其 signup_id 會以 dry_ 開頭，且永遠無法被認領。

claim_secret 只會在此回應中顯示一次，Hushscript 僅儲存其雜湊值。若在呼叫認領之前遺失它，就等於失去這次註冊：claim_secret 沒有任何復原途徑，而託管中的款項會由下方描述的排程掃描自動退還，而不是透過查詢取回。

在您自己的瀏覽器中完成 Checkout

checkout_url 是一個託管的 Stripe Checkout 頁面。這是整個流程中唯一需要瀏覽器的步驟，而且不必是人類使用的瀏覽器：代理程式可以用自己的自動化工具操作它（填入卡片欄位、送出、跟隨重新導向）。無論如何，Hushscript 都不會看到卡片明細，Stripe 才會。完成此步驟並接著認領的時限是 30 分鐘，也就是上方的 expires_at。

已付款但從未被認領的註冊，會在該 30 分鐘時限結束後大約一小時，由每小時執行一次的排程掃描自動退款。退款是全額的，因為分鐘數只會在認領時才會計入餘額，所以未被認領的註冊從一開始就沒有任何分鐘數可以消耗。

認領帳戶

POST /v1/agent/accounts/{signup_id}/claim 會在一次呼叫中，將已付款但尚未認領的註冊轉為真正的帳戶。

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
}

認領動作只能使用一次。它會建立恰好一個帳戶，背後對應一個合成且無法反查的登入身分，即使請求被重試，也只會授予一次已付款的套餐，並且只會產生一個 PAT：也就是上方的 pat 值，同樣只會顯示一次。

無論是密鑰錯誤、signup_id 不存在、註冊已被認領、已退款，或已過期，都會回傳同一個 agent_claim_invalid 錯誤。呼叫端無法從回應內容分辨究竟是哪一種情況，這是刻意的設計。只有在密鑰本身驗證通過之後，付款狀態才會被納入考量：尚未結算的 Checkout Session 會改為回傳 wrong_state。

上方的 balance_seconds 就是全部的起始餘額。代理程式帳戶不會像一般人的首個帳戶那樣獲得歡迎獎勵，也不會因卡片驗證而取得免費分鐘數；帳戶一開始只有已付款的那個套餐，別無其他。這是刻意的設計，而不是缺漏：這個帳戶在存在之前就已經付過款了。

購買更多分鐘數

從這裡開始，這個帳戶的運作方式就與其他帳戶完全相同，走的是同一組 /v1/ 介面，/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
}

這需要 billing 範圍，上方的認領回應已經授予了這項權限；此路由與儲存卡片的路由共用每個帳戶每分鐘 60 次請求的較嚴格限制，在各自呼叫 Stripe 之前就先受此限制。

新帳戶可購買的內容

套餐大小的解鎖依據是已結算款項的存續時間，而不是帳戶花費的金額。一筆購買要等到超過其付款日期 7 天 之後，才會計入下一個等級，因此全新的帳戶無法靠快速購買就達到較大的套餐。

遭拒絕的購買會在 details.allowed_packs 中列出目前允許的組合，而不是毫無說明地失敗。註冊呼叫套用的是這張表的第一列，這也是為什麼上方的示範購買的是 300min 而不是更大的套餐。與等級制度分開的是，一個滾動 24 小時的消耗上限，限制了尚未超過爭議期限的餘額能被花費的速度。

轉錄

上傳與轉錄的流程，與其他任何帳戶所使用的分段（multipart）流程完全相同。

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 將每個分段上傳至各自的預先簽署網址，再以 POST 呼叫同一工作的 /complete，並附上以此方式送出的每個分段的 n 與 etag。接著輪詢該工作：

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": "..."
}

輪替權杖

機器帳戶沒有密碼，也沒有可用的信箱，因此當 PAT 外洩或只是單純需要更換時，並不存在「忘記密碼」這條路徑。輪替就是這條路徑。

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
}

此呼叫不需要任何請求主體。它會以原子方式產生一個後繼權杖，並撤銷用來驗證此次請求的權杖，因此舊的 PAT 會在下一次呼叫時立即失效。後繼權杖會保留前一個權杖的範圍、購買權限、名稱、用戶端標籤與到期政策。此路由只會影響呼叫端自己的權杖：無法列出、產生或撤銷帳戶上的任何其他權杖。這是機器帳戶唯一的憑證復原途徑，因此請在捨棄舊權杖之前先完成輪替，而不是之後。

錯誤

以下四項僅適用於代理程式帳戶，人類帳戶絕不會遇到：

一旦密鑰本身驗證通過，尚未付款的 Checkout Session 會回傳 wrong_state（4001），而不是 agent_claim_invalid。完整目錄請見 OpenAPI 文件。

限制

呼叫次數限制為每分鐘 1,200 次。對代理程式帳戶而言，這個額度屬於整個帳戶，而不是個別的權杖：輪替譜系中的每一個權杖都共用同一份額度，因此輪替 PAT 並不會為後繼權杖帶來全新的額度。兩項與購買相關的寫入操作，也就是儲存卡片與購買套餐，共用每個帳戶每分鐘 60 次的較嚴格限制，在各自呼叫 Stripe 之前就先受此限制。上方提到的 24 小時購買上限，同樣是以帳戶為單位計算，而不是以權杖為單位。

深入了解

本頁涵蓋的是帳戶的生命週期：開設帳戶、為帳戶儲值，以及維持其權杖的有效性。至於這個帳戶接下來能做的所有事情，請見 REST API（包含完整的 OpenAPI 文件），或改用 MCP 伺服器，以工具而非原始 HTTP 的方式操作同一個帳戶。