TTS API 利用ガイドと仕様書

作成者 SmartKoe 編集部 · 更新日 2026-11-18

ノーコード開発者が、APIキーの取得から初回リクエストまで迅速に開始できるよう、具体的なcurlコマンドとパラメータ仕様を明記しています。

認証、レートリミット、エラー処理、およびOpenAI SDKとの互換性について解説します。エンドポイントの仕様とレスポンス形式を参照し、スマートホーム向け音声アシスタントや通知システムの構築を効率的に進めてください。

TTS API 利用ガイドと仕様書

よくある質問

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.mp3

Python (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中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

クイックスタート

の音声波形イラスト: クイックスタート

SmartKoeのTTS APIを利用するには、まずhttps://playt19.com/get-api-key/でAPIキーを取得してください。Googleサインインで無料トライアル($0.50)を開始できます。メールアドレスとパスワードのサインアップではトライアルクレジットは付与されません。

APIキーの取得

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

の音声波形イラスト: 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で生成したものです。

音声のアバター aria
aria女性
音声のアバター nova
nova女性
音声のアバター luna
luna女性
音声のアバター sage
sage女性
音声のアバター felix
felix男性
音声のアバター milo
milo男性
音声のアバター atlas
atlas男性
音声のアバター orion
orion男性

23言語

どの音声でも、これらの言語のいずれかを話します。

出典および参考資料

  1. Wikipedia
  2. Tether (USDT)
  3. openai-node on GitHub
  4. TRON developer hub: TRC-20
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. curl documentation
  7. Creative Commons Attribution 4.0
  8. MDN: Web Speech API
  9. openai-python on GitHub
  10. LibriTTS-R corpus (OpenSLR 141)
  11. Python documentation
  12. IETF RFC 7845: Ogg Opus

このサイトに関するその他の情報