API リファレンス

ベース URL は https://api.vocallab.ai です。すべてのリクエストには Authorization: Bearer vl_live_... が必要です（API Keys を参照）。

GET /api/v1/ping

接続と認証のテスト。ポイント残高を返します。

{ "ok": true, "points": 12345, "unit": "points (1 pt ≈ 1 second of audio)" }

GET /api/v1/voices

使用できるボイス（公開カタログと、あなた自身のクローンボイスおよびデザインしたボイス）。返された id を生成時の voice として使います。カタログのボイスは slug も指定できます。

{ "voices": [
  { "id": "Ashley", "slug": "warm-natural-female-explainer-voice-for-youtube-podcasts",
    "name": "Warm Natural Female Explainer Voice for YouTube & Podcasts",
    "type": "preset", "languages": ["en"], "category": "Narration" },
  { "id": "default-abc123__my-voice", "name": "My Narrator", "type": "clone", "languages": ["en"] }
] }

GET /api/v1/models

選択可能な音声モデル。key を POST /api/v1/tts の model として渡します（既定は v-pro）。API キーは 3 つすべてを利用できます。違いについては Voice Models を参照してください。

{ "default": "v-pro", "models": [
  { "key": "v-studio", "label": "VocalLab Studio", "steerable": true,  "costMultiplier": 1 },
  { "key": "v-pro",    "label": "VocalLab Pro",    "steerable": false, "costMultiplier": 1 },
  { "key": "v-lite",   "label": "VocalLab Lite",   "steerable": false, "costMultiplier": 0.5 }
] }

POST /api/v1/tts

音声を生成します。

フィールド	必須	備考
`text`	はい	最大 2,000 文字。各呼び出しは単一のリクエストとして合成されます — 長いスクリプトはテキストを分割して複数回呼び出してください
`voice`	はい	`/api/v1/voices` のボイス `id`
`model`	いいえ	`v-studio`（最新・ステアリング対応・200 以上の言語）、`v-pro`（既定 — 最高音質・15 言語）、または `v-lite`（高速・ポイント ½）。`GET /api/v1/models` を参照
`speed`	いいえ	数値 `0.5`〜`1.5`（刻み `0.05`）。省略時はボイスの既定値
`temperature`	いいえ	数値 `0.7`〜`1.5`（刻み `0.05`）。高いほど表現豊かで変化が大きい。省略時はボイスの既定値
`format`	いいえ	`MP3`（既定）、`WAV`、`FLAC`、`OGG_OPUS`、`LINEAR16`、`PCM`、`ALAW`、`MULAW` のいずれか
`bit_rate`	いいえ	整数 `32000`〜`320000`。`MP3` と `OGG_OPUS` のみ（他の形式では無視）
`sample_rate`	いいえ	`8000`、`16000`、`22050`、`24000`、`32000`、`44100`、`48000`（Hz）のいずれか

curl -X POST https://api.vocallab.ai/api/v1/tts \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from VocalLab","voice":"Ashley"}'

音声をインライン（base64）で返すほか、id も返します。ホスト URL はアップロードの完了後に表示されます。取得するには GET /api/v1/tts/:id をポーリングしてください。

各リクエストは 2,000 文字が上限で、ちょうど1 回の音声合成に対応します — 隠れた分割やファンアウトはないため、呼び出しあたりのコストとレイテンシは予測可能なまま保たれます。リクエストはポイント残高に対して計測され、公平利用のキューを通るため、重い自動化がアプリをブロックすることはありません。長いスクリプトをナレーションするには、2,000 文字以下の断片に分割し、別々の呼び出しとして送信してください（毎分 60 リクエストのレート制限を守ってください）。

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "format": "MP3", "model": "v-pro", "points_used": 12 }

モデルとコスト。 v-lite は v-pro/v-studio の半分のポイントで課金されます（points = ⌈ characters ÷ 30 ⌉、÷ 15 ではなく）。v-studio は表現／ステアリングの指示に従う唯一のモデルです — Voice Models と Voice Steering を参照してください。

間（ポーズ）

text の中に自己終了タグ <break /> を入れると、正確な長さの無音を挿入できます。

{ "text": "少し考えさせてください <break time=\"1.5s\" /> はい、考えました。", "voice": "Ashley" }

秒またはミリ秒で指定 — 1.5s = 1500ms。
1リクエストあたり最大 20個 のbreakタグ、対応する全言語で利用可能。
breakタグは2,000文字の上限に含まれ、字幕/SRTからは除去されます。

GET /api/v1/tts/:id

生成のステータスと、準備完了後のホスト音声 URL。

{ "id": "...", "status": "ready", "audio_url": "https://...", "format": "MP3" }

GET /api/v1/me

あなたのポイント残高とプラン。

エラー

ステータス	意味
`401`	API キーが未指定または無効
`402`	ポイント不足
`403`	Studio プランではない
`413`	テキストが長すぎる
`429`	レート制限に到達（キーごとに 60 / 分）

エラーは { "error": { "code": "...", "message": "..." } } の形式になります。

料金

生成はポイント残高から課金され、テキストの長さ（最終的な音声の長さではなく）から計算されます:

points = ⌈ characters ÷ 15 ⌉      (API レート — 1 ポイントあたり約 15 文字)

⌈ ⌉ は次の整数ポイントへ切り上げます。Web アプリは 1 ポイントあたり 17 文字を使うため、API にはわずかな（約 13%）プレミアムが乗ります。ポイントは上流の呼び出しの前に計測されます — 残高を超えるリクエストは 402 を返し、生成されることはありません。各レスポンスには正確な points_used が含まれます。音声は平均で 1 秒あたり約 15〜17 文字のため、1 ポイント ≈ 音声 1 秒ですが、正確な課金は常に上記の式に従います。詳しくは Credits & Minutes を参照してください。