遷移指南
從舊版 Open API 路徑移至 Open API v1。
遷移指南
TTS v3 遷移
新的 TTS 用戶端應使用 HTTP v3 與 Realtime v3；現有 HTTP v1/v2 和 Realtime v2 仍相容。HTTP 改用 /api/open/v3/speech/tts、/api/open/v3/speech/tts/jobs、/api/open/v3/voices 與 /api/open/v3/openapi.json，只傳送平台 voiceId、公共 modelId 和通用控制項。Realtime 改用 /v3/tts/live、realtime.tts.msgpack.v3 與 camelCase，以 ready.effectiveRequest 為實際配置。
除上文使用 v3 的 TTS 介面外，其他尚未提供 v3 的 Open API 新整合應呼叫 /api/open/v1。舊路徑僅用於相容既有客戶端，不應用於新開發。
路徑映射
| 遺留路徑 | 開啟API v1路徑 |
|---|---|
POST /api/open/create-model | POST /api/open/v1/voices |
POST /api/open/delete-model | DELETE /api/open/v1/voices/{voiceId} |
POST /api/open/list-models | GET /api/open/v1/voices |
POST /api/open/lip-sync/create | POST /api/open/v1/media/lip-sync/jobs |
GET /api/open/lip-sync/list | GET /api/open/v1/media/lip-sync/jobs |
GET /api/open/lip-sync/query | GET /api/open/v1/media/lip-sync/jobs/{jobId} |
透過以下方式確認最終請求和回應形狀：
GET /api/openapi.json推薦訂單
- 先切換唯讀呼叫，例如個人資料、語音清單和工作狀態。
- 在測試覆蓋請求和回應解析後移動建立端點。
- 在推出期間繼續記錄舊端點和新端點。
- 僅在生產流量不再依賴舊客戶端路徑後才刪除舊客戶端路徑。
請求更改
對每個 v1 請求使用承載身份驗證。
Authorization: Bearer FISHAUDIO_API_KEY請在請求本文中使用穩定 ID。TTS 的音色 ID 使用 voiceId，TTS 引擎模型 ID 使用 modelId；只有 reference_id 保留為音色 ID 的舊相容別名。
使用公共系統語音 00a1b221-6137-4b73-ad62-b0cbce134167 進行小型遷移冒煙測試，然後切換到應用程式選擇的生產語音 ID。
回應變化
V1 端點是圍繞顯式資源設計的：語音、任務、作業和設定檔記錄。更新您的用戶端以解析特定於端點的回應字段，而不是依賴一種全域包裝器形狀。
對於非同步媒體操作，立即保留傳回的作業或任務 ID。輪詢、重試和支援調查應使用該 ID。
計費和積分
遷移本身不會改變帳戶餘額，但新端點可能會暴露更清晰的信用和配額欄位。在推出期間，在移動大流量之前，先比較小型作業的新舊程式碼路徑。
如果遷移期間要求失敗，請記錄舊路徑、新路徑、狀態代碼、API requestId 和您的內部作業 ID。這提供了足夠的上下文支持，而無需暴露承載 API 金鑰或私有媒體 URL。