VoiceStudio 是做什麼的？
使用使用者正在運行的 VoiceStudio 後端。優先進行本地處理；遠端工作者、雲端翻譯、模型下載和外部整合需要使用者選擇。已安裝的模型可以離線運行；請不要保證每個配置的工作流程都是離線的。
連接與探索
預設後端地址為 http://localhost:3900；請尊重使用者配置的位址。Electron 的渲染器與開發代理伺服器是獨立的服務，不是公開的後端 API。
- 檢查
GET /health。 - 使用
GET /openapi.json探索運行中版本的合約，並使用GET /v1/audio/voices探索語音/引擎。請不要憑空發明設定檔 ID，或根據目錄列表推斷已安裝的模型。 - 如果服務不可用，則啟動已安裝的應用程式。對於已存在的原始碼檢查副本，請遵循其 Electron README（在倉庫根目錄執行
bun install、bun run setup:api，然後bun run dev）。請不要安裝第二個後端或覆蓋現有的檢查副本。 - 本地配置可能允許未經驗證的呼叫；受保護的部署需要已配置的憑證。將 401/403 視為驗證失敗，而不是允許停用驗證的權限。永遠不要輸出令牌，也不要將預留金鑰當作真實的憑證來使用。
產生語音
將此 JSON 儲存為 speech-request.json，並在使用者選擇語音後，將 voice 替換為已發現的設定檔 ID：
{"model":"tts-1","voice":"alloy","input":"Every voice has a story. Let's tell yours.","response_format":"wav"}
curl --fail-with-body --show-error http://localhost:3900/v1/audio/speech \
-H 'Content-Type: application/json' --data-binary @speech-request.json \
--output speech.wav
tts-1 和 tts-1-hd 是別名，並非品質保證。OpenAI 語音名稱是相容性別名，並非那些提供者的實際語音。偏好使用已發現的已儲存語音來進行可重複的旁白。在承諾結果之前，請檢查已安裝引擎的語言和語音設計能力。
在將其稱為音訊之前，請檢查 HTTP 狀態並解碼/探測輸出：錯誤回應可能會寫入到輸出路徑。請回報儲存的路徑以及實際的持續時間/格式。永遠不要捏造成功的生成、轉錄或任務完成。
轉錄
curl --fail-with-body --show-error http://localhost:3900/v1/audio/transcriptions \
-F [email protected] -F model=whisper-1 -F response_format=verbose_json
對於純文字轉錄，使用 json 或 text；對於帶時間戳的轉錄，使用 verbose_json；若運行中的架構支援，則使用 srt/vtt 作為字幕。在處理長時間錄音前，請檢查轉錄模型的就緒狀態；請說明缺少模型的情況並取得下載授權，而不是默默地安裝它。
克隆、設計、配音與較長的工作流程
使用已安裝的 OpenAPI 架構來探索設定檔建立、參考檔案上傳、生成、配音和長格式任務的操作。它們的原生端點比 OpenAI 相容性 API 更廣泛，並且會獨立演進。
- 僅克隆使用者有權使用的語音。保留參考檔案和現有設定檔。
- 對於設計，捕捉所需的語氣、表達方式、語言和範例文字；檢查引擎支援。
- 對於配音，保留原始媒體、說話者指派、片段時間和背景音訊意圖。翻譯完成不等於配音渲染完成。
- 對於非同步工作，使用回傳的任務 ID 和文件記載的進度/狀態端點。檢查終端錯誤；避免盲目地重新提交逾時的生成任務。
- 回傳可用的檔案和誠實的限制，包括缺少的模型或不可用的功能。
MCP 與自動化
運行的後端會在 http://localhost:3900/mcp 掛載一個 MCP 端點。使用用戶端支援的 HTTP 傳輸協定並在執行時期探索其工具。重複使用現有連線，而不是啟動另一個服務。對於僅支援 stdio 的用戶端，請查閱專案的 MCP 指南以取得其 shim。
對於 n8n、呼叫代理、容器或其他主機，請確保後端位址可從該環境到達：容器的 localhost 指的是容器本身。保持驗證和明確的遠端路由選擇不變。整合目錄列表並不表示該整合已連接。
發生錯誤時，請讀取回應內容，區分後端不可用、模型缺失、功能不支援、驗證問題和硬體忙碌。請修復所報告的狀況；不要切換到託管提供者或未經授權下載模型。
桌面工作流程與準備就緒
Electron 應用程式包含語音克隆和設計、已儲存的設定檔和图庫、故事/有聲書、配音專案、轉錄、工具和整合。請偏好使用其現有的專案和語音 ID，而不是建立重複項。對於桌面自動化，請檢查實際的 UI 和目前的設定快捷鍵；不要假設快捷鍵綁定或麥克風權限在每個主機上都相同。
在進行聽寫之前，請驗證已安裝的語音轉文字模型和可用的輸入裝置。區分錄音、暫停錄音、轉錄處理和文字完成。複製轉錄內容並將其插入另一個應用程式是不同的操作；在開始打字之前請確認目標應用程式，並在支援的情況下保留剪貼簿內容。永遠不要僅僅因為轉錄完成就回報文字已送達。
對於配音，請在匯出前檢查缺失/失敗的片段和時間溢位。當要求保留音樂和非語音音訊時，請加以保留；不要默默地取代整個原聲帶。保留原始來源並使輸出成為一個獨立的成品。翻譯風格提示屬於所選的翻譯操作，而遠端代理翻譯則需要使用者配置的提供者選擇。
將整合目錄用作探索和設定指南，而不是工作連接器的證明。在描述連接已準備就緒之前，請驗證實際的憑證、端點可達性和支援的操作。容器部署需要持久化的資料卷和一個可由呼叫端用戶端到達的後端 URL。