錄音語音轉文字 API

Hushscript 語音轉文字 API 透過 /v1/ 接受錄音，讓您的腳本查詢工作並讀取逐字稿。這是線上轉錄工作流程，並非即時串流或直接呼叫語音辨識模型的端點。如果您的用戶端偏好工具而非 HTTP 呼叫，MCP 伺服器使用相同的帳戶、餘額與持有者權杖。

透過 API 把音訊與影片轉成逐字稿

音訊轉錄 API 接受準備好的音訊檔案，包括錄製的語音。進行 STT（語音轉文字）整合時，請提交錄音檔案；不支援麥克風即時串流。若要轉錄影片，請直接上傳帶有音軌的 MP4 或 MOV 檔案：伺服器會讀取音軌並略過影像。其他影片格式請先擷取音訊；API 不接受影片網址。瀏覽器工作流程請見影片轉文字。

快速入門

這個 API 需要一個個人存取權杖，取得方式有兩種。一種是由個人使用者在帳戶中的 MCP 頁面的 建立新的權杖 區段建立權杖，選擇其權限範圍，並決定它是否可以購買分鐘數。另一種是由代理程式自行開設帳戶，無需人類帳戶持有人：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": 50,
    "max_daily_seconds": 144000,
    "active_jobs": 0,
    "used_today_seconds": 0
  }
}

這會回傳以秒為單位的餘額、正在執行工作所暫扣的秒數、credits_expire_at（分鐘數不會過期，因此一律為 null）、是否已儲存卡片、資料所在地區，以及受理上限（max_active_jobs、max_daily_seconds，及其目前用量）。每日上限是帳戶目前的有效上限，請勿寫死在程式碼中。POST /v1/uploads 檢查的是可用分鐘數，而不是卡片：分鐘數不足時會回傳 3001 insufficient_balance。

語音轉文字 API 是否免費？

沒有通用的免費 API 方案，但您可以在撰寫程式碼前先試用工作流程：公開預覽可在登入前，從一段錄音轉錄最長五分鐘。符合資格的個人帳戶在卡片驗證後，可獲得 30 分鐘免費額度（運作方式請見定價）；由代理程式建立的帳戶沒有歡迎分鐘，而是以註冊時購買的套餐開始使用。無論哪種帳戶，完整 API 工作都需要帳戶與分鐘數。

端到端自動化

相同的 /v1/ 呼叫，無論是使用由人在應用程式中建立的權杖，或是由代理程式在付費註冊後領取的權杖，都能運作（見自動化使用）。儲存卡片需要在瀏覽器中完成託管的 Checkout，代理程式可以自行操作；之後在非工作階段中發起的購買，若發卡機構要求驗證，仍可能被拒絕。

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、matter_code， 以及 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 是最多 64 字元的自由文字，只有在權杖屬於某個工作區時才有 意義：它會隨該工作的紀錄，顯示於該工作區的時數池活動記錄與用量報表中。若工作區的 案件代碼政策設為必填，未附上代碼的上傳請求會被 org_matter_code_required 拒絕。client_code 會被接受但忽略，因為客戶是案件的屬性，由工作區管理員設定。

   它會暫扣分鐘額度，並回傳一個 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、mp4 或 mov（使用音軌，略過影像軌）、wav、flac、ogg 或 opus， 並由伺服器探測格式；其他影片格式請在上傳前先擷取音訊。

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，以及已儲存的 dictionary_ids 與 prompt_preset_id，可透過 GET /v1/transcription-context 列出。

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

身分驗證

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

超出權杖權限範圍的呼叫，會以 403 回應 pat_scope_missing。billing 權限範圍在權杖與帳戶都啟用帳務功能之前也不會生效；任一開關關閉時呼叫帳務端點，同樣會失敗並回傳 pat_scope_missing，重新產生權杖也無法開啟帳戶端的開關。權杖無法建立、列出或撤銷權杖，一個帳戶最多可持有 25 個有效權杖。

這 11 個權限範圍可由呼叫端自行選擇。pat:rotate 是另一個獨立的權限範圍，會授予代理程式帳戶的第一個權杖及其輪替後的後繼權杖；它允許該權杖替換自己，但不能管理其他權杖。在應用程式中建立權杖時無法選擇它。

端點

正式版 OpenAPI 文件列出 38 個方法／路徑操作，涵蓋 37 個路徑。以下每個操作都受所示權限範圍限制：

/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 伺服器會以 56 個工具取代這些端點，操作的是同一個帳戶。它只會提供已連接權杖的權限範圍所允許的工具。

限制

以人類帳戶的權杖發出的請求，每個權杖限制為每分鐘 1,200 次。代理程式帳戶輪替後的權杖在整個帳戶內共用此額度。呼叫 Stripe 的帳務路由對 PAT 呼叫端共用一個更嚴格的額度，每個帳戶每分鐘 60 次：設定工作階段、購買、切換預設卡片、移除卡片，以及卡片清單的快取未命中。一般節流會以 429 rate_limited 回應，並附上以秒為單位的 Retry-After 標頭；請等待該時間後再重試。代理程式帳戶的購買，或人類帳戶以 PAT 發起的購買，共用每個帳戶在滾動 24 小時內最多 3 次嘗試的上限。代理程式的註冊購買也計入；保留額度後遭拒或出錯的嘗試同樣計入。由人在瀏覽器工作階段中發起的購買不受此限。因上限而被拒絕時，會以 HTTP 429 回應 4038 agent_purchase_capped 與 Retry-After。錄音長度可為 15 秒至 10 小時。GET /v1/account 會回報帳戶目前的受理上限（max_active_jobs、max_daily_seconds）。

沙盒

沒有通用的轉錄沙盒：一般的 /v1/ 呼叫都會作用於真實帳戶，購買會花費真實金錢。例外是註冊驗證：POST /v1/agent/accounts 接受 dry_run: true，會回傳無法領取的 dry_ 註冊 id，且不會開啟 Stripe 工作階段或帳戶。

錯誤

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

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