API 概覽
從您自己的應用程式調用 Speechdash，並創建授權該應用程式的 API 金鑰。
Speechdash API 讓您的應用程式能夠創建文件並使用與應用程式相同的語音進行語音合成。您透過 API 創建的所有內容也會出現在您的圖書館中。在應用程式中完成的音頻和視頻轉寫文件也會作為圖書館文件顯示（source 是 transcription，並帶有 transcript_id）。沒有 /transcripts REST 資源：請使用文件端點。API 不會啟動轉寫工作。
基礎 URL：
https://api.speechdash.com/v1健康檢查（無需 API 金鑰）：GET https://api.speechdash.com/health
機器可讀的合約已發佈在 https://api.speechdash.com/v1/openapi.json，因此您可以為您的語言生成客戶端。
端點
| 方法 | 路徑 | 用途 |
|---|---|---|
GET | /health | 服務健康狀態（不在 /v1 下） |
GET | /v1/openapi.json | OpenAPI 3.1 文件 |
GET | /v1/me | 帳戶、計劃和錢包 |
GET | /v1/documents | 列出圖書館文件，包括完成的轉寫 |
POST | /v1/documents | 創建一個文字文件（source=api） |
GET | /v1/documents/{document_id} | 讀取文件及其文字內容 |
PUT | /v1/documents/{document_id} | 更新標題、文字、語言、is_archived 或 visibility |
DELETE | /v1/documents/{document_id} | 刪除文件 |
POST | /v1/documents/{document_id}/translate | 新的翻譯版本（與 MP3 導出相同的信用額度） |
GET | /v1/documents/{document_id}/export | 下載 pdf、docx、txt、csv、srt 或 vtt |
POST | /v1/audio/speech | 合成最多 5,000 個字元（JSON + 音頻） |
POST | /v1/audio/stream | 流式傳輸 WAV，最多 20,000 個字元 |
POST | /v1/audio/stream/with-timestamps | SSE 具有每句音頻和標記 |
GET | /v1/voices | 語音目錄 |
GET | /v1/voices/{voice_id} | 一個語音預設值 |
MCP 伺服器（用於 AI 助手）
如果您使用 Cursor、Claude Desktop 或其他 MCP 客戶端，您可以新增官方 Speechdash MCP 伺服器，而不是直接呼叫 HTTP。它提供與本指南相同的 API 金鑰和計費的工具，包括圖書館（包含完成的轉寫）、翻譯、導出、語音、帳戶快照，以及非流式語音合成。流式語音合成仍使用 REST。
請參閱 MCP 伺服器 以獲取完整的工具清單和設定（stdio 或 Streamable HTTP）。您也可以閱讀 Agents 中心 在行銷網站上針對 AI 系統設計的機器可讀文檔。端用戶可以從 API 金鑰和 MCP 此幫助中心開始。
創建 API 金鑰
開啟 設定 → API。
點擊 新增金鑰，並為其命名，說明它將被用於哪裡，例如 Production 伺服器。
立即複製金鑰。僅儲存其前綴，因此它只會顯示一次，之後永不再現。
一個金鑰會影響您的帳戶。請將其放在伺服器上，永遠不要放在瀏覽器、行動應用程式或公共儲存庫中。如果金鑰泄漏，請從 設定 → API 撤銷其權限，並創建一個新的。
您可以保留最多 10 個活動金鑰，隨時更改其名稱，並查看每個金鑰上次使用的時間。撤銷一個金鑰會立即停止其請求。
驗證請求
將金鑰作為 Bearer 令牌傳送：
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"沒有有效金鑰的請求會回應 401 並帶有代碼 unauthorized。
GET /me 會返回您的帳戶 ID、電子郵件、計劃和錢包餘額（wallet_cents 和 display_credits），以及關於使用的 API 金鑰的額外元數據。您可以用它來在設定後驗證金鑰（例如在 Zapier 中）。
POST /documents 和 POST /audio/speech 接受一個可選的 Idempotency-Key 標頭。重試相同的金鑰和相同的內容會在 24 小時內重播第一次成功的回應，因此網路暫時中斷不會創建第二個文件或重複計費語音。如果語音回應太大無法儲存，重試相同的金鑰會回應 409 而不是重新產生（原始請求已經計費）。/audio/speech 的客戶端斷開連接會回應 204，結算已產生的任何音頻，並釋放金鑰，以便重試可以重新產生。流式音頻端點會拒絕此標頭。
信用額度
語音合成會從與應用程式相同的錢包中消耗信用額度：**0.5 個信用額度（1 個錢包分）**每開始 30 秒的合成音頻。每個請求在開始合成前會持有一個估計值（加上一個小幅度），然後會結算為實際產生的音頻。未使用的持有額度會退款；每個結算請求會在 設定 → 信用額度使用 中顯示為 API 語音合成。API 回應中的 billed_credits 字段是錢包分（2 分 = 1 個顯示信用額度）。如果流式傳輸在中途中斷，已傳送的句子仍然會計費。
如果您的餘額不足以覆蓋持有額度，API 會在開始生成任何內容前回應 402 並帶有代碼 payment_required。
創建文件不會消耗信用額度，但它會計入您計劃的每日文件上限（免費： 每天 3 個；Unlimited：無每日上限）和上傳時長限制。文件導出不會消耗信用額度。
計費與應用程式內雲端重播
應用程式內 雲端 重播會重複使用每文件的句子快取：重播已在伺服器上生成的句子可能只需要 0 個顯示信用額度。REST 和 MCP 語音端點總是會合成新的音頻並按每開始 30 秒的相同速率計費。在生成時，API 或 MCP 合成沒有重播快取。
限制
| 限制 | 值 |
|---|---|
到 /documents 的請求 | 每分鐘每帳戶 120 個 |
到 /audio/* 的請求 | 每分鐘每帳戶 60 個 |
| 平行語音請求 | 每帳戶 3 個 |
POST /audio/speech input | 5,000 個字元 |
POST /audio/stream input | 20,000 個字元 |
| 文件文字 | 500,000 個字元 |
| 活動 API 金鑰 | 10 個 |
速率限制是按帳戶計算的，不是按金鑰計算的，因此額外的金鑰不會提高您的配額。每個回應都會帶有 X-Request-ID，而 /documents 和 /audio/* 也會返回 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。當您聯繫支援時，請引用 X-Request-ID。
語音請求也有平行度限制：第四個同時請求在前三個仍在運行時會回應 429，因此一個整合不能獨佔合成。請重試 429 和 503 並等待 Retry-After 標頭。
對於超過語音限制的內容，請使用 POST /v1/documents 創建一個文件，並從應用程式導出其音頻。
文件：分享、翻譯、導出
序列化的文件包含 visibility 和 share_url（當文件為私有時為 null）。PUT /v1/documents/{id} 接受 visibility 以發佈一個只讀頁面 /share/document/{id}，並接受 is_archived 以歸檔或還原。分享的頁面僅為文字內容。它們不會播放計費的音頻。
POST /v1/documents/{id}/translate 創建一個新的翻譯版本。它會按與 MP3 導出相同的信用額度計費（每開始 30 秒的估計語音 0.5 個信用額度），並在錢包不足時回應 402。當翻譯未配置或停止時，它會回應 503。
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt 會下載當前版本作為附件。添加 timestamps=1 以在 PDF、DOCX、TXT 和 CSV 中包含節時。SRT 和 VTT 需要轉寫或完整的句子時標。儲存的 text 在 GET /v1/documents/{id} 上保留轉寫時標標頭。隱藏它們是應用程式閱讀器的開關選項。