StoryTone API クイックスタート

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

このページでは、StoryTone API を最短で実装するための手順を解説します。API キーの取得から最初の音声生成、OpenAI SDK への連携まで、具体的なコード例を用いて手順を追います。物語の雰囲気に合わせた8種類の声や、mp3、wav などの対応形式についても記載しています。

レート制限やエラー処理、音声の選択方法、速度調整の設定値など、実運用で必要な設定値を網羅します。コンテンツクリエーターが、童話や物語の音声コンテンツを効率的に作成・統合するためのガイドとしてご利用ください。

StoryTone API クイックスタート

よくある質問

APIキーはどのように取得しますか?

https://playkkff.com/get-api-key/ でGoogleまたはメール登録してください。キーはダッシュボードに表示され、AuthorizationヘッダーにBearer付きで設定します。1アカウントにつき有効なキーは1つで、新しいキーを発行すると旧キーは即時無効になります。

最初のリクエストはどのように行いますか?

POST https://api.playkkff.com/v1/audio/speech へJSONボディを送信します。model、input、voice、response_format、speedを指定します。認証にはAPIキーを使用し、テキストは4096文字以内で送信してください。

OpenAI SDKはどのように使用しますか?

OpenAI SDKのbase_urlを https://api.playkkff.com/v1 に変更して使用できます。APIキーを設定し、speechエンドポイントにアクセスすることで、既存のコードをほぼ変更せずに統合可能です。

音声ファイルの形式はどれが推奨ですか?

mp3は汎用性が高く、wavは高品質、opusは軽量です。flacは非圧縮、pcmは生データ向けです。用途に合わせてresponse_formatで選択してください。mp3は多くのプレイヤーで再生可能です。

エラーが発生した場合、どう対処しますか?

エラー時は課金されません。料金は全額返金されます。エラーメッセージを確認し、パラメータやネットワーク接続を確認してください。問題が解決しない場合はサポートまでご連絡ください(メールのみ)。

レート制限を超えるとどうなりますか?

1分あたり60リクエストの制限があります。トップアップ前は1分あたり10リクエストです。制限を超えると429エラーが発生します。処理は逐次行われるため、負荷が高いと待ち時間が生じます。

音声はどのように選択しますか?

GET /v1/voices で利用可能な8種類の声を確認できます。aria、nova、luna、sage、felix、milo、atlas、orionから選択します。物語の雰囲気に合わせて適切な声を選んでください。

速度はどのように調整しますか?

speedパラメータで0.25から4.0の範囲で調整可能です。デフォルトは1.0です。物語のペースに合わせて速度を変更し、聞き取りやすい速度に設定してください。

音声ファイルはどのようにダウンロードしますか?

APIレスポンスのボディに音声データが含まれます。直接保存するか、ファイルとして処理してください。mp3やwavなど、指定した形式で返されます。

レスポンスの形式はどうなっていますか?

音声ファイルが直接レスポンスボディに返されます。ヘッダーにはContent-Typeが含まれます。エラー時はエラーメッセージが返されます。成功時は音声データが返ります。

音声の長さは制限されていますか?

1リクエストあたり4096文字までです。それ以上の場合は分割して送信し、音声を結合してください。分割合成により、より長い物語も作成可能です。

音声の品質はどのように確認しますか?

生成された音声ファイルを再生して確認してください。wavやflacは高音質です。mp3は圧縮形式です。品質は音声設定に依存します。

音声の速度はどのように変更しますか?

speedパラメータで調整します。0.25から4.0の範囲で設定可能です。物語のトーンに合わせて速度を調整し、最適な再生速度を見つけてください。

音声の形式はどのように変更しますか?

response_formatパラメータでmp3、wav、opus、flac、pcmを選択できます。用途に応じて適切な形式を選んでください。mp3は広く普及しており、wavは高音質です。

最初のリクエスト

curl

curl https://api.playkkff.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.playkkff.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.playkkff.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キーの取得

StoryTone APIを利用するには、まずAPIキーの取得が必要です。登録にはGoogleアカウントまたはメールアドレスとパスワードの2通りがあります。

Google認証での登録

Google認証での登録

Googleアカウントで登録すると、即座に$0.50の無料トライアルクレジットが付与されます。これは約5万文字分に相当し、7日間で有効です。

メールアドレスでの登録

メールアドレスでの登録

メールとパスワードでの登録の場合は、トライアルクレジットは付与されません。その代わりに、必要な時にUSDTでチャージして利用できます。

APIキーの確認

登録完了後、/get-api-key/ページでAPIキーを確認できます。キーは1アカウントにつき1つで、新しいキーを発行すると旧キーは直ちに無効になります。

最初のリクエスト

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

APIキーを取得したら、curlコマンドで最初の音声合成をテストできます。以下のコマンドは「tts-1」モデルを使用して、短く明確なテキストを音声ファイルに変換する例です。

リクエストボディにはモデル、音声、形式、そして生成したいテキストを指定します。失敗したリクエストは課金されないので、安心して最初の呼び出しを確認してください。

curlコマンドの例

次のコマンドを実行して、音声ファイルのダウンロードを試みましょう。YOUR_API_KEY部分には、取得したキーを挿入してください。

```bash curl -X POST "https://api.playkkff.com/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "おはようございます。今日はいい天気ですね。", "voice": "luna", "response_format": "mp3" }' \ -o output.mp3 ```

JSONボディの構造

リクエストボディはJSON形式で、以下の必須フィールドを含みます。modelは"tts-1"または"tts-1-hd"を指定します。voiceは8種類の preset のいずれかです。

inputフィールドには最大4096文字までのテキストをセットします。スペースや句読点も文字数としてカウントされる点に注意してください。

response_formatは"mp3", "wav", "opus", "flac", "pcm"のいずれかを指定します。デフォルトはmp3です。

  • model: "tts-1" または "tts-1-hd"
  • voice: "aria", "nova", "luna", "sage", "felix", "milo", "atlas", "orion"
  • input: 生成したいテキスト文字列
  • response_format: "mp3", "wav", "opus", "flac", "pcm"

レスポンスの形式

成功すると、音声データがバイナリ形式で返されます。通常は指定した拡張子(例: .mp3)のファイルとして保存されます。

エラーが発生した場合は、JSON形式のエラーメッセージが返されます。ステータスコードを確認し、必要な修正を行ってください。

OpenAI SDKとの連携

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

StoryTone APIはOpenAIのspeechエンドポイントと互換性があるため、既存のOpenAI SDKをそのまま利用できます。APIのbase_urlをhttps://api.playkkff.com/v1に変更し、APIキーを設定するだけで連携が完了します。

base_urlの変更

SDKの初期化時に、base_urlパラメータにhttps://api.playkkff.com/v1を指定します。これにより、通常のOpenAIサービスではなく、StoryToneの音声合成エンドポイントにリクエストが送信されます。

SDKのインストール

Python環境ではpip install openaiコマンドを実行して、最新のOpenAI Python SDKをインストールしてください。他の言語でも同様の公式SDKが利用可能です。

インストール後、環境変数またはコード内でAPIキーを設定するだけで準備は完了です。

コード例

以下は、Pythonで音声ファイルを生成する最小限のコード例です。tts-1モデルを使用して、指定した音声と速度で音声データを作成します。

生成された音声データはバイト列として返されるため、ファイルに保存するかストリームとして処理できます。

  • model: "tts-1"
  • voice: "luna"
  • input: "おはようございます"
  • response_format: "mp3"

音声ファイルの形式

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

StoryTone APIでは、mp3、wav、opus、flac、pcmの5つの音声フォーマットから選択できます。これにより、ブラウザでの再生や録音ソフトでの編集など、用途に合わせた最適な形式で音声ファイルを取得できます。

各フォーマットは、生成された音声データそのままを返すため、追加の変換作業が不要です。APIリクエストのresponse_formatフィールドに希望する形式を指定するだけです。

mp3のサポート

mp3は広く普及している圧縮形式で、Webブラウザやモバイルアプリでの再生に最適です。ファイルサイズが小さく、ネットワーク転送効率が良いため、多くのプラットフォームで標準的に使用されます。

  • 一般的なWebサイトやアプリでの再生に最適
  • ファイルサイズが小さく、保存や転送が効率的

wavのサポート

wavは非圧縮の音声形式で、高音質が求められる録音や編集作業に適しています。音声データの劣化がなく、そのまま編集ソフトウェアに読み込めるため、プロフェッショナルな制作現場で好まれます。

  • 非圧縮で高音質を維持
  • 編集ソフトとの互換性が高い

opus、flac、pcmのサポート

opusは高い圧縮効率を実現する形式です。flacはロスレス圧縮形式です。pcmは生音声データで、最も基本的な形式です。

  • opus: 高効率な圧縮でファイルサイズを最小化
  • flac: ロスレス圧縮で高音質を維持
  • pcm: 生音声データ、最も基本的な形式

エラー処理

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

API呼び出しで発生するエラーは、主にリクエスト形式の誤りや存在しない音声 ID の指定によるものです。ステータスコード 4xx を確認し、送信データを確認してください。

音声合成の処理中に内部エラーが発生した場合、そのリクエストは正常に完了したとみなされません。

一般的なエラー

400 エラーはパラメータの不足や不正を意味します。404 は存在しないエンドポイントです。

  • パラメータ不足: 必須フィールドが欠けている場合
  • 無効な音声: 指定された voice が存在しない場合

レート制限のエラー

1 分あたり 60 リクエストの制限を超えると、429 エラーが発生します。チャージ前アカウントは 1 分あたり 10 リクエストに制限されます。

制限超過時は、メッセージを待ってから再試行してください。

  • 60 リクエスト/分: 通常時の上限
  • 10 リクエスト/分: 初回チャージ前の制限

失敗時の返金

音声合成に失敗したリクエストは、課金対象外となります。失敗した場合は、料金が全額返金されます。

正常に完了したリクエストのみが課金対象となります。

  • 失敗: 料金が返金される
  • 成功: 課金対象となる
エラー処理

レート制限

の音声波形イラスト: レート制限

StoryTone APIは、安定したサービス提供のためレート制限を設けています。通常は1分間に60リクエストまで処理可能です。これにより、多数のクリエイターが同時に音声生成を行っても、品質が保たれます。

60リクエスト/分の制限

通常時、APIキー1つあたり1分間に60リクエストの制限があります。短くても長くても、この上限内で効率的に音声ファイルを生成できます。

チャージ前の制限

初回またはチャージ前の状態では、1分あたり10リクエストの制限がかかります。これはシステム負荷を軽減するための措置です。

制限の解除方法

USDT(TRC-20)でのチャージを行うと、制限が解除され、60リクエスト/分の通常速度に戻ります。チャージは数分で反映されます。

音声の選択

の音声波形イラスト: 音声の選択

StoryTone APIでは、物語の雰囲気やターゲット層に合わせた8種類の音声から選べます。LibriTTS-R(CC BY 4.0)やLibriVoxの録音データに基づいた声質です。

各音声は明確な役割を持ち、読み手によって異なる印象を与えます。適切な音声選択が、物語の没入感を高める鍵となります。

8つの音声のリスト

以下の8つの音声プリセットから、コンテンツのトーンに合うものを選択できます。

女性ボイス: aria(温かみのあるナレーター)、nova(明るく元気)、luna(柔らかいストーリーテリング)、sage(落ち着いた指示)。男性ボイス: felix(エネルギッシュな宣伝)、milo(親しみやすい会話)、atlas(ニュートラルなニュース)、orion(深みのあるドキュメンタリー)。

これらは8種類のプリセットです。SSMLは使用できません。

  • aria: 温かみのあるナレーター
  • nova: 明るく元気
  • luna: 柔らかいストーリーテリング
  • sage: カーム、教育的
  • felix: エナジーチック、プロモーション
  • milo: 親しみやすい会話調
  • atlas: ニュートラルなニューススタイル
  • orion: 深みのあるドキュメンタリー

音声の指定方法

APIリクエストのJSONボディでvoiceフィールドに音声名を指定します。例えば"voice": "luna"と設定すると、柔らかいストーリーテリングの音声で音声ファイルが生成されます。

言語を明示的に指定しない場合、文字コードに基づいて自動検出されますが、英語以外のラテン文字の場合はlanguageパラメータで明示してください。

音声の変更

各リクエストごとに異なる音声を指定できます。同じテキストでも、voiceパラメータを変えるだけで異なるキャラクターとして再生可能です。

音声の変更は即時反映され、追加の設定や読み込みは不要です。生成された音声には合成音声を示す不可視の透かしが埋め込まれます。

速度の調整

の音声波形イラスト: 速度の調整

StoryTone APIでは、speedパラメータを使って音声の再生速度を0.25倍から4.0倍の範囲で自由に調整できます。これは、童話の朗読リズムや物語の雰囲気に合わせて音声のテンポを最適化するために不可欠です。

速度を変更しても音声の質は維持されますが、生成時間やキャラクターの認識に影響を与えます。適切な速度設定は、子どもたちの聴覚体験を向上させる鍵となります。

速度パラメータの設定

APIリクエストのJSONボディにspeedフィールドを追加します。値は浮動小数点数で指定し、デフォルトは1.0です。例えば、speed: 0.8と設定すると、標準の80%の速度で音声が発話されます。

言語を指定する場合でも、速度パラメータは独立して機能します。languageフィールドとは別に設定するため、多言語の物語でも一貫したテンポを維持できます。

  • パラメータ名: speed
  • データ型: 浮動小数点数
  • デフォルト値: 1.0

速度の範囲

許容される速度の範囲は0.25から4.0です。0.25は通常の4分の1の速度、4.0は通常の4倍の速度になります。これ以外の値を送信するとエラーが発生します。

極端な速度変更でも、音声は歪まずに再生されます。ただし、4.0のような高速設定では、聞き取りにくさを感じる可能性があるため、テストをお勧めします。

  • 最小速度: 0.25
  • 最大速度: 4.0
  • 指定可能な値: 0.25〜4.0の任意の数値

速度の影響

速度を変更すると、音声の生成時間にも影響します。通常、1秒あたりの生成速度は一定ですが、速度が速いほど音声ファイルの長さが短くなります。,speed: 2.0の場合、音声は半分になります。

物語の雰囲気によっては、遅い速度が効果的ですが、長いテキストでは生成待ち時間が増える可能性があります。バランスの良い速度設定を試してみてください。

  • 生成時間: 速度に反比例
  • 音声の長さ: 速度に比例して変化
  • 推奨: テストによる調整

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。 物語の進行に合わせて、重要な部分では遅く、説明的な部分では速く調整することで、聴覚に配慮したコンテンツ作成が効率的になります。

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

23言語

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

出典および参考資料

  1. Wikipedia
  2. openai-python on GitHub
  3. curl documentation
  4. W3C WAI: making audio and video accessible
  5. TRON developer hub: TRC-20
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Creative Commons Attribution 4.0
  8. ISO 639 language codes
  9. OpenAI API reference: create speech
  10. LibriVox public-domain audiobooks
  11. openai-node on GitHub
  12. Node.js documentation

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