Hushscript 開發者 API

對於偏好直接呼叫 HTTP 端點、而非執行 MCP 用戶端的代理程式與腳本，Hushscript 同樣也能回應純粹的 REST 呼叫。從頭到尾都是同一個帳戶、同一份餘額、同一組持有者權杖：這裡的一切都不會改變轉錄的計價或儲存方式。

快速入門

這個 API 需要一個個人存取權杖，取得方式有兩種。一種是由某個人在帳戶中的 MCP 頁面的**權杖（Tokens）**底下建立一個權杖，選擇其範圍，並決定它是否可以購買分鐘數。另一種是由代理程式自行開設帳戶，全程無人參與：POST /v1/agent/accounts 會啟動一次付費註冊，POST /v1/agent/accounts/{signup_id}/claim 則以一次性的認領密鑰換取一個真正的帳戶與第一個權杖。無論哪一種方式，權杖都只會顯示一次，格式為 hsr1:<region>:pat.<id>.<secret>。透過 MCP 伺服器的 OAuth 登入所產生的權杖，在這裡同樣適用；詳見連接。權杖永遠無法建立、列出或撤銷其他權杖，一個帳戶最多可持有 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"
   }

   在您自己控制的瀏覽器中開啟這個網址，完成託管的 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，會在離線情境下向卡片扣款，並回傳新的 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 以及第一頁已預先簽署的分段網址：

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

   以 PUT 將每個分段上傳至各自的網址（預設每個分段 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> 取得，長時間傳輸時， 請在 20 分鐘閒置逾時之內盡早呼叫 POST /v1/uploads/{job}/heartbeat。當預先 簽署的網址無法使用，或某個分段失敗時，可改用 PUT /v1/uploads/{job}/parts/{n} 透過 API 直接送出該分段的位元組；重複 PUT 會取代該分段，因此重試是安全的。 僅接受音訊：mp3、m4a、wav、flac、ogg 或 opus，上限 5 GB，並由伺服器探測格式； 上傳前請先從影片中擷取音軌。

5. 開始並等待。 POST /v1/uploads/{job}/complete 搭配每個透過預先簽署網址 送出的分段的 n 與 etag（若所有分段都透過 API 送出，則省略 parts）：

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

   接著輪詢 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，以及 GET /v1/transcription-context 所列出、已儲存的 dictionary_ids 與 prompt_preset_id。

帳戶的部分功能目前仍僅限於 MCP：以連結匯入、編輯或刪除逐字稿、Insights、匯出、 儲存詞典與提示詞預設，以及帳戶設定，目前都還沒有對應的 /v1/ 路由；MCP 伺服器則以同一個權杖涵蓋所有這些功能。

身分驗證

每一次 /v1/ 呼叫都會在 Authorization 標頭中帶有持有者權杖，並依照與 MCP 伺服器相同的範圍進行檢查：

超出權杖範圍的呼叫，會以 403 回應 pat_scope_missing。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 文件：請以它為準，優先於 本表。它會提供給任何持有者權杖，不論範圍為何，因此用戶端可以直接用手上既有 的憑證取得它。

MCP 介面

比起原始 HTTP，更偏好工具介面嗎？對於已經使用 MCP 而非 REST 的用戶端， MCP 伺服器會以 51 個工具取代這些端點，操作的是同一個帳戶。

限制

以權杖發出的請求，每個權杖限制為每分鐘 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/ 呼叫都會作用於真實帳戶，購買分鐘數也 會花費真實金錢。

錯誤

錯誤是一個帶有固定數字 code 與 error 代稱的 JSON 主體，搭配下表所示的 HTTP 狀態碼。/v1/ 的錯誤主體是一個凍結的投影：error、code，以及一組 固定的詳細資訊欄位。/api 的錯誤結構則未凍結，可能帶有更多欄位。自動化呼 叫端必須處理的代碼如下：

OpenAPI 文件列出了每個操作可能回傳的確切代碼，MCP 伺服器則以 hushscript://error-codes 資源發布完整目錄。