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 でも指定できます。

レスポンスには常に total・count・offset・has_more が含まれるので、推測せずにページングできます。type を除く同じパラメータが GET /api/v1/voices/clones と GET /api/v1/voices/designs でも使えます。

curl "https://api.vocallab.ai/api/v1/voices?q=narrator&limit=20" \
  -H "Authorization: Bearer vl_live_..."

{ "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 キーはすべてのモデルを利用できます。違いについては Voice Models を参照してください。

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

POST /api/v1/tts

音声を生成します。

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 リクエスト、Max では 120 リクエストのレート制限を守ってください）。

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions",
  "format": "MP3", "model": "v-pro", "points_used": 12 }

モデルとコスト。 v-flash は ¾（points = ⌈ characters ÷ 20 ⌉）、v-lite は半分（÷ 30）のポイントで課金されます（v-pro/v-studio は ÷ 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://...",
  "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions", "format": "MP3" }

GET /api/v1/tts/:id/audio

完成したクリップの音声バイトを直接ストリーミングします。base64 の audio_base64 ブロブの代わりに使えます。inline で配信され（ブラウザやメディアプレーヤーで再生）、HTTP の Range ヘッダーに対応しているのでシークできます。クリップがまだ処理中の間は 409 を返します。GET /api/v1/tts/:id をポーリングして status が ready になってからストリーミングしてください。

curl -L https://api.vocallab.ai/api/v1/tts/GENERATION_ID/audio \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.mp3

同じリンクは POST /api/v1/tts と GET /api/v1/tts/:id の stream_url としても返されます。

GET /api/v1/tts/:id/captions

生成した音声の字幕を .srt ファイルとして返します。キューは実際の発話に合わせて（合成時に返る単語単位のタイミングから）作られ、[emotion] マークアップや <break /> のポーズはすべて取り除かれるため、ファイルには話された言葉だけが入ります。

字幕は音声ファイルではなく保存済みのタイミングから作られるので、status がまだ pending の間でもすぐに利用できます。

curl -L "https://api.vocallab.ai/api/v1/tts/GENERATION_ID/captions" \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.srt

1
00:00:00,000 --> 00:00:01,240
Hello from VocalLab,

2
00:00:01,240 --> 00:00:03,100
this is your narrator speaking.

format=json の場合:

{ "id": "...", "mode": "phrase", "duration": 3.1,
  "srt": "1\n00:00:00,000 --> 00:00:01,240\nHello from VocalLab,\n\n...",
  "words": [ { "word": "Hello", "start": 0, "end": 0.32 } ] }

同じリンクは POST /api/v1/tts と GET /api/v1/tts/:id の captions_url としても返されます。1 回の呼び出しで音声と一緒に SRT を受け取るには、POST /api/v1/tts に "captions": true を渡してください。

単語タイミングが保存されていない生成（一部の古いクリップ）では 409 captions_unavailable を返します。音声には影響しません。

DELETE /api/v1/tts/:id

自分が所有する生成を完全に削除します。保存された音声ファイルとデータベースのレコードの両方を削除します。ダウンロード後の整理や、データ削除リクエストへの対応に便利です。存在しない、または自分のものではない id は 404 を返します。

curl -X DELETE https://api.vocallab.ai/api/v1/tts/GENERATION_ID \
  -H "Authorization: Bearer vl_live_..."

{ "ok": true, "id": "...", "deleted": true }

GET /api/v1/voices/languages

変更点: GET /api/v1/voices/languages は 470 以上の言語と、そのアクセントバリエーション（en-GB、pt-PT など）を返すようになりました。code は BCP-47 タグです。従来の値（EN_US、PT_BR など）と Other も引き続き使用できます。

クローンとボイスデザインに使える言語と録音の制限。ハードコードせずここを参照してください——Studio のアップロードフォームと同じ唯一の情報源です。

{ "languages": [
    { "name": "English", "code": "EN_US", "experimental": false },
    { "name": "Other",   "code": "AUTO",  "experimental": true }
  ],
  "sample_limits": { "max_samples": 1, "max_base64_length": 4194304,
                     "allowed_formats": ["mp3", "wav", "webm"] } }

ボイスデザイン

録音なしで、文章による説明から新しい声を作ります。2 回の呼び出しです：候補プレビューを生成し、気に入ったものを保存します。

POST /api/v1/voices/designs/previews

最大 3 つの候補ボイスを生成します。points を消費します——各プレビューは preview_text の実際の音声合成で、API レート（プレビュー 1 件あたり ⌈文字数 ÷ 15⌉）で課金されます。

この時点では何も保存されないためデザインスロットは消費しませんが、空きスロットが必要です。デザインがプラン上限に達している場合は 409 design_limit を返し、points は一切消費されません——保存できない声にお金を払う意味がないからです。

curl -X POST https://api.vocallab.ai/api/v1/voices/designs/previews \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A warm, unhurried British woman in her forties, low and reassuring, like a documentary narrator.","count":2}'

{ "previews": [
    { "preview_id": "...", "text": "Hello! This is a preview of my voice...",
      "preview_url": "https://api.vocallab.ai/api/v1/audio/..." }
  ],
  "points_used": 12, "expires_in": 1800 }

preview_id はまだ使えるボイスではなく、有効期間は約 30 分です。

保存しなかったプレビューは破棄されます。 次のセットを生成する前に、残したいものを保存してください——このエンドポイントを再度呼ぶと以前のプレビューは破棄されて preview_url は無効になり、1 つを保存すると同じバッチの残りも破棄されます。いずれの場合も何も残りません。

POST /api/v1/voices/designs

プレビューを永続ボイスとして保存します。points はかかりません（プレビューで課金済み）が、プランのデザインスロットを 1 つ使います。返される id は POST /api/v1/tts の voice としてすぐに使えます。

{ "id": "default-abc123__narrator", "name": "Documentary Narrator", "type": "designed",
  "languages": ["EN_US"], "created_at": "...",
  "preview_url": "https://api.vocallab.ai/api/v1/audio/...", "used": 3, "limit": 20 }

GET /api/v1/voices/designs

デザインしたボイスを新しい順に、スロット使用状況付きで返します：{ "voices": [...], "used": 3, "limit": 20 }。

DELETE /api/v1/voices/designs/:voiceId

プロバイダとライブラリからボイスを削除します。有料プランではスロットが 1 つ戻ります。{ "ok": true, "id": "...", "deleted": true } を返します。

ボイスクローン

短い録音 1 つから特定の声を再現します。クローンは points を一切消費しません——プランのクローンスロット数だけが制限です。権利を持つ声、または書面で許可を得た声のみをクローンしてください。

POST /api/v1/voices/clones

ほぼどんな音声ファイルでも使えます。 audio_base64 は録音の生の base64 で、data: プレフィックスは不要です——MP3・WAV・M4A・AAC・OGG・FLAC・WebM、MP4 の音声トラックなど。プロバイダがそのまま受け付けない形式はサーバー側でモノラル 16-bit WAV に変換されます。Web アプリがアップロード前にブラウザで行っているのと同じことなので、API が Studio より厳しくなることはありません。

• 先頭 30 秒に切り詰め——長いファイルを送っても構いませんが、使われるのは冒頭だけです
• ステレオをモノラルにダウンミックスし、32 kHz にリサンプル
• 大きすぎるファイルを縮小——24-bit のスタジオ WAV を手作業で準備する必要はもうありません

制限はデコード後のバイト数ではなく base64 文字列に対してで、最大 8,000,000 文字（およそ 6 MB のファイル）です。超えると 413 sample_too_large、音声として読めないファイルは 400 unreadable_audio を返します。

何かが変更された場合、レスポンスにその内容を示す audio_notes 配列が含まれます。長い録音の先頭 30 秒から作られたクローンが黙って出来上がることがないよう、ログに残しておく価値があります：

{ "id": "...", "name": "My Narrator", "type": "clone", "used": 2, "limit": 100,
  "audio_notes": ["Re-encoded to mono 16-bit WAV at 32 kHz — aac isn't a format the provider accepts.",
                  "Trimmed to the first 30s (the sample was 90s)."] }

curl -X POST https://api.vocallab.ai/api/v1/voices/clones \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"My Narrator\",\"language\":\"English\",\"samples\":[{\"audio_base64\":\"$(base64 -w0 sample.mp3)\"}]}"

{ "id": "default-abc123__my-narrator", "name": "My Narrator", "type": "clone",
  "languages": ["EN_US"], "created_at": "...", "used": 2, "limit": 100 }

GET /api/v1/voices/clones

クローンしたボイスを新しい順に、スロット使用状況付きで返します：{ "voices": [...], "used": 2, "limit": 100 }。

DELETE /api/v1/voices/clones/:voiceId

プロバイダとライブラリからボイスを削除します。有料プランではスロットが 1 つ戻ります。{ "ok": true, "id": "...", "deleted": true } を返します。

スロットは別枠です。 クローンボイスとデザインボイスが枠を共有することはありません——プランごとの数は プランと制限 を参照。無料プランの上限は生涯のもので、削除してもスロットは戻りません。ワークスペースではメンバーはオーナーのプラン上限内で作業し、デザインの points はオーナーの残高から引かれます。

points がかかる操作

GET /api/v1/me

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

エラー

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

料金

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

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

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