---
name: avacast
description: avacast (写真から作った AI アバターを日本語でリアルタイムに喋らせる API) を Web アプリに組み込む。「アバターに喋らせたい」「AI 接客・受付に顔を付けたい」「リップシンクする動画をブラウザに出したい」と言われたら使う。アバター作成・セッション・発話・有料化は avacast MCP の tool で行う
---

# avacast を組み込む

avacast MCP (`https://api.avacast.jp/v1/mcp`) の tool で進める。REST・SDK・料金・エラーの全文は `get_integration_guide` が返す。ここには tool を呼ぶだけでは分からないことだけ書く。

## つなぎ方

1. MCP の URL を追加すると、MCP クライアントがブラウザを開く。利用者が管理画面 (https://app.avacast.jp) のアカウントでログインして「許可する」を押せばつながる (OAuth)。**API キーは要らない**。アカウントが無ければ先に管理画面で登録してもらう
2. できることは管理画面と同じ役割で決まる。組織のオーナーはすべて、メンバーは見るだけ。複数の組織に入っている人は `list_organizations` で組織の ID を確かめ、各 tool の `organization_id` に渡す (1 つなら省略できる)
3. 利用者のサーバーから REST API を呼ぶための API キーは `create_api_key` で発行する (平文は 1 回だけ返る)。利用者に見せるときは前 16 文字までにする
4. OAuth を使えないクライアントは、管理画面の「API キー」で発行したキーを接続の `Authorization: Bearer sk_live_…` に付ける
5. 無料枠は同時 2 セッション・月 30 分・アバター作成可

## アバター

- `list_avatars` のプリセットで動作確認してから、利用者の写真で `create_avatar(image_base64, name)`。正面・顔がはっきり写った 1 枚。生成に数分かかるので `get_avatar` で `ready` を待つ
- 声は `list_voices` から `voice_id` を選んで `create_session` の `voice` に渡す

## セッションと発話

- `create_session(avatar_id)` → `session_id` と `client_token` と `webrtc` が返る。**API キーはサーバーだけが持ち、ブラウザに渡すのは `client_token`**
- `speak(session_id, text)` で喋る。キューに積まれ、`interrupt` で捨てる
- `end_session` を必ず呼ぶ。課金はセッションが開いていた分数 (発話の長さではない)。放置は 30 分で切れる

## Web に組み込むコード

利用者のサーバーが API キーで `POST /v1/sessions` を叩き、返った `client_token` をブラウザへ渡す。ブラウザ側:

```html
<video id="avatar" autoplay playsinline></video>
<script type="module">
  import { AvacastSession } from 'https://avacast.jp/sdk/v1.js';
  // client_token と webrtc は POST /v1/sessions のレスポンスから
  const session = new AvacastSession(client_token, {
    signalingUrl: webrtc.signaling_url,
    iceServers: webrtc.ice_servers,
  });
  session.attach(document.getElementById('avatar'));
  // 映像が届いてから (session.ready) 喋らせる。届く前の speak は 409 になる
  session.on('session.ready', () => session.speak('こんにちは。'));
  await session.start();
</script>
```

ブラウザから直接喋らせるときは `POST /v1/client/sessions/:id/speak` に `Authorization: Bearer <client_token>`。会話ロジックが顧客のフロントにある場合はこちらが 1 往復速い。

## 有料化

- 上限に当たったら `list_plans` で見せ、`create_checkout(plan)` が返す URL を利用者に開いてもらう。はじめての申し込みは Stripe Checkout (カード入力)、有料プランの間の上げ下げは管理画面の確認画面で、どちらも利用者が確定する
- 月間の接続時間の上限を下げるのは `set_spending_cap(minutes)`。上限に達すると新しいセッションが作れなくなり、それ以上は請求されない。上げる・外すのは返る `settings_url` を利用者に開いてもらう
- 請求書や解約は `get_billing_portal` の URL

## 使ってはいけないこと

- API キーをフロントのコードや公開リポジトリに書かない
- 利用者の代わりに Checkout や管理画面の URL を開こうとしない (本人の操作が要る)