遷移指南

新整合應呼叫 /api/open/v1。舊路徑在相容性視窗期間仍然可用，但不應將其用於新工作。

路徑映射

透過以下方式確認最終請求和回應形狀：

GET /api/openapi.json

推薦訂單

1. 先切換唯讀呼叫，例如個人資料、語音清單和工作狀態。
2. 在測試覆蓋請求和回應解析後移動建立端點。
3. 在推出期間繼續記錄舊端點和新端點。
4. 僅在生產流量不再依賴舊客戶端路徑後才刪除舊客戶端路徑。

請求更改

對每個 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。