CapCut-TTS

CapCut TTS Wrapper API

English README

CapCut Web に email / password でログインし、session を維持しながら最新の Web TTS 経路で音声を取得する、セルフホスト用ラッパー API です。

旧来の token + websocket 方式ではなく、現在の CapCut Web の認証フローと storyboard/v1/tts/multi_platform に合わせています。

できること

• CapCut Web に email / password でログインして session を維持
• GET /v2/speakers で利用可能な話者一覧を取得
• GET /v2/speakers/:speakerId/preview で話者プレビュー音声を取得
• GET /v2/synthesize で MP3 音声を取得
• POST /v2/synthesize で JSON body を使って MP3 音声を取得
• GET /v1/synthesize で旧 token + websocket フローの WAV 音声を取得
• buffer と stream の 2 つのレスポンス方式に対応
• session を capcut-session.json に保存して再利用
• CapCut の bundle から抽出した設定を capcut-bundle-config.json に保存して再利用

注意事項

• このプロジェクトは CapCut の公式 SDK / 公式 API ラッパーではありません
• CapCut 側の仕様変更により、突然動かなくなる可能性があります
• 利用にあたっては、各自の責任で公開範囲や運用方法を判断してください

クイックスタート

1. 依存関係をインストール

npm install

2. .env を作成

cp .env.example .env

3. CapCut の認証情報を設定

最低限、次の 2 つを設定してください。

[email protected]
CAPCUT_PASSWORD=your-password

通常は他の値はデフォルトのままで動きます。

4. 開発サーバーを起動

npm run dev

5. API を呼び出す

# 話者一覧を取得
curl "http://localhost:8080/v2/speakers"

# 話者プレビューを取得
curl "http://localhost:8080/v2/speakers/ICL_en_female_jiaoao/preview" --output preview.mp3

# GET で音声合成
curl "http://localhost:8080/v2/synthesize?text=こんにちは&speaker=labebe&method=buffer" --output voice.mp3

# POST で音声合成
curl -X POST "http://localhost:8080/v2/synthesize" \
  -H "Content-Type: application/json" \
  -d '{"text":"こんにちは","speaker":"labebe","method":"buffer"}' \
  --output voice.mp3

旧フローを使う場合は、LEGACY_DEVICE_TIME と LEGACY_SIGN を設定したうえで次のように呼び出せます。

curl "http://localhost:8080/v1/synthesize?text=こんにちは&type=0&pitch=10&speed=10&volume=10&method=buffer" --output voice.wav

bundle 設定の扱い

このプロジェクトは、CapCut Web の bundle から見つかった各種設定値を capcut-bundle-config.json に保存しながら動作します。

ここで保存しているのは、たとえば次のような値です。

• login / account 系 endpoint path
• editor / TTS 系 endpoint path
• appvr, version_name, sdk_version などの version 系値
• editor API の sign 生成に使う recipe
• 音声カテゴリ ID 一覧

capcut-bundle-config.json は、実際にページへアクセスして取得した bundle 情報のキャッシュです。ファイルが存在し、その内容がキャッシュ有効期間内であれば、毎回あらためて CapCut のページへアクセスして bundle を取り直さなくても動作します。

逆に、次のような場合は live で再取得を試みます。

• capcut-bundle-config.json がまだ存在しない
• キャッシュが期限切れになった
• 必要な設定値がまだ十分に揃っていない

つまり、通常運用では HAR は必須ではありません。現在は HAR なしでも、サーバーが CapCut のページにアクセスできれば bundle 情報を動的に取得し、その結果を capcut-bundle-config.json に保存して以後の起動や通信で再利用します。

HAR と capcut:extract の位置づけ

npm run capcut:extract は、HAR から capcut-bundle-config.json を生成したいときの補助コマンドです。

npm run capcut:extract

これは必須コマンドではありません。主な用途は次のとおりです。

• 初回に HAR から既知の設定を投入して起動を安定させたいとき
• live アクセスを行う前に bundle 情報を手元で固定したいとき
• CapCut 側の変更調査をするとき

API

ベース URL

http://<host>:<port>/

エンドポイント

GET /v2/speakers レスポンス

[
  {
    "id": "ICL_en_female_jiaoao",
    "resourceId": "7530105822785899777",
    "effectId": "7530105822785899777",
    "name": "ラベベさん",
    "description": "英語の明るい女性ボイス",
    "style": "",
    "language": "en"
  }
]

GET /v2/speakers/:speakerId/preview

指定した話者のプレビュー音声を返します。初回アクセス時のみ音声を生成して speaker-preview-temp/<speakerId>.mp3 に保存し、以降はキャッシュを返します。ファイルの更新日時が CAPCUT_SPEAKER_PREVIEW_MAX_AGE_DAYS を超えた場合は再生成します。

GET /v2/synthesize クエリパラメーター

POST /v2/synthesize リクエストボディ

GET と同じフィールドを JSON body で送信します。

{
  "text": "こんにちは",
  "speaker": "labebe",
  "speed": 10,
  "volume": 10,
  "method": "buffer"
}

レスポンス

/v1/synthesize は旧 token + websocket フローを使い、audio/wav を返します。
LEGACY_DEVICE_TIME と LEGACY_SIGN が未設定の場合は 503 Service Unavailable を返します。

話者解決ルール

type / speaker 互換表

type は次の固定話者にマップされます。speaker を使う場合は alias 列の値を指定できます。

これら以外の話者は、/v2/speakers を参照してください。

環境変数

主要な環境変数は次のとおりです。

npm scripts

補足

• 起動時に session の warmup を試み、その後は SESSION_REFRESH_INTERVAL_MINUTES ごとに検証します
• 起動時や実行時に bundle 情報が必要になると、capcut-bundle-config.json を読み込み、必要に応じて live 抽出して更新します
• LEGACY_DEVICE_TIME と LEGACY_SIGN を設定すると、起動時に legacy token の取得も試みます
• speaker に effectId / resourceId / speaker name を直接渡しても選択できます
• 現在の CapCut Web TTS は MP3 を返し、レスポンスの Content-Disposition は inline です