よくある質問
APIとは何ですか?
APIは、アプリケーションが互いに通信するための仕組みです。当社のTTS APIは、テキストを送信すると音声ファイルが返されるクラウドサービスです。HTTPのPOSTメソッドでリクエストを送信し、JSON形式でデータをやり取りします。
RESTful APIとは?
RESTful APIは、インターネット標準のHTTPプロトコルを使用した設計手法です。当社のAPIはGETやPOSTなどのHTTPメソッドを使い、URLエンドポイントを通じて音声合成リクエストを処理します。OpenAI SDKと互換性のある仕様を採用しています。
JSONデータとは?
JSONは、軽量なデータ交換形式です。APIリクエストでは、モデル名や音声、テキストなどをJSON形式のボディに含めて送信します。レスポンスとして返される音声ファイルも、適切に処理されるJSON形式のメタデータとセットで受け取ります。
Bearerトークンとは?
Bearerトークンは、APIへの認証に使用する秘密の鍵です。リクエストヘッダーに「Authorization: Bearer <キー>」として設定します。各アカウントには1つのアクティブなキーがあり、新しいキーを発行すると旧キーは直ちに無効になります。
レートリミットとは?
レートリミットは、1分あたりのリクエスト制限です。通常は1分あたり60リクエストまで、初回前は1分あたり10リクエストまで利用可能です。これを超過するとリクエストが拒否されるため、バッチ処理などで調整が必要です。
バッチ処理とは?
バッチ処理は、大量のテキストを一度に処理する手法です。4096文字ごとにテキストを分割し、複数の音声ファイルを生成してから結合します。これにより、長い文章でも効率的に音声合成を行うことができます。
キューとは?
キューは、リクエストが処理される順番を待つ待機列です。負荷がかかる場合、リクエストはキューに積まれ、順番に処理されます。これにより、音声生成は通常リアルタイム速度で行われますが、待ち時間が発生する可能性があります。
ストリーミングとは?
ストリーミングとは、データを連続的に受信する方式です。当社のAPIではストリーミングは提供されていません。リクエストを送信すると、音声ファイルの生成が完了してからレスポンスとしてファイル全体が返されます。
SSMMLとは?
Q: SSMLとは? A: SSMLは音声合成の発話スタイルを制御するマークアップ言語です。当社のAPIではSSMLをサポートしていません。速度や音声の種類はパラメータで指定できますが、詳細な発話制御はできません。
カスタム音声とは?
カスタム音声とは、ユーザー独自の声を学習させて作成する機能です。当サービスではカスタム音声の提供はありません。8つのプリセットされた音声の中から、プロジェクトに合った声を選択してご利用ください。
エラーコードとは?
エラーコードは、リクエストが失敗した理由を示す番号です。音声合成に失敗した場合、料金は全額返金されます。エラーコードを確認して、テキストやパラメータに問題がないか確認してください。
レスポンスとは?
レスポンスは、APIサーバーから返されるデータです。音声合成が成功すると、音声ファイル本体とメタデータがレスポンスとして返されます。生成された音声ファイルはサーバーに保存されず、即座にクライアントに返されます。
メタデータとは?
メタデータは、データに関する追加情報です。APIのレスポンスには、音声ファイルの形式やサイズ、生成時間などの情報が含まれます。また、請求のためにリクエストのメタデータが記録されます。
データフローとは?
データフローは、データの処理の流れです。テキストを入力し、APIエンドポイントにPOSTリクエストを送信し、音声ファイルを受信します。入力は音声生成のみに使用され、学習には利用されません。生成された音声は保存されません。
APIの基本概念
KoeLinkはRESTfulなJSON APIを提供しています。テキストを送信すると音声ファイルが返るシンプルな構造で、OpenAI SDKのbase_urlを変更するだけで連携可能です。
認証とデータ形式を正しく設定するだけで、ブラウザやバックエンドからすぐに音声合成を起動できます。
RESTful APIの構造
KoeLinkは標準的なREST APIを採用しています。POSTで音声生成リクエストを送信し、JSON形式で音声ファイルを受信するシンプルな設計です。
- HTTPメソッドの標準化
- ステートレスな接続
JSONデータの送受信
リクエストボディにはモデル名や音声ファイルの形式をJSONで指定します。返されるレスポンスもJSON形式で、生成済みの音声データを直接受け取れます。
認証情報の管理
APIキーはリクエストヘッダーにBearerトークンとして設定します。各アカウントには有効なキーが一つあり、必要に応じて新しいキーを発行できます。
- Authorization: Bearerヘッダー
- 単一キー管理
エンドポイント
KoeLinkのAPIは、標準的なRESTful構造を採用しています。主な機能は音声生成エンドポイントと、利用可能な音声やモデル情報を取得するエンドポイントで構成されています。
これらのエンドポイントを通じて、ブラウザやバックエンドから効率的に音声合成リクエストを送信・管理できます。
POST /v1/audio/speech
テキストから音声ファイルを生成するための主要エンドポイントです。JSONボディでモデル、入力テキスト、音声、フォーマットなどを指定します。
最大4096文字までのテキストを送信でき、mp3やwavなどの形式で音声データを取得できます。
GET /v1/voices
利用可能な音声、言語、フォーマット、価格情報を取得します。8種類の音声プリセットと23言語の対応状況を確認できます。
各音声の特徴やサポート言語を事前に確認し、プロジェクトに最適な音声を選択してください。
- 8種類の音声プリセット
- 23言語のサポート
- 音声ごとの特性確認
GET /v1/models
利用可能なモデル情報を取得します。"tts-1"と"tts-1-hd"の2モデルが利用可能で、同じエンジンと価格です。
モデルの仕様や制限事項を確認し、適切なモデルを選択してAPIリクエストを送信してください。
リクエストの構造
音声合成APIへのリクエストは、JSON形式のボディで送信します。APIはRESTfulな構造を採用しており、シンプルなHTTPリクエストで音声ファイルを生成できます。認証情報はヘッダーに付与し、安全に管理しましょう。
必須パラメータ
最低限必要なパラメータは model、input、voice の3つです。model には "tts-1" または "tts-1-hd" を指定します。input には4096文字以内のテキスト、voice には8種類のプリセットのいずれかを設定します。
- model: "tts-1" または "tts-1-hd"
- input: テキスト(最大4096文字)
- voice: 8種類のプリセットから選択
オプションパラメータ
生成音质や速度を制御するオプションがあります。response_format で mp3 や wav などの形式を指定でき、speed で 0.25〜4.0 の範囲で再生速度を調整します。language は任意のISOコードで言語を指定可能ですが、未設定の場合はスクリプトから自動推測されます。
- response_format: mp3, wav, opus, flac, pcm
- speed: 0.25〜4.0(デフォルトは1.0)
- language: 任意のISOコード(任意)
ボディの形式
リクエストボディは JSON 形式です。OpenAI SDKの互換性があるため、既存のコードを少し修正するだけで統合できます。テキストが長い場合は、4096文字ごとに分割して送信し、生成された音声ファイルを結合してください。
レスポンスの処理
APIからの応答には、生成された音声ファイル自体と、その処理状況を示すメタデータが含まれます。主要なエンドポイント POST /v1/audio/speech へリクエストを送信すると、サーバーは処理結果を返します。
音声ファイルの受け取り
成功したリクエストの場合、レスポンスボディには音声データ(mp3, wav, opus, flac, pcmのいずれか)が直接含まれます。これはHTTPステータスコード200と共に返され、ブラウザやアプリで直接再生、またはファイルとして保存可能です。
メタデータの解釈
レスポンスには、処理に要した時間や使用した文字数などのメタデータは含まれません。これらは請求の根拠となり、APIキーごとの使用状況を確認する際に役立ちます。
エラーレスポンス
音声合成に失敗した場合は、適切なエラーコードとメッセージが返されます。この場合、そのリクエストは無料となり、課金されることはありません。エラー内容を確認し、必要に応じてパラメータを修正して再送信してください。
データフロー
APIはRESTfulなデータフローに基づき、クライアントからサーバーへJSONリクエストを送信し、音声ファイルを受信します。このプロセスは、Webアプリやバックエンド処理での音声合成連携の基盤となります。
クライアントからサーバーへ
クライアントはPOSTメソッドでhttps://api.playe67.com/v1/audio/speechへJSONボディを送信します。認証情報(Bearerトークン)をヘッダーに含め、テキストと音声設定を指定します。
- JSON形式でのテキスト入力
- Bearerトークンによる認証
- 最大4096文字のテキスト制限
音声生成プロセス
サーバーはリクエストを受けると、指定されたモデル(tts-1またはtts-1-hd)で音声合成を実行します。テキストが長い場合は分割され、音声ファイルが生成されます。
- 生成速度
- 音声ファイルの結合処理
- キューによる順序処理
レスポンスの返却
生成された音声ファイル(mp3、wavなど)がレスポンスボディとして返されます。ステータスコードとメタデータも同時に提供され、エラー時には適切なエラーメッセージが返ります。
- 音声ファイルの直接受信
- ステータスコードの確認
- エラーメッセージの解釈
認証とセキュリティ
KoeLinkのAPIは、リクエストごとにBearerトークンを用いた認証を行います。APIダッシュボードで生成したキーをリクエストヘッダーに設定することで、音声合成サービスへのアクセス権限を制御します。
Bearerトークン
Authorizationヘッダーに「Bearer <YOUR_API_KEY>」と付加してください。キーは1アカウントにつき1つが有効で、新しいキーを発行すると古いキーは即時無効になります。
- ヘッダー形式: Authorization: Bearer tts-...
APIキーの保護
APIキーはWebダッシュボードで随時再発行可能です。古いキーは新しいキーの発行と同時に即座に無効化されるため、セキュリティリスクを即座に遮断できます。
- キーは1アカウントあたり1つ
- 再発行で旧キーは即時無効
リクエストの検証
正しいキーと有効なエンドポイントが設定されていない場合、APIはアクセスを拒否します。また、各キーには minuteあたりのリクエスト数制限(60リクエスト)が適用され、負荷が制御されます。
- 不正なキーはアクセス拒否
- 分間60リクエストの制限あり
スケーラビリティ
KoeLink APIは、1分間に60リクエスト(初回トップアップ前は10リクエスト)というレートリミットを設けています。開発者はこの制限を意識し、短時間で大量のテキストを処理する場合は、適切な間隔を空けてリクエストを送信する必要があります。
バッチ処理では、4096文字を超える長いテキストを複数の小さなパートに分割し、それぞれを個別に生成します。生成された音声ファイルはプログラム側で結合することで、全体として一貫した音声コンテンツを完成させます。
レートリミットの管理
1分間に60リクエストが上限です。初回のトップアップ前までは1分あたり10リクエストに制限されます。超過するとエラーが返されるため、監視ツールで使用状況を把握し、必要に応じて待機時間を入れる運用が推奨されます。
- 1分間あたり60リクエスト(初回制限後)
- 初回トップアップ前は1分間あたり10リクエスト
- 超過時はエラーレスポンスが返される
バッチ処理の効率化
1つのリクエストで処理できる文字数は4096文字までです。これを超える文章は、クライアント側またはバックエンドで複数のパートに分割して送信します。各パートの音声ファイルを生成した後、それらを連続して再生することで、一貫した音声を作成します。
- 1リクエストあたりの最大文字数:4096文字
- 分割して複数のリクエストを送信
- 生成された音声ファイルを結合して使用
キューの仕組み
リクエストは順次処理されるため、負荷が高い時間帯にはリクエストがキューに待機する可能性があります。特に短時間のフレーズ生成でも数秒かかることがあり、連続リクエスト時は待機時間が発生し得ます。この特性を考慮して、ユーザー体験を損なわないように設計してください。

統合の例
KoeLink APIは、WebサイトやWebアプリに音声合成機能を簡単に組み込めます。OpenAI SDKのbase_urlを変更するだけで、既存のコードを最小限の手間で活用可能です。
バックエンドやモバイルアプリでも、単純なHTTPリクエストで音声ファイルを入手できます。複雑な処理は不要で、APIキーとテキストを送信するだけです。
Webアプリへの組み込み
ブラウザやサーバーサイドでREST APIを呼び出します。JSONボディにテキストと音声設定を指定し、生成された音声ファイルを受信します。
認証はBearerトークンで行い、APIキーを適切に管理することで安全に利用できます。
- RESTful API構造
- JSONデータの送受信
- Bearerトークン認証
バックエンド処理
Node.jsやPythonなどのバックエンド環境からAPIを呼び出し、音声データを生成します。
生成された音声ファイルは、そのままレスポンスとして返却されるため、データベースに保存する必要はありません。
- REST API連携
- JSONボディ送信
- 音声ファイル受信
モバイルアプリ連携
モバイルアプリからAPIを呼び出すことも可能です。
APIキーをアプリに埋め込むか、バックエンドを経由して使用することで、音声合成機能を提供できます。
- HTTPリクエスト
- APIキー管理
- 音声ファイル再生
デバッグ
API連携中にエラーが発生した際、まずはリクエストの送受信ログを確認し、JSONボディやヘッダーの形式が正しいか検証します。
エラーコードとHTTPステータスコードを照合して原因を特定し、適切なリトライ戦略を実行することで、安定した音声生成を実現します。
ログの確認
リクエスト送信時、JSONボディの文字数が4096文字を超えていないか、APIキーが正しいか確認します。ログには送信時刻やキャラクター数も記録され、課金の確認にも役立ちます。
- JSONボディの構造確認
- APIキーの有効性確認
- 送信文字数の検証
エラーコードの解釈
4xxエラーはパラメータの誤りやキーの無効化を示し、5xxはサーバー側の一時的な問題です。音声生成失敗時は課金が全額返却されるため、エラーログを記録して後で確認できます。
エラーメッセージの内容に基づき、音声やフォーマット指定の修正を行います。
- 4xx: パラメータまたは認証エラー
- 5xx: サーバー側のエラー
- 課金エラー時の返却確認
リトライ戦略
ネットワークエラーやサーバー過負荷の場合、指数バックオフでリトライを行います。レートリミット(60リクエスト/分)を超えた場合は、キューに待機させてから再送します。
短時間のリトライは1-2回程度に留め、それ以上失敗した場合はユーザーに再試行を促すか、ログを記録して後続処理を行います。
- 指数バックオフによるリトライ
- レートリミット超過時の待機
- 最大リトライ回数の設定
ベストプラクティス
API利用を効率化し、無駄な課金を防ぎましょう。キャッシュや適切なエラー処理で、安定した音声生成を実現します。
レートリミットを考慮した実装と、失敗時のリトライ戦略を組み合わせることで、スムーズな運用が可能です。
キャッシュの活用
同じテキストと音声パラメータを再利用する場合は、生成済みの音声ファイルをローカルまたはCDNに保存してください。API呼び出し回数を減らし、コストとレイテンシを削減できます。
- 同一テキストの音声ファイルは再利用する
- ハッシュ値などをキーにして管理する
エラーハンドリング
音声合成の失敗時には課金が返金されるため、安心してリトライできます。ネットワークエラーやレートリミット超過時は、指数バックオフで再試行してください。
入力テキストが4096文字を超える場合は、事前に分割して処理することで、エラーを減らしましょう。
- 失敗時の課金返金を利用する
- 指数バックオフで再試行する
パフォーマンス最適化
並列リクエストを送信するとキューが混雑する可能性があるため、レートリミット(1分60リクエスト)を意識してください。バッチ処理では、適度な間隔を開けることが重要です。
短時間での大量生成時は、APIの応答時間を考慮し、ユーザー体験を損なわないよう工夫しましょう。
- 1分間60リクエストの制限を守る
- 並列数の調整でキューを管理する
将来の拡張
将来の拡張については、既存の仕様に合わせて進めます。現在は8音声・5フォーマットで安定稼働しており、急激な仕様変更は行いません。
新しい音声の追加
現在提供中の8種類のプリセット音声に加え、追加のバリエーションが加わる可能性があります。ただし、既存のAPI互換性は維持されます。
フォーマットの拡張
現在のmp3、wav、opus、flac、pcmに加え、他の音声フォーマットのサポートも検討されています。ニーズに合わせて対応していきます。
APIのバージョン管理
現在のAPIバージョンは維持されます。大きな変更がある場合は事前に通知しますが、基本的には後方互換性を重視します。
サポート
KoeLinkは電話やライブチャットを持たず、すべてのサポートはメールのみです。技術的な質問や課金に関する問い合わせは、公式ドキュメントを参照しながらメールで受け付けます。
迅速なレスポンスを提供するため、詳細なエラーログや使用状況を添付していただくと処理がスムーズになります。
技術文書の参照
まず公式ドキュメントのAPI仕様を確認してください。リクエスト形式やエラーコードの解釈方法が詳しく記載されています。
デバッグ時に参考になるcurl例や、よくある失敗パターンも記載していますので、まずはそちらをご覧ください。
- APIリファレンス
- エラーコード一覧
- curlサンプル
メールサポート
電話やライブチャットは用意していません。すべての問い合わせはメールで行います。
技術的な不明点や課金のトラブルなど、どんな質問でも受け付けています。
メールには、発生したエラーメッセージやリクエストIDを必ず記載してください。これにより、より正確かつ迅速な回答が可能になります。
コミュニティの活用
公式のコミュニティフォーラムはありませんが、ドキュメント内のコード例は他の開発者とも共有しやすい形式です。
GitHubや技術ブログで、KoeLinkを活用した実装例を探してみることもおすすめです。
独自の解決策を見つけたら、ドキュメントの改善提案としてフィードバックを送ることができます。
- コード例の共有
- フィードバック投稿
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 あなたのアイデアをコードなしで自由に形に変えていきましょう。
23言語
どの音声でも、これらの言語のいずれかを話します。
