よくある質問
読み上げ API はどう使いますか?
POST https://api.playt19.com/v1/audio/speech へ JSON 本文を送信し、音声ファイルを受け取ります。モデルは「tts-1」または「tts-1-hd」を指定し、テキストは4096文字以内で送信します。必要に応じて速度や音声プリセットを調整し、生成されたオーディオファイルを IoT や Web アプリに組み込んで利用します。
APIキーはどこで取得しますか?
サイト内の /get-api-key/ ページで Google またはメールパスワードでサインアップすると API キーを取得できます。アカウントにはアクティブなキーが1つ割り当てられ、必要に応じて新しいキーを発行可能です。新しいキーの発行直後に古いキーは即時無効化されます。
curlコマンドは使えますか?
はい、標準的な HTTP リクエストとして curl コマンドを使用できます。/get-api-key/ ページには準備済みの curl 例が表示されます。Authorization ヘッダーに Bearer トークンを設定し、JSON 本文でモデルや音声、テキストを指定して POST リクエストを送信してください。
OpenAI SDKは使えますか?
公式の OpenAI SDK を使用できます。base_url を https://api.playt19.com/v1 に変更し、サイト固有のキーを設定するだけで動作します。リクエスト形状は OpenAI の speech エンドポイントと同一であるため、既存の OpenAI 用コードをそのまま流用して音声合成処理を実装できます。
レートリミットは?
1分あたり60リクエストの制限があります。最初のトップアップ前は1分あたり10リクエストです。テキストが長い場合は4096文字ごとに分割し、生成されたオーディオファイルを結合して使用します。通常、テキスト1秒あたり約25文字の速度で生成されますが、負荷が高い場合はキュー待ちが発生する場合があります。
エラー時の処理は?
音声合成に失敗した場合、請求は発生せず料金が全額返金されます。エラーレスポンスを受け取った場合は、リクエスト内容を確認して再試行してください。メタデータ(時刻、文字数、ステータス)は請求のために保持されますが、生成された音声ファイル自体は保存されません。
音声ファイルの形式は?
mp3, wav, opus, flac, pcm の5形式から選択できます。response_format フィールドに指定することで、IoT デバイスや Web アプリに適した形式で音声ファイルを取得できます。各形式は同じエンジンで生成され、品質や価格に違いはありません。
認証方法は?
Authorization ヘッダーに Bearer トークン形式の API キーを設定します。形式は「Authorization: Bearer tts-...」です。各アカウントには1つのアクティブなキーが割り当てられ、セキュリティのため必要に応じて新しいキーを発行して古いキーを無効化できます。
ストリーミングはサポートしていますか?
ストリーミングはサポートしていません。WebSocket やリアルタイムの部分的な音声配信は提供されません。テキストを送信すると、合成が完了した後に音声ファイルがレスポンスとして返されます。IoT やバッチ処理には適していますが、リアルタイム対話には不向きです。
SSMLはサポートしていますか?
SSML はサポートしていません。音声の制御は速度(speed)パラメータや音声プリセットの選択に限定されます。カスタム発音辞書や音素レベルの制御、SSML タグによる詳細な音声調整は行えません。シンプルなテキスト入力とパラメータ設定のみで音声ファイルを生成します。
カスタム音声はサポートしていますか?
カスタム音声クローニングはサポートしていません。お客様が独自の音声をアップロードしたり、既存の音声と異なる新しい声を作成したりすることはできません。8つのプリセット音声(aria, nova, luna, sage, felix, milo, atlas, orion)から選択して使用します。
音声のクローニングはサポートしていますか?
音声のクローニングはサポートしていません。既存の録音データ(LibriTTS-R, LibriVox)に基づく8つのプリセット音声のみが利用可能です。顧客固有の声を学習させたり、特定の人物の声を模倣したりする機能は提供していません。
音声のデザインはサポートしていますか?
音声のデザインはサポートしていません。既存の8つのプリセット音声から選択するのみです。カスタムな声質やトーンをデザインして新規に作成することはできません。各音声は特定の用途(ナレーター、ニュース、ドキュメンタリーなど)に合わせて設計されています。
音声の感情タグはサポートしていますか?
音声の感情タグはサポートしていません。SSML や特殊なタグを使用して音声に感情やニュアンスを付与することはできません。音声の特徴はプリセット(例:warm, bright, calm)で定義されており、生成時に動的に感情を変更する機能はありません。
APIキーの取得
SmartKoeのAPIキーを取得するには、Googleアカウントまたはメールアドレスでの登録が必要です。Googleサインインは即時のトライアルクレジット付与に対応し、メール登録はトライアルクレジットなしで利用できます。
認証情報は各サイトアカウントに固有で、既存のキーを無効化して新しいキーを即時発行できます。これにより、セキュリティリスクを最小限に抑えつつ、IoTデバイスやWebアプリへの組み込みを迅速に進められます。
Googleサインイン
Googleアカウントでサインインすると、7日間有効な$0.50のトライラルクレジットが付与されます。これは約50,000文字の生成に相当します。
この方法は、APIの使用をすぐに試したいノーコード開発者に適しています。アカウント作成と同時にAPIキーが発行され、利用状況を確認できます。
- トライアルクレジット$0.50が自動付与される
- 7日間の有効期間
- 即時にAPIキーが発行される
メール登録
メールアドレスとパスワードを使用してアカウントを作成することも可能です。この方法では、トライアルクレジットは付与されません。
安定した運用を目的とした開発者が、スマートホームやIoTシステムの音声通知基盤を構築する際に推奨されます。
登録後、すぐにAPIキーを確認し、curlコマンドやSDKを使用して音声生成のテストを実行できます。
- トライアルクレジットは付与されない
- 安定した運用に最適
- いつでもキーを発行可能
キーの発行
アカウントダッシュボードでAPIキーを発行・管理できます。キーは1アカウントにつき1つが有効で、新しいキーを発行すると古いキーは即時無効になります。
この仕組みにより、異なるプロジェクトやデバイス間でキーを使い分ける必要がなく、セキュリティの維持が容易になります。
発行されたキーは、AuthorizationヘッダーにBearerトークンとして設定して使用します。
- 1アカウントにつき1つの有効キー
- 新キー発行で旧キーは即時無効化
- セキュリティリスクを低減
curlコマンドの実行
APIエンドポイントにPOSTリクエストを送信すると、テキスト音声変換(TTS)が実行され、音声ファイルが返されます。最大4096文字の入力に対応し、mp3やwavなどの形式で音声データを取得できます。
レスポンスは音声ファイルそのものまたはJSON形式のエラーメッセージです。成功時はステータスコード200と共に音声データが返され、失敗時は適切なエラーコードとメッセージが含まれます。
リクエストの送信
POST https://api.playt19.com/v1/audio/speech に対して、JSON body で model、input、voice を指定します。認証には Authorization: Bearer ヘッダーが必要です。
- endpoint: POST /v1/audio/speech
- body: {"model": "tts-1", "input": "こんにちは", "voice": "nova"}
レスポンスの受信
正常なリクエストでは、音声ファイル(mp3、wav、opus、flac、pcm のいずれか)が返されます。ファイルは直接ダウンロードまたは保存可能です。
音声ファイルは生成され、長時間テキストでも約25文字/秒の速度で処理されます。
エラーの確認
エラーが発生した場合は、JSON 形式で原因が返されます。ステータスコードを確認し、必要な修正を行います。
例えば、APIキーが無効な場合は 401、レートリミット超過時は 429 が返されます。
- 400: リクエスト形式の誤り
- 401: 認証エラー
- 429: レートリミット超過
OpenAI SDKの使用
OpenAIの公式SDKをそのまま利用し、base_urlのみをAPIエンドポイントに変更するだけで連携可能です。認証ヘッダーはSDKが自動で処理するため、複雑なリクエスト整形の必要はありません。
base_urlの変更
Python SDKを使用する場合、初期化時のbase_url引数に https://api.playt19.com/v1 を指定します。これにより、既存のコード変更最小限で音声生成機能にアクセスできます。
コード例
以下のコードは、指定された音声でテキストを合成し、ファイルとして保存する例です。inputフィールドに最大4096文字のテキストを渡します。
エラー処理
ネットワークエラーや認証失敗は標準的な例外として返されます。失敗したリクエストは課金対象外となるため、適切にエラーをキャッチして再試行またはログ記録を行ってください。
レートリミットの確認
APIキーごとに毎分60リクエストの制限が適用されます。これはIoTデバイスからの定期的な通知送信や、スマートホームシステムでの音声フィードバック生成に利用できます。
課金前の初期状態では、最初のトップアップまで毎分10リクエストに制限されます。この制限により、テスト環境での過剰な使用を防ぎつつ、本番環境への移行を安全に行うことができます。
60 RPM
通常の稼働状態では、1分間に最大60回の音声生成リクエストを送信可能です。これは、複数デバイスの同時接続やバッチ処理に適した性能です。
10 RPM
アカウント作成直後または課金前の状態では、毎分10リクエストに制限されます。これはテスト目的の制限であり、TRONネットワークでのUSDT入金後、自動的に上限が引き上げられます。
キーごとの制限
レートリミットはAPIキーごとに独立して管理されます。一つのキーが制限に達しても、別のキーがあれば並列処理が可能です。ただし、推奨されるのは単一キーの使用であり、複数キーの併用は管理コストを増加させます。
エラー処理の方法
API呼び出し時のエラーは、HTTPステータコードと明確なメッセージで返されます。失敗したリクエストは課金されず、料金が全額返金されます。
400エラー
入力テキストの文字数制限(4096文字)超過や、無効な音声ID指定時に発生します。JSONボディの形式が正しくない場合にも返されます。
- inputフィールドの文字数が4096文字を超えている
- 存在しないvoice IDを指定している
- JSONボディの形式が不正である
401エラー
AuthorizationヘッダーのBearerトークンが無効、または期限切れの場合に返されます。APIキーが正しく設定されているか確認してください。
- APIキーが間違っている
- キーが他のキーによって無効化された
429エラー
レートリミット超過時に応答されます。通常は1分あたり60リクエスト、初回利用時は1分あたり10リクエストの制限があります。
- 1分あたり60リクエストの制限に達した
- 未課金状態での1分あたり10リクエスト制限に達した
音声ファイルの形式
生成された音声ファイルは、MP3、WAV、Opus、FLAC、PCMの5つの形式から選択できます。各リクエストでresponse_formatフィールドを指定することで、出力形式を制御します。
MP3
MP3は最も広くサポートされている形式です。ファイルサイズが小さく、IoTデバイスやWebアプリでの転送効率に優れています。
- 圧縮形式によるサイズ軽減
- 幅広いデバイスでの互換性
WAV
WAVは非圧縮の音声形式です。音質の劣化がなく、音声解析や高精細な処理が必要な場合に適しています。
- 損失のない音声データ
- 即時再生に適した形式
Opus
Opusは高効率な圧縮形式です。帯域幅が限られた環境や、長文の音声生成時にコストと転送量を最適化できます。
- 高い圧縮効率
- 低帯域環境での利用に最適
認証方法の確認
API認証はBearerトークン方式を採用しています。APIキーはアカウントページで発行・管理でき、最大1つが有効です。新しいキーを発行すると古いキーは即時無効化されます。
すべてのAPIリクエストには、ヘッダーに認証情報を含める必要があります。これにより、安全に音声ファイルを生成できます。
ベアラートークン
認証にはBearerトークンを使用します。これはAPIキーそのものです。
トークンは各リクエストで一意に識別され、不正アクセスを防ぎます。
- Bearerスキームを使用
Authorizationヘッダー
HTTPヘッダーにAuthorizationフィールドを設定します。
値は「Bearer YOUR_API_KEY」とします。
これによりAPIエンドポイントがリクエストを承認します。
APIキーの管理
ダッシュボードでキーを確認・再生成できます。
新しいキー発行時に旧キーは即座に無効化されます。
各アカウントにつきアクティブなキーは1つのみです。

ストリーミングの有無
このTTS APIはストリーミング(WebSocketやチャンクごとの逐次受信)には対応していません。音声ファイルの生成が完了するまで待機し、生成終了後に単一のファイルデータがレスポンスとして返されます。
非対応
リアルタイムの音声ストリーミングやSSMLは提供していません。テキストを送信すると、バックエンドで音声ファイルが完全に合成され、それがレスポンスとして返されます。
- ストリーミング接続は使用不可
- チャンクごとのデータ受信は行わない
ファイルダウンロード
生成された音声ファイル(mp3、wav、opusなど)は、レスポンスボディとして直接受信またはダウンロードされます。IoTデバイスやWebアプリへの組み込みには、このファイルデータを使用してください。
生成が完了していない状態での部分読み込みはできないため、短時間の遅延後に完全なファイルを取得してください。
リアルタイム再生
ファイルのダウンロードが完了した後、クライアント側で再生を開始してください。API側では再生中の制御は行わないため、ストリーミングのようなリアルタイム性は実現しません。
音声ファイルのサイズはテキストの長さによるため、短めのテキストでは即座にダウンロード可能ですが、長文の場合は生成完了まで待ちます。
SSMLの有無
このTTS APIはSSML(Speech Synthesis Markup Language)に対応していません。構造化されたマークアップで音質や発音を細かく制御する機能が省かれているため、標準的なHTMLやXMLの知識がなくても、単純なテキストデータを送信するだけで音声ファイルを生成できます。
SSMLの解釈ロジックを省くことで、シンプルなAPI設計を維持しています。IoTデバイスやスマートホームの自動化システムでは、軽量なJSONペイロードが好まれるため、この設計は適合しています。
非対応
SSMLタグ(<prosody>や<p>など)は認識されません。送信したテキスト内の特殊文字は、音声合成エンジンによって無視されるか、単なるテキストとして扱われます。
構造化データが必要な場合は、アプリケーション側でテキストを分割して複数回APIを呼び出す方式を採用してください。これにより、制御ロジックをシンプルに保つことができます。
- SSMLタグは解析対象外です
- 複雑なマークアップは不要です
- テキストのみが処理対象です
テキストのみ
APIの input フィールドには、単なる文字列(String)を渡します。HTMLエンティティやXML構造は考慮されず、そのまま読み上げ対象となります。
これはスマートホームの通知システムにおいて、動的に生成される短いメッセージ(例:「ドアが開きました」)を処理する際、余計な変換コストをかけないための設計です。
- プレーンテキストのみ有効です
- 特殊文字はそのまま出力されます
音声ファイル
最終的に返されるのは音声ファイル(mp3, wav, opus等)です。SSMLによる「間」や「強調」の指定がないため、音声は均一なリズムで出力されます。
特定の単語を長めに読ませたい場合は、テキスト側に「...」や改行を追加して、音声ファイル内のポーズとして機能させる工夫が必要です。
- 音声ファイルはmp3/wav/opus形式です
- テキストの変更で出力が変わります
カスタム音声の有無
SmartKoeの音声合成APIは、ユーザーが独自の声を登録したり、既存の音声データをアップロードしてカスタム音声を作成したりする機能には対応していません。IoTデバイスやスマートホームシステムで使用する音声は、事前に用意された8つのプリセットボイスから選択する形式です。
各ボイスはLibriTTS-RおよびLibriVoxの公開データに基づいており、特定の個人の声や有名人の模倣ではありません。カスタムクローニング機能を必要とするケースでは、別途音声ファイルを生成して組み込む運用となります。
非対応
音声のクローニングやカスタムボイスの作成は現在サポートされていません。ユーザーが任意の音声データをアップロードして、それをモデルに学習させる機能も存在しません。
音声のデザインや感情タグの付与もプリセットの声に限定されます。特定のトーンやニュアンスを細かく調整して新しい声を作る機能は備わっていません。
- 音声データのアップロード機能: なし
- カスタムボイスの学習: なし
- 音声のデザイン: なし
プリセットのみ
利用可能な音声は、aria、nova、luna、sage、felix、milo、atlas、orionの8種類のみです。これらはすべてプリセットとして提供されており、APIリクエストのvoiceパラメータで選択します。
これらのボイスは多言語に対応しており、英語だけでなく日本語を含む23言語で音声合成が可能です。IoT機器のUIや通知音として、一貫した音声品質を保つのに適しています。
- aria: 暖かみのあるナレーター
- nova: 明るく活発なトーン
- luna: 柔らかいストーリーテリング
- sage: 落ち着いた指示口調
- felix: エネルギーあふれるプロモーション
- milo: フレンドリーな会話調
音声のクローニング
音声のクローニング機能は提供していません。既存のボイスのパラメータ(速度やピッチ)を調整することで、異なるトーンを再現することは可能ですが、新しい声を生成するわけではありません。
特定の人物の声を模倣する目的で、外部データから学習させたカスタム音声を使用することもできません。すべての生成音声は、プリセットボイスに基づいています。
音声のクローニングの有無
本APIは、ユーザー固有の声を録音してカスタム音声を作成する機能(音声のクローニング)には対応していません。既存の8種類のプリセットボイスから、スマートホームやIoTアプリケーションの用途に最も適した音色を選択してご利用ください。
非対応
顧客ごとに個別の声優を起用して録音するカスタムクローニング機能はありません。APIリクエストでは、事前に定義された8つのボイスプリセット(Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion)から一意の音声識別子を指定する方式を採用しています。これにより、生成される音声ファイルの品質と特徴を常に一定に保つことができます。
- 個別の音声データアップロード機能なし
- 顧客ごとのカスタム音声モデル生成なし
プリセットのみ
利用可能なのは、LibriTTS-RおよびLibriVoxのデータセットに基づいた8つのプリセットボイスのみです。これらは「暖かいナレーター」「アップビートな告知」「静かなストーリーテリング」など、用途に応じて明確に区別された音色を提供します。特定の個人の声や、既存の著名人の声を模倣したクローニング音声も提供していません。
音声のデザイン
音声のクローニングとは別に、ユーザーが声の特徴を細かくデザインして新たなボイスを生み出す機能もありません。また、生成された音声に「喜び」や「緊張」などの感情タグを付与して音色を変化させる機能も備えていません。必要に応じて速度(0.25〜4.0倍)を調整することで、用途に合わせた音声のトーンを調整してください。
音声のデザインの有無
このAPIは、音声に感情のニュアンスを追加する機能を持っていません。生成される音声は、指定されたボイスプリセットの特性に従って、一定のトーンで出力されます。
開発者は、音声の感情的な変化を期待せず、テキストの内容や速度パラメータで制御することを前提としてください。
非対応
音声に感情のニュアンスを追加する機能は備えていません。生成される音声は、指定されたボイスプリセットの特性に従って、一定のトーンで出力されます。
プリセットのみ
利用可能な音声は8つのプリセットのみです。各ボイスは、アーキタイプに基づいて設計されており、感情タグによる細かなトーン変更はできません。
- Aria(暖かく明確なナレーター)
- Nova(明るく活気のあるトーン)
- Luna(柔らかい物語調)
- Sage(落ち着いた指示用)
- Felix(エネルギッシュなプロモーション)
- Milo(親しみやすい会話調)
- Atlas(中立なニュース調)
- Orion(深みのあるドキュメンタリー調)
音声の感情タグ
読み上げ時に「喜び」や「悲しみ」などの感情タグを指定して声のトーンを変化させる機能は備えていません。速度パラメータでリズムを変えることは可能ですが、感情の付加は手動で制御する必要があります。
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。
23言語
どの音声でも、これらの言語のいずれかを話します。
