よくある質問
読み上げAPIはどのように動作しますか?
POST https://api.playt19.com/v1/audio/speech にテキストを送信すると、音声ファイルが返されます。4096文字を超える場合は分割して結合してください。生成は逐次処理され、キュー待ちが発生する場合があります。
APIキーはどこで取得しますか?
サイトの /get-api-key/ ページでGoogleまたはメールパスワードでサインアップすると、APIキーが発行されます。アカウント作成時にキーと残高を確認でき、必要に応じて新しいキーを発行できます。
curlコマンドは使えますか?
はい、利用可能です。ドキュメントページには準備済みのcurl例が記載されています。JSONボディでモデル、音声、テキストなどを指定し、Authorizationヘッダーでキーを渡すことで音声ファイルを生成できます。
OpenAI SDKは使えますか?
はい、公式OpenAI SDKが利用可能です。base_urlを https://api.playt19.com/v1 に変更し、サイト固有のキーを使用するだけで動作します。SDK固有の独自機能は必要ありません。
レートリミットは?
キーあたり1分間あたり60リクエストです。初回のチャージ前は1分あたり10リクエストに制限されます。超過するとリクエストが拒否されます。バッチ処理には注意してください。
エラー時の処理は?
合成に失敗した場合は、請求は発生しません。料金は全額返金されます。エラーレスポンスを受け取った場合、そのリクエストに対しては課金されませんのでご安心ください。
音声ファイルの形式は?
mp3、wav、opus、flac、pcmから選択可能です。response_formatパラメータで指定します。用途に合わせて最適な形式を選択してAPIリクエストを送信してください。
認証方法は?
Authorizationヘッダーに 'Bearer tts-...' の形式でAPIキーを設定します。各アカウントには1つのアクティブなキーがあり、新しいキーを発行すると旧キーは即時無効になります。
ストリーミングはサポートしていますか?
いいえ、サポートしていません。WebSocketやリアルタイムの部分的な音声ストリーミングは提供していません。API呼び出し完了後に音声ファイルが返されます。
SSMLはサポートしていますか?
いいえ、サポートしていません。SSMLタグやカスタム発音辞書は使用できません。単純なテキスト入力のみを受け付けます。
カスタム音声はサポートしていますか?
いいえ、サポートしていません。顧客向けの音声クローニングや独自の音声アップロード機能はありません。8つのプリセット音声から選択してください。
音声のクローニングはサポートしていますか?
いいえ、カスタムクローニングは提供していません。既存の8つのプリセット音声を使用します。独自の声のクローニング機能は現在ありません。
音声のデザインはサポートしていますか?
いいえ、音声デザイン機能は提供していません。既存の8つのプリセット音声から選択して使用してください。
音声の感情タグはサポートしていますか?
いいえ、感情タグはサポートしていません。速度パラメータで調整は可能ですが、特定の感情タグによる制御はできません。
APIキーの取得方法
SmartKoeのAPIを利用するには、まずアカウントの作成が必要です。/get-api-key/ページでGoogleサインインまたはメール登録を行い、認証キーを入手してください。
Googleアカウントでの新規登録には無料トライアル($0.50)が付与されます。メールアドレス登録の場合はトライアルなしで開始可能です。
Googleサインイン
Googleアカウントを使用して即座にサインアップできます。この方法でアカウントを作成すると、7日間有効な$0.50の無料クレジット(約5万文字分)が付与されます。
スマートホームやIoTプロジェクトの試作段階で、APIの動作確認をすぐに開始するのに適しています。
- 7日間の無料クレジット付与
- 即座にAPIキーを発行可能
メール登録
メールアドレスとパスワードを使用してアカウントを作成することもできます。この方法では、サインアップ直後のトライアルクレジット付与はありません。
既存のSmartKoeアカウントとは独立して管理されるため、プロジェクトごとに異なるキー環境を構築したい場合に適しています。
キーの発行と管理
ダッシュボードにはAPIキー、残高、使用状況が表示されます。キーは1アカウントあたり1つ有効で、新しいキーを発行すると古いキーは直ちに無効になります。
生成されたキーはAuthorizationヘッダーに設定して使用します。キーの管理はWebページ上で行い、必要に応じて再発行してください。
- 1アカウント1キー
- 新キー発行で旧キーは即時停止
curlコマンドでの利用
curlコマンドを使用して、APIエンドポイントにPOSTリクエストを送信し、音声ファイルを取得します。
生成された音声はレスポンス本体として返され、ファイルとして保存できます。
リクエストの送信
POST https://api.playt19.com/v1/audio/speech に対し、JSONボディで model、input、voice、response_format を指定します。テキストは4096文字まで可能です。
- - Authorization ヘッダーにベアラートークンを設定
- -
inputフィールドに読み上げテキストを指定 - -
response_formatで mp3/wav/opus を選択
レスポンスの受信
正常なリクエストでは、音声ファイルのバイナリデータが返されます。これを標準出力にリダイレクトしてファイルに保存します。
エラーの確認
エラーが発生した場合はJSON形式のエラーメッセージが返されます。ステータスコードを確認し、原因を特定します。
OpenAI SDKとの連携
OpenAI公式SDKをそのまま利用可能で、APIのベースURLを変更するだけで連携できます。既存のコードを大幅に書き換える必要がなく、スマートホームやIoTデバイスの音声通知システムにすばやく組み込めます。
PythonやNode.jsなどの標準ライブラリで、tts-1やtts-1-hdモデルを呼び出すことができます。認証情報は環境変数から読み込む形式を推奨し、セキュリティを維持しながら開発を進めてください。
base_urlの変更
SDKの初期化時に、base_urlをhttps://api.playt19.com/v1に設定します。これにより、OpenAI互換のエンドポイントとしてSmartKoeのAPIが認識されます。認証ヘッダーにはAuthorization: Bearer <APIキー>を付与してください。
既存のOpenAI用コードのベースURL書き換えだけで動作します。他のパラメータ(voice, inputなど)は標準仕様に準拠しているため、追加の設定は不要です。
- base_url: https://api.playt19.com/v1
- 認証: Authorization: Bearer <キー>
- モデル: tts-1 または tts-1-hd
コード例
Pythonの場合、openaiパッケージを使用して音声ファイルを生成します。以下のコードは、指定されたテキストを音声に変換する基本的な実装例です。inputフィールドに生成したいテキストを、voiceフィールドに8つのプリセットから選択した音声名を設定します。
生成された音声ファイルはバイナリデータとして返され、ローカルファイルに保存するか、IoTデバイスに送信します。
- import openai
- client = OpenAI(base_url="https://api.playt19.com/v1", api_key="<KEY>")
- audio = client.audio.speech.create(model="tts-1", voice="nova", input="スマートロックを開けます")
エラー処理
API呼び出し時にネットワークエラーや認証エラーが発生した場合、SDKは例外をスローします。401エラーはAPIキーが無効または期限切れであることを示します。429エラーはレートリミット(60リクエスト/分)を超えた場合です。
これらのエラーをキャッチし、必要に応じて再試行ロジックを実装してください。失敗したリクエストは課金されませんので、データの整合性を保ちながら安全に処理できます。
- 401: 認証エラー(キー確認)
- 429: レートリミット超過(60 RPM)
- 失敗時は課金されません
レートリミットについて
レート制限は1APIキーあたり1分間60リクエストです。これはIoTデバイスの定期的な通知やスマートホームの音声フィードバックに適しています。
利用開始直後は1分間10リクエストの制限が適用されます。TRC-20(USDT)でのチャージ後、制限は直ちに解除されます。
60 RPM
通常時、1分間あたり60リクエストまで送信可能です。短く頻繁な音声通知や、複数デバイスへの同時配信に最適です。
- 1分あたり60リクエスト
- 通常時の標準制限
10 RPM
アカウント作成後、最初のチャージ完了まで1分あたり10リクエストの制限がかかります。これは無料トライアル期間にも適用されます。
- 1分あたり10リクエスト
- チャージ前の制限
キーごとの制限
制限はアカウントではなくAPIキーごとに独立しています。キーを再発行すると旧キーは即時無効化されます。
- キー単位での管理
- 再発行で制限リセット
エラー処理の方法
API呼び出し時のエラーは、HTTPステータコードで判別します。各エラーに応じた処理をコードに実装することで、スマートホームやIoTデバイスでの音声生成パイプラインの安定性を確保します。
失敗したリクエストは課金されません。エラーログを記録し、必要に応じて再試行ロジックを組み込むことを推奨します。
400エラー
リクエスト形式の不正、無効なパラメータ、または指定されたモデルが存在しない場合に返されます。JSONボディの構造を確認し、modelやvoiceの値が仕様通りか検証してください。
- JSON形式の不正
- 無効なパラメータ値
- 存在しないモデル指定
401エラー
APIキーが未設定、無効、または期限切れの場合に発生します。ヘッダーのAuthorization: Bearer <key>が正しいか確認してください。キーの再発行も可能です。
- APIキー未設定
- 無効なキー
- キーの期限切れ
429エラー
レートリミット超過時です。通常は1分間60リクエスト、初回利用時は1分間10リクエストの制限があります。バックオフアルゴリズムを用いて再試行してください。
- 1分間60リクエスト
- 初回1分間10リクエスト
- バックオフ再試行推奨
音声ファイルの形式
SmartKoeのTTS APIでは、mp3、wav、opus、flac、pcmの5つの音声出力形式に対応しています。IoTデバイスやWebアプリへの組み込みにおいて、ネットワーク帯域や再生環境に適した形式を選択可能です。
データ転送量を抑えたい場合はmp3やopus、録音や編集用途にはwavやflacが適しています。
MP3
最も汎用性の高い形式です。ほとんどのブラウザやメディアプレイヤーで再生可能で、ファイルサイズが小さく帯域効率が良いです。
IoTデバイスやWebアプリでの音声読み上げに最適です。音声認識やバックグラウンド再生のシナリオで広く採用されています。
- 広く対応したメディアプレイヤーで再生可能
- ファイルサイズが小さく帯域効率が良い
- IoTやWebアプリでの音声再生に最適
WAV
非圧縮のオーディオ形式で、高音質なままデータを取得できます。音声の解析や編集、録音用途に適しています。
ファイルサイズは大きくなりますが、劣化のない忠実な音声データが必要な場合に推奨されます。
- 非圧縮で高音質なオーディオ形式
- 音声解析や編集、録音用途に適す
- ファイルサイズは大きいが劣化しない
Opus
高効率なオーディオコーデックです。低ビットレートでも高音質を維持し、リアルタイム通信やストリーミングに適しています。
帯域が限られる環境でも、音声の明瞭さを保ちながらデータ転送量を削減できます。
- 高効率なオーディオコーデック
- 低ビットレートでも高音質を維持
- 帯域が限られる環境でデータ転送量を削減
認証方法の確認
SmartKoeのAPIはBearerトークン方式で認証を行います。有効なAPIキーをリクエストヘッダーに設定することで、音声生成エンドポイントへのアクセス権限が付与されます。
ベアラートークン
認証にはAuthorization: Bearer tts-...という形式のトークンを使用します。このトークンはアカウントごとに一意に生成され、APIリクエストの正当性を検証するために必要です。
- トークンはBearerスキームで渡す
- トークンはアカウントごとに一意
Authorizationヘッダー
HTTPリクエストのヘッダーフィールドにキーを指定します。これにより、APIサーバーはリクエスト元のアカウントと権限を識別し、レートリミットや残高をチェックします。
- ヘッダーにキーを指定
- サーバーがアカウントを識別
APIキーの管理
アカウントにはアクティブなキーが1つだけ存在します。新しいキーを発行すると、旧キーは直ちに無効化されます。セキュリティを確保するため、定期的なキーのローテーションを推奨します。
- アクティブキーは1つのみ
- 新発行で旧キーは即時停止

ストリーミングの有無
SmartKoe APIはストリーミングに対応していません。音声データは全文生成が完了してから単一のファイルとして返却されます。IoTデバイスやWebアプリへの組み込みには、ファイルのダウンロード処理が必要です。
非対応
音声の前半部分だけを送信する機能はありません。処理速度は実時間並み(約25文字/秒)です。
ファイルダウンロード
リクエスト送信後、生成された音声ファイル(MP3/WAV/Opus)がレスポンスとして返されます。ノコード開発では、このファイルを受信して保存または再生する仕組みを構築します。
リアルタイム再生
リアルタイムストリーミングではなく、ファイル単位での処理となります。短めのテキストでも生成に数秒要することがあります。
SSMLの有無
SmartKoe APIはSSML(Speech Synthesis Markup Language)に対応していません。音声の発話制御が必要な場合は、テキストを適切な長さに分割するか、速度パラメータで調整してください。
入力はプレーンテキストのみです。カスタム発音や強調、一時停止を細かく指定する機能はありません。シンプルで確実な音声合成を実現します。
非対応
SSMLタグは認識されません。複雑なマークアップをサポートしていないため、シンプルで確実な音声合成が可能です。
テキストのみ
入力フィールドにはプレーンテキストのみが有効です。発音記号や強調タグは単なるテキストとして処理されます。
- プレーンテキストのみ入力可能
音声ファイル
音声ファイルの生成にはテキストのみを使用します。MP3やWAVなどの形式で出力されます。
- MP3、WAV、Opus、FLAC、PCM
カスタム音声の有無
SmartKoeは、8種類のプリセット音声(aria, nova, luna, sage, felix, milo, atlas, orion)のみの提供です。ユーザーが独自の音声データをアップロードしたり、既存の声似の音声を生成したりする「カスタム音声クローニング」機能は備えていません。
音声のデザインや感情タグも指定できません。すべての音声ファイルは、LibriTTS-R(CC BY 4.0)およびLibriVoxの録音データから生成されたプリセットのみを使用します。
非対応
カスタム音声のアップロード、クローニング、デザイン機能は提供していません。音声の細かな調整はプリセットの選択のみで完結します。
プリセットのみ
aria, nova, luna, sage, felix, milo, atlas, orionの8種類のプリセットから選択してください。これらは特定の用途に合わせて設計されています。
各音声は固定されたトーンを持ち、リクエストごとに声質を変更することはできません。
音声のクローニング
既存の人の声を記録してモデル化し、新しいテキストを読み上げさせる音声クローニングは行いません。
音声の感情やニュアンスをカスタマイズする機能もありません。
音声のクローニングの有無
SmartKoeの音声クローニング機能は非対応です。既存の8種類のプリセット音声(aria, nova, luna, sage, felix, milo, atlas, orion)のいずれかを選択して使用します。独自の声や特定の人物の声をコピーして生成するカスタムクローニング機能は提供していません。
非対応
音声のクローニング機能は非対応です。APIリクエストでは、voiceパラメータで事前に定義された8つのプリセットからいずれかを指定する形式となります。既存の音声データをアップロードして新しい声を学習させる機能や、特定の個人の声似の音声を作成するカスタムクローニングは提供していません。
- 既存のプリセット音声のみを選択可能
- カスタム音声データのアップロード不可
- 特定の人物の声のクローニング不可
プリセットのみ
利用可能な音声は、LibriTTS-RおよびLibriVoxの録音データに基づく8つのプリセットです。これらの音声は、スマートホームの通知やIoTデバイスでの案内など、明確な音声合成が求められる用途に適しています。
aria, nova, luna, sage, felix, milo, atlas, orionの8種類から、用途に合わせて適切な音声を選択してください。
- aria, nova, luna, sage (女性)
- felix, milo, atlas, orion (男性)
- LibriTTS-R / LibriVoxベース
音声のデザイン
音声のデザイン機能も非対応です。感情タグを付与して音声のトーンを変更したり、カスタムな音声特性をデザインしたりすることはできません。
各プリセット音声は固定された特性を持っています。
- 感情タグ非対応
- 音声特性のカスタムデザイン不可
音声のデザインの有無
音声のニュアンス制御は非対応です。感情タグ(例:happy, sad)による細かな表現の調整は行えません。
プリセットの声は8種類用意されており、それぞれの声質特性に基づいて利用されます。
音声のデザイン機能も非対応です。カスタム音声の生成や、既存の声の調整はできません。
非対応
音声のニュアンス制御は非対応です。感情タグ(例:happy, sad)による細かな表現の調整は行えません。
音声のデザイン機能も非対応です。カスタム音声の生成や、既存の声の調整はできません。
プリセットのみ
プリセットの声は8種類用意されており、それぞれの声質特性に基づいて利用されます。
男女のボイスから選択し、IoTデバイスやWebアプリに組み込みます。
- aria: 暖かく明確なナレーター
- nova: 明るく活気のあるトーン
- luna: 柔らかく物語的な語り
- sage: 落ち着きのある教育系
音声の感情タグ
感情タグによる音声のニュアンス制御は非対応です。
テキストの内容に基づき、プリセットの声が音声ファイルを生成します。
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。
23言語
どの音声でも、これらの言語のいずれかを話します。
