よくある質問
APIキーはどこで取得しますか?
https://playt19.com/get-api-key/ でGoogleまたはメールアドレスとパスワードでサインアップしてください。アカウント作成後、ダッシュボードにAPIキーが表示されます。キーは1アカウントにつき1つ有効で、必要に応じて新しいキーを発行できます。
curlコマンドの例は?
GET /v1/voices で音声一覧を取得し、POST /v1/audio/speech で音声ファイルを生成します。本文にはmodel、input、voice、response_format、speed、languageを指定できます。認証ヘッダーに Bearer <your_key> を設定してください。
OpenAI SDKは使えますか?
はい、公式OpenAI SDKを使用できます。base_urlを https://api.playt19.com/v1 に変更し、APIキーを設定するだけで動作します。リクエスト形状はOpenAIのspeechエンドポイントと同じです。
レートリミットは?
APIキーあたり1分間60リクエストです。初回のチャージ前は1分間10リクエストに制限されます。長文テキストの場合は4096文字ごとに分割して送信し、生成された音声ファイルを結合してください。
エラー時の処理は?
合成に失敗した場合は、請求は発生しません。料金は全額返金されます。エラーレスポンスを確認し、必要に応じてリクエストパラメータを修正して再送信してください。
音声ファイルの形式は?
mp3、wav、opus、flac、pcmの5形式から選択できます。response_formatフィールドに希望する形式を指定してください。
認証方法は?
HTTPヘッダー Authorization: Bearer <your_key> を使用します。APIキーはアカウント作成時に発行されます。キーは1つだけ有効で、新しいキーを発行すると古いキーは即時無効になります。
ストリーミングはサポートしていますか?
いいえ、ストリーミングやWebSocket、リアルタイムの部分的な音声生成はサポートしていません。POSTリクエストに対して音声ファイル全体が返されます。
SSMLはサポートしていますか?
いいえ、SSMLはサポートしていません。入力テキストはそのまま処理され、SSMLタグは解釈されません。
カスタム音声はサポートしていますか?
いいえ、カスタム音声クローニングや独自の音声アップロードはサポートしていません。8つのプリセット音声から選択してください。
音声のクローニングはサポートしていますか?
いいえ、顧客向けの音声クローニング機能は提供していません。既存の8つの音声プリセットのみを使用できます。
音声のデザインはサポートしていますか?
いいえ、音声のデザイン機能は提供していません。既存の音声プリセットの特性を変更することはできません。
音声の感情タグはサポートしていますか?
いいえ、感情タグはサポートしていません。音声のトーンや感情を制御するタグは使用できません。
音声のフォントはサポートしていますか?
音声にはフォントという概念はありません。当APIは音声プリセット(Aria、Novaなど8種類)に基づいて音声ファイルを生成します。テキストの書式やフォント情報は音声データに含まれないため、音声ファイル内に視覚的なフォント設定は存在しません。音声の質やトーンは、選択したプリセットと速度パラメータによってのみ決定されます。
最初のリクエスト
curl
curl https://api.playt19.com/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playt19.com/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.playt19.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | 女性 |
nova | 女性 |
luna | 女性 |
sage | 女性 |
felix | 男性 |
milo | 男性 |
atlas | 男性 |
orion | 男性 |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
クイックスタート
SmartKoeのTTS APIを利用するには、まずhttps://playt19.com/get-api-key/でAPIキーを取得してください。Googleサインインで無料トライアル($0.50)を開始できます。メールアドレスとパスワードのサインアップではトライアルクレジットは付与されません。
APIキーの取得
Get API Keyページにアクセスし、Googleまたはメールアドレスでサインアップしてください。ダッシュボードに一意のキー(tts-...)が表示されます。
最初のリクエスト
テキストを音声に変換するには、指定されたエンドポイントにPOSTリクエストを送信します。最大4096文字まで処理可能です。
curlコマンド例
以下のコマンドで音声ファイルを生成できます。
```bash
curl -X POST https://api.playt19.com/v1/audio/speech \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "tts-1", "input": "こんにちは", "voice": "nova"}' \
-o output.mp3
```
エンドポイント
APIエンドポイントは音声生成とメタデータ取得の3つです。音声ファイルの生成にはPOST、利用可能な音声リストやモデル情報はGETエンドポイントで取得します。
POST /v1/audio/speech
テキストから音声ファイルを生成する主要エンドポイントです。JSONボディでモデル、テキスト、音声、形式、速度を指定します。
- 長さは4096文字まで。超過時は分割処理が必要。
GET /v1/voices
利用可能な音声プリセット、対応言語、サポートされている音声形式の一覧を取得します。
- 8つの音声プリセットと23言語の対応状況を確認可能。
GET /v1/models
利用可能なモデルの一覧と仕様を確認します。tts-1とtts-1-hdの2種類が利用可能です。
リクエストパラメータ
TTS APIへの音声生成リクエストは、JSON形式でPOST /v1/audio/speechエンドポイントへ送信します。必須パラメータはmodel、input、voiceの3つです。入力テキストは4096文字まで、音声ファイル形式はmp3、wav、opus、flac、pcmから選択可能です。
model
TTS-1またはTTS-1-HDを指定します。両モデルは同じエンジンと価格(100万文字あたり10ドル)を使用します。
input
音声変換対象のテキスト文字列です。最大4096文字まで指定可能で、スペースや句読点も文字数にカウントされます。
voice
以下の8つのプリセットから1つを選択します。aria(暖かくクリアなナレーター)、nova(明るく活気のあるトーン)、luna(柔らかいストーリーテリング)、sage(落ち着いた指示用)、felix(エネルギー満点なプロモーション)、milo(親しみやすい会話風)、atlas(ニュース用のニュートラル)、orion(ドキュメンタリー用)。
レスポンス形式
APIは音声ファイルを直接レスポンスボディに含めて返します。成功時はステータスコード200が返され、ファイル形式はリクエストで指定したmp3、wav、opus、flac、pcmのいずれかになります。
音声ファイル
生成された音声はバイナリデータとして返されます。短文の合成には数秒、長文は実時間並みの処理速度となります。音声ファイルはレスポンスに含まれて返されますが、生成されたファイル自体はサーバーに保存されません。
- 対応形式: mp3, wav, opus, flac, pcm
- ファイルはレスポンスボディに直接含まれる
JSONエラー
処理失敗時はエラー原因を示すJSONオブジェクトが返されます。合成エラーが発生した場合、料金は全額返金されます。
ステータスコード
成功時は200を返します。認証失敗は401、レートリミット超過は429、パラメータエラーは400を返します。
認証方法
API認証にはBearerトークンを使用します。有効なキーのみが音声生成を許可し、不正アクセスを防ぎます。
セキュリティを確保するため、キーは安全な環境で管理し、不要な共有を避けてください。
ベアラートークン
認証ヘッダーには「Bearer + スペース + APIキー」の形式で値を設定します。このトークンはアカウントに一意に紐付き、音声生成の権限を制御します。
- トークンは秘密に保持してください
- 複数デバイスで同一キーを使用可能
Authorizationヘッダー
HTTPリクエストのヘッダーフィールドに設定します。例:Authorization: Bearer tts-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。これを付与することで、APIはリクエスト元の正当性を検証し、音声データを返します。
ヘッダー名は大文字小文字を区別しません。値の末尾に空白や改行が含まれないよう注意してください。
APIキーの管理
各アカウントには1つのアクティブなキーが割り当てられます。ダッシュボードから新しいキーを発行すると、旧キーは直ちに無効化されます。
キーの再発行はいつでも可能ですが、旧キーの失効は即時発生するため、使用中の接続には注意が必要です。

レートリミット
APIキーごとに minute 単位のリクエスト数制限が適用されます。標準アカウントは1分間に60リクエスト、トライアル中は10リクエストが上限です。
60 RPM
通常利用では1分あたり60リクエストまで可能です。長文の合成は内部で分割されるため、実際の生成速度は1文字あたり約0.025秒程度です。
10 RPM(トライアル)
Googleサインインによるトライアルアカウントは、1分あたり10リクエストの制限がかかります。これは最初のチャージ前に適用される制限です。
キーごとの制限
制限は各APIキーに対して個別に適用されます。新しいキーを発行すると古いキーは即時無効化されます。
並列処理は行われず、リクエストはキューで待機します。負荷が高い場合、処理に時間がかかる場合があります。
エラー処理
APIはリクエストの形式や認証状態に応じて、具体的なエラーコードを返します。エラーが発生したリクエストは課金対象外となり、料金は全額返金されます。
各エラーはJSON形式で詳細を返すため、ログ解析や自動リトライロジックの実装が容易です。
400エラー
入力テキストが4096文字を超えている場合、または無効なパラメータが指定された場合に返ります。テキストを分割して再送信してください。
- inputフィールドの文字数制限を確認
- voiceパラメータの有効値を確認
401エラー
Authorizationヘッダーに正しいBearerトークンが含まれていない場合、またはトークンが失効している場合に返ります。APIキーが正しいか確認してください。
429エラー
1分あたりのリクエスト数が制限を超えた場合に返ります。トライアル中は1分あたり10リクエスト、通常は60リクエストが上限です。
- Exponential backoffによる待機処理を実装
- バッチ処理でAPIコールを最適化
OpenAI SDK
SmartKoeのTTS APIはOpenAIのspeechエンドポイントとリクエスト形状が同じです。既存のOpenAI SDKを使用し、base_urlをSmartKoeのAPIベースURLに変更するだけで、追加の設定や変換コードなしで音声合成機能を利用できます。
この互換性により、IoTデバイスやWebアプリへの組み込みが迅速かつ確実に実現可能です。認証情報はSmartKoe固有のAPIキーを使用します。
base_urlの変更
SDKの初期化時に、base_urlパラメータをhttps://api.playt19.com/v1に設定します。これにより、リクエストがSmartKoeの音声合成エンジンへルーティングされます。他のパラメータやエンドポイント構造は変更不要です。
互換性
リクエストボディの構造(model, input, voiceなど)はOpenAIの仕様に準拠しています。既存のOpenAI用コードのbase_urlを変更するだけで利用可能です。
コード例
Python SDKを使用する場合、以下のように設定します。APIキーはSmartKoeのダッシュボードから取得したキーを指定してください。
- ```python
- from openai import OpenAI
- client = OpenAI(api_key="tts-your-key", base_url="https://api.playt19.com/v1")
- response = client.audio.speech.create(
- model="tts-1",
- voice="nova",
- input="こんにちは、スマートホームへようこそ。"
- )
- response.stream_to_file("output.mp3")
- ```
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。
23言語
どの音声でも、これらの言語のいずれかを話します。
