API連携のクイックスタートガイド

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

このガイドは、API開発者やWeb制作初心者がKoeLinkの音声合成APIをすばやく連携できるよう設計されています。ブラウザでのデモ確認から始め、APIキーの取得方法、curlコマンドによる初回リクエストの実行手順、そしてOpenAI SDKとの連携方法まで、具体的なコード例を交えて解説します。

パラメータの使い方やレートリミットの仕組み、エラー時の対応策も網羅しています。長文テキストの扱い方やサポート外の機能についても言及し、プロジェクトで必要な音声生成をスムーズに進めるための実用的な情報を提供します。

API連携のクイックスタートガイド

よくある質問

APIキーはどこで取得しますか?

サイトの/get-api-key/ページでGoogleまたはメール登録を行うと、APIキーが発行されます。初期状態では1分あたり10リクエストの制限がありますが、初回チャージ後には60リクエスト/分に緩和されます。キーはアカウントごとに1つ有効で、新しいキーを発行すると古いキーは即時無効になります。

curlコマンドの例は?

POST https://api.playe67.com/v1/audio/speech へ、JSONボディで model、input、voice を指定してリクエストします。Authorization ヘッダーに Bearer <YOUR_API_KEY> を設定してください。成功すると音声ファイルが返され、失敗したリクエストは無料です。詳細なcurl例はダッシュボードでご確認いただけます。

OpenAI SDKは使えますか?

当社の公式SDKはありませんが、OpenAI SDKで base_url を https://api.playe67.com/v1 に変更してご利用いただけます。リクエスト形状は OpenAI の speech エンドポイントと同じです。他の言語のSDKでも、ベースURLと認証ヘッダーを適切に設定すれば標準的なHTTP通信として利用可能です。

エラーが返されたらどうすれば?

合成に失敗したリクエストについては、料金が全額返金されます。エラーメッセージを確認し、テキストの文字数(4096文字以内)や音声の指定を確認してください。サーバー側の処理待ちにより遅延する場合がありますが、課金されません。詳細はサポートメールまでご連絡ください。

レートリミットは?

APIキーあたり1分あたり60リクエストまで使用できます。ただし、初回チャージ前は1分あたり10リクエストの制限となります。長文のテキストを処理する際は、内部で4096文字ごとに分割され、順次処理されるため、キュー待ちが発生する場合があります。

音声ファイルのサイズは?

音声ファイルのサイズは選択したフォーマット(mp3, wav, opus, flac, pcm)によって異なります。典型的な生成速度は実時間と同程度(約1秒あたり25文字)です。ファイルサイズはテキストの長さや音声の速度パラメータに依存し、固定ではありません。

ストリーミングはサポートされていますか?

ストリーミングやWebSocket、リアルタイムのパートオーディオはサポートされていません。テキストを送信すると、処理が完了した後に音声ファイルがレスポンスとして返されます。長文の場合は分割処理されるため、完了まで待機する必要があります。リアルタイム性は追求していません。

SSMMLは使えますか?

SSML(Speech Synthesis Markup Language)はサポートされていません。音声の制御は speed(速度)パラメータのみで調整可能です。カスタム発音辞書や感情タグ、フェムノームレベルの細かな制御もできません。シンプルなテキスト入力による音声生成が主な機能です。

カスタム音声は指定できますか?

顧客独自の音声クローニングや、アップロードした音声の使用はできません。8種類のプリセット音声(aria, nova, luna, sage, felix, milo, atlas, orion)から選択します。音声デザインやカスタムボイスの機能は現在提供していません。

エラー時の返金ルールは?

音声合成に失敗したリクエストについては、料金が全額返金されます。正常に処理されたリクエストのみが課金対象となります。失敗したリクエストのチャージは自動的に返金されるため、手動での請求調整は不要です。

APIキーの再発行は?

アカウントページから新しいAPIキーをいつでも発行できます。新しいキーを発行すると、古いキーは即時無効になります。セキュリティの向上やキーのローテーションが必要な場合に利用してください。アクティブなキーは1つのみです。

レスポンスフォーマットは?

mp3, wav, opus, flac, pcm の5つのフォーマットから選択できます。response_format パラメータで指定してください。デフォルトのフォーマットは特に定められていませんが、一般的なWeb用途にはmp3やopusが適しています。音声ファイルはレスポンスボディとして返されます。

速度パラメータの効果は?

speed パラメータで0.25から4.0の範囲で音声の速度を変更できます。デフォルト値は1.0です。速度を上げると生成時間が短縮されます。プロジェクトの要件に合わせて調整してください。

言語の自動検出は?

language パラメータを指定しない場合、テキストの文字から言語が推測されます。ラテン文字のテキストはデフォルトで英語として扱われます。日本語や中国語など、ラテン文字以外のテキストでは明示的に language パラメータでISOコードを指定してください。

最初のリクエスト

curl

curl https://api.playe67.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.playe67.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.playe67.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

APIキーの取得

の音声波形イラスト: APIキーの取得

APIキーを取得するには、まず /get-api-key/ でGoogleまたはメールパスワードのどちらかでサインアップしてください。Google認証では無料トライアル($0.50)が付与されますが、メール登録では付与されません。

Googleまたはメールでサインアップ

Googleまたはメールでサインアップ

Googleアカウントまたはメールアドレスとパスワードでアカウントを作成します。アカウントはサイトごとに独立しています。

ダッシュボードでのキー確認

ダッシュボードでのキー確認

サインアップ後、ダッシュボードでAPIキーを確認できます。残高や使用状況もここで管理します。

キーの再発行方法

いつでも新しいキーを発行できます。新キーを発行すると、旧キーは即時無効になります。

最初のリクエスト

の音声波形イラスト: 最初のリクエスト

APIキーを取得したら、実際の音声生成を試してみましょう。ここでは、curlコマンドを使って最初のリクエストを送信する方法と、JSONボディの構成、そして返ってくるレスポンスの解釈について説明します。

curlコマンドの例

以下のコマンドを実行して、テキストから音声ファイルを取得してください。YOUR_API_KEYはダッシュボードで確認したキーに置き換えてください。

  • ```bash curl -X POST https://api.playe67.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "こんにちは、世界!", "voice": "nova"}' \ --output speech.mp3 ```

JSONボディの構成

リクエストボディにはmodel、input、voiceの3つの必須パラメータを含めます。inputは最大4096文字まで指定可能で、スペースや句読点も文字数としてカウントされます。

  • model: "tts-1" または "tts-1-hd" input: 読み上げたいテキスト voice: 声のプリセット名(例: nova, aria)

レスポンスの解釈

成功すると、音声データを含むバイナリファイルが返されます。失敗した場合はエラーメッセージと共にステータスコードが返り、その場合、課金は発生しません。返されたファイルは指定したresponse_format(デフォルトはmp3)で保存してください。

OpenAI SDKとの連携

の音声波形イラスト: OpenAI SDKとの連携

OpenAIの公式SDK(Python, Node.jsなど)をそのまま使えます。base_urlをhttps://api.playe67.com/v1に変更し、APIキーを設定するだけで連携完了です。

既存のコードを最小限の変更で移行できます。エラーハンドリングは標準ライブラリの仕組みに従い、レートリミット超過時は適切な待機処理を実装してください。

base_urlの変更

SDKの初期化時にbase_urlパラメータをhttps://api.playe67.com/v1に指定します。これにより、既存のOpenAI互換の呼び出しが当APIエンドポイントへルーティングされます。

認証ヘッダーにはAuthorization: Bearer YOUR_API_KEYを設定してください。キーはダッシュボードで取得した値を使用します。

公式SDKの再利用

OpenAIの公式SDK(Python, Node.jsなど)をそのまま使えます。modelパラメータにtts-1またはtts-1-hdを指定するだけで音声生成が可能です。

リクエストボディの形状はOpenAIのSpeechエンドポイントと同一なので、既存のアプリケーションロジックをほぼ変更せずに統合できます。

エラーハンドリング

HTTPステータスコードやSDKが返すエラーオブジェクトを確認してください。レートリミット超過時は429エラー、無効なパラメータは400エラーが返ります。

ネットワークエラーやタイムアウト時には、指数バックオフ方式でリトライを実装することをお勧めします。失敗したリクエストは課金されません。

パラメータの詳細

の音声波形イラスト: パラメータの詳細

APIリクエストの核心は、生成される音声の品質と形式を制御するパラメータにあります。ここでは、エンジン、音声プリセット、ファイル形式の3つの主要な設定要素を解説します。

各パラメータはJSONボディ内で指定し、組み合わせによって出力される音声の性格やデータサイズが決定されます。

modelの選択(tts-1/tts-1-hd)

利用可能なモデルは「tts-1」と「tts-1-hd」の2つです。両者は同じエンジンを使用しており、音声の品質や生成速度に違いはありません。価格も同一です。用途に応じて任意のモデルを指定してください。

voiceのプリセット一覧

8種類のプリセットから、プロジェクトの雰囲気に合った声を選択します。女性ボイスの「aria」(暖かくクリアなナレーター)や「nova」(明るく元気なトーン)、男性ボイスの「atlas」(ニュートラルなニュース調)などが利用可能です。

  • aria: 暖かくクリアなナレーター
  • nova: 明るく元気なトーン
  • luna: ソフトなストーリーテリング
  • sage: カルムなインストラクショナル
  • felix: エナジックなプロモーション
  • milo: フレンドリーな会話調

response_formatの設定

音声ファイルの形式はmp3、wav、opus、flac、pcmから選べます。mp3は軽量化に適し、wavは高品質な録音に、opusは効率的な配信に最適です。必要に応じて適切な形式を選択してください。

速度と言語

の音声波形イラスト: 速度と言語

速度パラメータ speed は 0.25 から 4.0 の範囲で調整可能です。デフォルトは 1.0 で、値を上げると発話速度が上がり、下げるとゆっくりになります。

言語は自動検出または明示的な指定で制御します。ラテン文字のテキストはデフォルトで英語として扱われるため、他の言語の場合は language パラメータで ISO コードを指定してください。

speedパラメータ(0.25-4.0)

生成速度は通常、長文で実時間再生程度(1秒あたり約25文字)ですが、速度を変更すると処理時間や出力される音声の速さが変わります。短めの文章では数秒かかることもあります。

languageの指定と自動検出

指定しない場合、テキストの文字コードに基づいて言語が推測されます。ただしラテン文字のテキストはデフォルトで英語と判断されるため、英語以外のラテン文字言語(例:ドイツ語やオランダ語)を使用する場合は、language パラメータで明示的にコードを指定してください。

言語の制限

対応言語は23種類です。ベトナム語、インドネシア語、タイ語、ウクライナ語、ルーマニア語、チェコ語、ベンガル語などは現在サポートしていません。

  • 英語、日本語、中国語、韓国語、フランス語、ドイツ語、スペイン語など23言語
  • どの音声も全ての対応言語を話せます
速度と言語

レートリミット

の音声波形イラスト: レートリミット

APIの利用には、キーごとに1分間あたり最大60リクエストの制限があります。この制限は、安定したサービス提供のために設けられています。

通常の利用ではこの制限内で問題なく動作しますが、大量のテキストを処理する際は、リクエストの集中に注意してください。

1分間60リクエスト

認証済みAPIキー1つにつき、1分間に60回までのリクエストが許可されます。これは1秒間あたり1回のペースに相当します。

この制限を超えると、HTTP 429エラーが返されます。バッチ処理やバックグラウンドタスクでは、適度な間隔を開けて呼び出すことを推奨します。

初回制限(1分間10リクエスト)

アカウント作成直後や、課金前の状態では、1分間に10リクエストまでの制限が適用されます。

これは初回利用時のサーバー負荷を軽減するための仕組みです。初回のトッピング(USDTでの入金)が完了すると、制限は標準の60リクエスト/分に引き上げられます。

制限中は待機するか、バックオフ戦略を用いて再試行してください。

  • 初回: 1分間10リクエスト
  • 通常: 1分間60リクエスト

キューの仕組み

リクエストは一度に一つずつ処理されます。特に長文のテキストを生成する場合、音声合成に時間がかかるため、リクエストがキューに待機することがあります。

このため、短くても生成に数秒要することがあります。並列処理が必要な場合は、クライアント側で適切な待機ロジックを実装してください。

エラー処理

の音声波形イラスト: エラー処理

API連携時に発生する一般的なエラーと、失敗時の課金ルールについて解説します。不正なリクエストや一時的なエラーでも、正しく処理されれば課金は発生しません。

安定した運用のため、適切なリトライ戦略を実装してください。短時間の再試行と指数関数的バックオフを組み合わせることで、キュー待ちを効率的に回避できます。

一般的なエラーコード

401 UnauthorizedはAPIキーが誤っている場合、429 Too Many Requestsはレートリミット(1分間60リクエスト)超過を示します。ボディ形式が不正な場合は400エラーが返ります。

失敗時の課金ルール

音声合成に失敗したリクエストは課金されません。エラーレスポンスが返った場合、その分のクレジットは全額返金されます。

リトライの戦略

短時間の再試行と指数関数的バックオフを推奨します。サーバー側のキュー混雑時にも、過度なリクエスト爆発を防ぎつつ正常に完了させられます。

音声ファイルの処理

の音声波形イラスト: 音声ファイルの処理

APIから返される音声ファイルは、生成ごとに直ちにレスポンスとして受け取ります。生成済みの音声ファイルはサーバー上に永続的に保存されませんので、必要に応じてダウンロードまたは処理してください。

長文のテキストを処理する場合は、4096文字ごとにリクエストを分割し、取得した音声ファイルを結合して使用します。

長文の分割と結合

1つのリクエストで扱えるテキストの上限は4096文字です。それを超える長文を音声化する場合は、クライアント側で文字列を適切な長さに分割し、それぞれを個別のAPIリクエストとして送信してください。生成された音声ファイルは、mp3やwavなどの形式で取得できますので、必要に応じてツールを用いて結合してください。

フォーマットの変換

出力フォーマットは response_format パラメータで mp3, wav, opus, flac, pcm の中から選択できます。生成済みの音声ファイルのフォーマットを変換したい場合は、取得後のファイルに対して別途変換ツールを使用してください。APIのレスポンスは常に選択した形式で返されます。

ストリーミングの非サポート

本APIはストリーミングに対応していません。音声ファイルの生成が完了するまで待機し、完了後にファイル全体を取得する形式となります。リアルタイム性の高い対話型アプリケーションでは、生成待ち時間を考慮した設計が必要です。

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。 あなたのアイデアをコードなしで自由に形に変えていきましょう。

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

23言語

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

出典および参考資料

  1. Wikipedia
  2. TRON developer hub: TRC-20
  3. openai-python on GitHub
  4. Node.js documentation
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. Creative Commons Attribution 4.0
  7. ISO 639 language codes
  8. openai-node on GitHub
  9. OpenAI API reference: create speech
  10. LibriTTS-R corpus (OpenSLR 141)
  11. LibriVox public-domain audiobooks
  12. IETF RFC 7845: Ogg Opus

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