移行ガイド

新しい統合では、/api/open/v1 を呼び出す必要があります。互換性期間中はレガシー パスも引き続き使用できますが、新しい作業には使用しないでください。

パスマッピング

最終的なリクエストとレスポンスの形状を次のように確認します。

GET /api/openapi.json

推奨される順序

1. 最初に、プロファイル、音声リスト、ジョブ ステータスなどの読み取り専用通話を切り替えます。
2. リクエストとレスポンスの解析がテストでカバーされた後、作成エンドポイントを移動します。
3. ロールアウト中は、レガシー エンドポイントと新しいエンドポイントの両方のログを記録し続けます。
4. レガシー クライアント パスを削除するのは、運用トラフィックが依存しなくなった後でのみ行ってください。

変更のリクエスト

すべての v1 リクエストにベアラー認証を使用します。

Authorization: Bearer KITTA_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 を公開することなく、サポートに十分なコンテキストが提供されます。