音声合成のベストプラクティス

良い合成結果は、自然な文章、正確な句読点、音声に合った言語設定から始まります。 安定した運用には、再試行の方針とAPIキーの安全な保管方法も必要です。

どのくらいの長さのテキストを送りますか？

1文、または自然にひと続きで話す発話単位で送信してください。短すぎる断片は 音の高さ、速度、間が変わることがあり、長すぎるリクエストは生成時間と失敗時の コストを増やします。

• 句読点で意図した間と文末を明確にします。
• タイトル、本文、ボタン文言など、読み上げる目的が異なるテキストは分けます。
• 続けて読む文脈が重要な場合は、自然な文単位にまとめます。
• 複数の音声をつなぐ場合は、最終ファイルの無音区間を確認します。

表現タグはどのように使いますか？

対応タグは[laughter]、[sigh]、[en]、[wa]、[hnn]です。タグは 発話の流れに直接挿入し、1文で使いすぎないでください。

本当に良かったです。 [sigh] これで安心できます。

対応していない角括弧タグはリクエストエラーになります。HTTPリクエストで 自由な演技指示が必要な場合は、instructフィールドに自然言語で記述してください。

言語と音声はどのように選びますか？

リクエストの前に/v1/voicesを呼び出し、アカウントで利用できるvoice_idと languageの組み合わせを選択してください。

• 表示名ではなく、安定したvoice_idを保存します。
• 本文の言語とlanguage_codeを一致させます。
• 複数の言語が混在する場合は、意味のある発話単位に分けて適切な言語を指定します。
• 品質を比較するときはtext、voice、language、output formatを固定します。

どの出力形式を選びますか？

形式	適した用途	注意点
mp3_44100_128	Web・アプリでの再生、転送サイズの削減	非可逆圧縮
wav_24000	後処理、編集、分析	ファイルサイズが大きい

一般的な再生にはデフォルトのMP3を、編集パイプラインにはWAVを優先して 検討してください。プロジェクト内でsample rateとformatを統一すると、 後処理がシンプルになります。

再試行はどのように設計しますか？

すべての失敗を再試行しないでください。リクエストを変更せずに成功する可能性が あるエラーだけを、回数を制限して再試行します。

レスポンス	再試行	推奨対応
400·422	いいえ	入力と対応範囲を修正
401·402	いいえ	認証または請求の状態を解決
404	通常はいいえ	voice_idとアクセス権を確認
429	はい	Retry-Afterに従い、jitterを含むexponential backoffを使用
500·502·503·504	制限付きではい	同じリクエストを最大2～3回再試行
timeout	制限付きではい	レスポンス受信の有無と重複処理を先に確認

たとえば1秒、2秒、4秒を基準に小さなランダム遅延を加えます。大量処理では 同時リクエスト数を制限し、アカウントのRPM内でキュー処理してください。正確な 上限はAPIキーや契約によって異なる場合があります。

APIキーはどのように保管しますか？

• サーバーの環境変数またはシークレット管理サービスに保存します。
• ブラウザやモバイルクライアントからKitsch APIを直接呼び出しません。
• ログにはキー全体ではなくprefixと短いpreviewのみを残します。
• development、staging、productionでキーを分けます。
• 漏えいの疑いがある場合は、直ちにrevokeして新しいキーに交換します。

export KITSCH_API_KEY="<API_KEY>"

運用ログには何を残しますか？

APIキーやユーザーのテキスト全体をそのまま残さず、次の項目を構造化して 記録してください。

• リクエスト時刻とアプリケーションのjob ID
• endpoint、voice_id、language、output format
• HTTPステータスコード
• x-kitsch-request-id
• 再試行回数と最終結果

問い合わせ時にrequest ID、発生時刻、endpoint、ステータスコードを伝えると、 より迅速に確認できます。