移行ガイド
従来の Open API パスから Open API v1 に移動します。
移行ガイド
TTS v3 への移行
新規クライアントは 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 を使用します。
上記の 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 エンドポイントは、音声、タスク、ジョブ、プロファイル レコードなどの明示的なリソースを中心に設計されています。 1 つのグローバル ラッパー形状に依存するのではなく、エンドポイント固有の応答フィールドを解析するようにクライアントを更新します。
非同期メディア操作の場合、返されたジョブまたはタスク ID をすぐに永続化します。ポーリング、再試行、およびサポート調査にはその ID を使用する必要があります。
請求とクレジット
移行自体はアカウント残高を変更しませんが、新しいエンドポイントではより明確なクレジットとクォータ フィールドが公開される可能性があります。ロールアウト中に、大量のトラフィックを移動する前に、小規模なジョブで古いコード パスと新しいコード パスを比較します。
移行中にリクエストが失敗した場合は、レガシー パス、新しいパス、ステータス コード、API requestId、および内部ジョブ ID をログに記録します。これにより、ベアラー API キーやプライベート メディア URL を公開することなく、サポートに十分なコンテキストが提供されます。