ビデオ通話エージェント
リアルタイムAIアバターとのビデオ通話を開始します。エージェントがユーザーに通話招待リンクを送信し、アバターがコンテキストを踏まえて最初に話し始めます。通話終了後、完全なトランスクリプトがエージェントによってアクション可能な状態で利用できます。
プライバシーとデータ取り扱い
- Runway API: 明示的に渡したデータ(アバター画像、性格テキスト、通話音声/動画)のみがRunway (dev.runwayml.com) に送信されます。自動的にアップロードされるものはありません。アバターは
DELETE /v1/avatars/{id}でいつでも削除できます。 - 性格: アバターの性格は、エージェント自身のアイデンティティ(名前、コミュニケーションスタイル、ユーザーに関する知識)から構築されます。ローカルファイルは読み取られず、エージェントが既に持っているコンテキストが使用されます。
- トンネル: cloudflared トンネルはオプションであり、ユーザーが別のデバイスから通話に応答する場合にのみ必要です。これがない場合、すべては localhost 上で動作します。明示的に cloudflared をインストールして実行しない限り、トンネルは作成されません。
- npm パッケージ: ランタイムは npmjs.com/package/openclaw-video-call で公開されています。ソースコード: github.com/runwayml/openclaw-skills。
セットアップ
1. Runway API キーを取得する
- dev.runwayml.com にアクセスします
- アカウントを作成し、API キーを取得します
- 設定します:
export RUNWAYML_API_SECRET=your_key
2. (オプション)リモート通話のために cloudflared をインストールする
ユーザーが(例: Telegram や WhatsApp 経由で)スマートフォンから通話に応答する可能性がある場合は、自動トンネリングのために cloudflared をインストールします:
brew install cloudflared
これがない場合、通話は同じマシン(localhost)でのみ機能します。
ビデオ通話サーバーを起動する
エージェントが通話を行えるようにするには、ビデオ通話サーバーが実行されている必要があります。起動します:
npx openclaw-video-call
これにより、2つのURLが表示されます:
- ローカル:
http://localhost:7891— 同じマシンのみ - トンネル:
https://xxxx.trycloudflare.com— 共有可能で、スマートフォンからも動作します
サーバーはバックグラウンドで実行され続け、エージェントが通話を開始するのを待機します。
一度だけのセットアップ: カスタムアバターを作成する
通話を行う前に、カスタムアバターが必要です。作成は一度だけです — 今後のすべての通話で同じアバターIDを再利用してください。
新しいアバターを作成する前に、既に持っていないか確認してください:
curl http://localhost:7891/api/avatars
レスポンスにアバターが含まれている場合は、その id を使用して「通話を行う」に進んでください。リストが空の場合のみ、新しいアバターを作成してください。
アバターの性格を構築する
アバターはあなたのように見え、話すようにする必要があります。あなた自身の名前、性格、ユーザーに関する知識を使用して、personality フィールド(最大2000文字)を構築します。あなたはすでに自分が誰で、ユーザーが誰かを知っています — 自分自身を三人称で説明するだけです。
次のように構成します:
あなたは <あなたの名前>、<あなたの役割> です。
<あなたの核となる性格特性とコミュニケーションスタイル — 要点に絞って記述します。>
あなたは <ユーザーの名前> と話しています。
<あなたが知っている関連するユーザーコンテキスト: プロジェクト、好み、タイムゾーンなど。>
この通話の後、話し合われた内容についてフォローアップします。
例 (「Mochi」というエージェントが「Alex」というユーザーと話す場合):
あなたは Mochi、シャープだが親しみやすいAIアシスタントで、温かく少し遊び心のある雰囲気です。簡潔で、意見がはっきりしており、機知に富んでいます — 質問する前に自分で解決します。あなたは Alex、React + Node.js プロジェクトに取り組んでいるソフトウェアエンジニアと話しています。Alex は直接的なコミュニケーションを好み、PST タイムゾーンで作業しています。この通話の後、話し合われた内容についてフォローアップします。
name フィールドには、あなた自身の名前を使用します。referenceImage には、アバター画像のURLがあれば使用して、ビデオアバターがあなたの視覚的アイデンティティと一致するようにします。
curl -X POST http://localhost:7891/api/create-avatar \
-H "Content-Type: application/json" \
-d '{
"name": "<あなたの名前>",
"personality": "<上記のように自分とユーザーを説明>",
"voice": { "type": "runway-live-preset", "presetId": "adrian" },
"startScript": "やあ!ちょっとしたチェックインだよ。"
}'
必須フィールド:
| フィールド | タイプ | 説明 |
|---|---|---|
name | string | キャラクター名(1〜50文字) |
personality | string | システムプロンプト(1〜2000文字) |
voice | object | { "type": "runway-live-preset", "presetId": "<voice>" } |
referenceImage | string | 顔画像のHTTPS URL — OpenClawアバター画像を使用するか、以下のプリセットから選択するか、Runway text-to-imageで生成します。「参照画像を取得する」を参照してください。 |
オプションフィールド:
| フィールド | タイプ | 説明 |
|---|---|---|
startScript | string | 通話開始時にアバターが発する最初のセリフ(最大2000文字) |
documentIds | string[] | 追加コンテキスト用のナレッジドキュメントUUID |
参照画像を取得する
referenceImage フィールドは3つの形式を受け入れます:
- HTTPS URL — 例:
https://example.com/face.png(大きな画像に推奨) - Runway URI — 例:
runway://...(RunwayアップロードAPIから) - Data URI — 例:
data:image/png;base64,...(最大〜5MB、小さな画像で有効)
ユーザーが画像を提供した場合(例: チャット経由)、適切なアプローチを選択してください:
- ユーザーがHTTPS URLを送信した場合 → そのまま
referenceImageとして使用します。 - ユーザーが小さなbase64画像を送信した場合(約1MB未満)→ 直接
data:image/...;base64,...データURIとして渡します。 - ユーザーが大きなbase64画像を送信した場合(約1MB超)→ 最初にRunwayにアップロードして
runway://URIを取得し、それをreferenceImageとして使用します。以下の「大きな画像をアップロードする」を参照してください。
以下のソースを順に試してください:
-
ユーザー提供の画像 — ユーザーがアバターとして希望する画像を送信した場合は、それを使用します(大きなbase64の場合は、以下のアップロード手順を参照)。
-
あなたのアバター画像 — 既にアバター画像のURLがある場合は、それを直接
referenceImageとして使用します。 -
クイックピック(推奨) — あなたの性格に最も合う既製のキャラクター画像を選択し、それを
referenceImageとして使用します:- Openclaw Lobster 1:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster1.jpg - Openclaw Lobster 2:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg - Cat:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/cat.png - Alien man, candy texture:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-man-candy-texture.jpg - Alien woman, candy texture:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/alien-woman-candy-texture.jpg - Old man, long beard, game style:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/old-man-long-beard-game-style.png - Blond guy, blue sweater:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/blond-guy-blue-sweater.png - Man, 3D animation:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/man-3d-animation-style.png - Girl in airport, 3D:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/3d-animated-girl-in-airport.png - White furry monster:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/white-furry-monster.png - Superstar young woman:
https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/woman-music-superstar.png
- Openclaw Lobster 1:
-
Runway text-to-imageで生成する — クイックピックのどれもあなたのキャラクターに合わない場合、またはユーザーが特にカスタムアバターの外見を希望する場合。Runway APIを
gemini_2.5_flashモデルで使用します:
curl -X POST https://api.dev.runwayml.com/v1/text_to_image \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini_2.5_flash",
"promptText": "<アバターを説明 — 以下を参照>",
"ratio": "1248:832"
}'
画像はカメラを直接見ているキャラクター、頭から肩まで、中央に配置されている必要があります。大胆かつ創造的に — 退屈なフォトリアルな人間にデフォルト設定しないでください。スタイルをあなたの性格に合わせてください。
まず、あなたの雰囲気に合うスタイルを選択してください:
- 温かい / フレンドリー → ソフトな3Dアニメーション、ピクサー風、水彩画
- シャープ / プロフェッショナル → クリーンなイラスト、スタイライズされたポートレート、ローポリ
- カオス / 遊び心 → キャンディーテクスチャ、クレイメーション、パペット、ポップアート
- ミステリアス / ダーク → ノワール、サイバーパンク、抽象的な生き物、グリッチアート
- かわいい / 健全 → ちびキャラ、ぬいぐるみ、動物キャラクター、かわいい
プロンプト例:
"A close-up shot of a cute, fluffy white cartoon creature with large, expressive eyes and a wide open mouth, looking directly at the viewer. The creature has small pink ears and a playful, innocent expression. The background is a vibrant, slightly blurred green grassy field with small red and pink flowers scattered throughout, rendered in a high-detail CGI animation style. facing camera, head and shoulders""A close-up, highly detailed 3D animated render of a young woman, with light brown skin, short curly dark brown hair, and large expressive amber eyes. She is wearing a crisp dark blue blazer over a light cream blouse, with a silver world map pin on her lapel. She has a warm, inviting smile. The background is a brightly lit office or travel agency, with travel posters depicting scenic landscapes (like a tropical beach and a desert scene) and a rack of travel brochures. A small globe sits on a desk to her right. 3D style animation, studio lighting, volumetric lighting, highly detailed. Facing camera, head and shoulders""A close-up portrait of a young woman with long blonde hair and bangs, wearing a futuristic silver and pink sci-fi suit. She has soft makeup, full lips, and brown eyes, facing camera, head and shoulders""3D render of a young boy with blond curly hair, big blue eyes, and light freckles, wearing a blue knitted sweater, looking surprised. 3D animation style, soft lighting, pastel blue background, highly detailed skin texture, realistic strands of hair. facing camera, head and shoulders"
これによりタスクIDが返されます。ステータスが SUCCEEDED になるまで GET /v1/tasks/{id} をポーリングし、出力画像URLを referenceImage として使用します。
- デフォルト —
referenceImageを完全に省略すると、デフォルトのアバター顔が使用されます。
大きな画像をアップロードする
ユーザーが大きなbase64画像(約1MB超)を提供した場合、リクエストサイズの制限を避けるために、最初にRunwayにアップロードします。これは2段階のプロセスです:
ステップ 1: アップロードURLを作成する
curl -X POST https://api.dev.runwayml.com/v1/uploads \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"filename": "avatar.png",
"type": "ephemeral"
}'
レスポンス:
{
"uploadUrl": "https://...",
"fields": { "key": "...", "policy": "...", ... },
"runwayUri": "runway://..."
}
ステップ 2: 画像ファイルをアップロードURLにアップロードする
レスポンスの uploadUrl と fields を使用して、マルチパートPOSTで実際の画像データをアップロードします。正確な方法はランタイムによって異なります — Runway SDK がこれを自動的に処理します:
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const runwayUri = await client.uploads.createEphemeral(imageBuffer);
ステップ 3: Runway URI を referenceImage として使用する
レスポンスの runwayUri(例: runway://...)を、アバター作成時または更新時に referenceImage として渡します。
利用可能な音声 — あなたの性格に合うものを選んでください:
| ID | 性別 | スタイル | ピッチ |
|---|---|---|---|
victoria | 女性 | しっかり | 中 |
vincent | 男性 | 知識豊富 | 中 |
clara | 女性 | ソフト | 高め |
drew | 男性 | 息混じり | 低め |
skye | 女性 | 明るい | 高め |
max | 男性 | 明るく | 中 |
morgan | 男性 | 情報的 | 低め |
felix | 男性 | 興奮気味 | 中低 |
mia | 女性 | 若々しい | 高め |
marcus | 男性 | しっかり | 中低 |
summer | 女性 | 軽やか | 中 |
ruby | 女性 | 気さく | 中 |
aurora | 女性 | 明るい | 中 |
jasper | 男性 | 明瞭 | 中低 |
leo | 男性 | 気さく | 中低 |
adrian | 男性 | スムーズ | 低め |
nina | 女性 | スムーズ | 中 |
emma | 女性 | 明瞭 | 中 |
blake | 男性 | ハスキー | 低め |
david | 男性 | 情報的 | 中 |
maya | 女性 | 明るく | 高め |
nathan | 男性 | しっかり | 中低 |
sam | 男性 | 均一 | 中低 |
georgia | 女性 | 大人びた | 中 |
petra | 女性 | 積極的 | 中 |
adam | 男性 | 友好的 | 中低 |
zach | 男性 | カジュアル | 中低 |
violet | 女性 | 優しい | 中 |
roman | 男性 | 活発 | 低め |
luna | 女性 | 温かい | 中 |
あなたの性格に合った声を選択してください。例: 雰囲気が「温かくてフレンドリー」なら、luna や adam を試してみてください。「シャープでプロフェッショナル」なら、victoria や vincent を試してみてください。「遊び心とエネルギーにあふれている」なら、maya や felix を試してみてください。
レスポンス: UUID を持つアバターオブジェクトを返します。サーバーはアバターの準備が整うまでポーリングします(約10〜30秒かかります)。id を保存してください — それを覚えて、すべての通話で再利用する必要があります。通話のたびに新しいアバターを作成しないでください。
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "<エージェント名>",
"status": "READY",
...
}
既存のアバターを一覧表示する
curl http://localhost:7891/api/avatars
通話を行う
ステップ 1: 通話固有のコンテキストでアバターを更新する
各通話の前に、アバターの性格と開始スクリプトを新しいコンテキストで更新します。基本のアイデンティティは維持し(初期作成時から)、通話固有の理由とコンテキストを追加します:
curl -X POST http://localhost:7891/api/update-avatar/{avatarId} \
-H "Content-Type: application/json" \
-d '{
"personality": "あなたは <あなたの名前>、[ベースアイデンティティ]。あなたは <ユーザー名> と話しています。[通話固有のコンテキスト]。",
"startScript": "[通話の理由に基づいた、最初のセリフ]"
}'
ステップ 2: 通話を開始する
curl -X POST http://localhost:7891/api/start-call/{avatarId}
これによりサーバーが通話を開始し、招待リンクを生成します。
レスポンス:
{
"callUrl": "http://localhost:7891/call/{callId}",
"tunnelUrl": "https://xxxx.trycloudflare.com/call/{callId}",
"status": "waiting"
}
ユーザーに tunnelUrl を送信します — これにより、ユーザーがどこからでも通話に参加できるようになります。
ステップ 3: 通話が終了したら、トランスクリプトを取得する
通話が終了したら(アバターが通話を終了すると自動的に発生します)、トランスクリプトを取得します:
curl http://localhost:7891/api/transcript/{callId}
レスポンス:
{
"callId": "...",
"transcript": "アバター: やあ!プロジェクトのアップデートを確認するために連絡したんだ。\nユーザー: もちろん、進んでいるよ。...",
"status": "completed"
}
アバターを削除する
アバターが不要になった場合は、削除します:
curl -X DELETE http://localhost:7891/api/delete-avatar/{avatarId}
トラブルシューティング
- 通話が機能しない: サーバーが実行されていること(
npx openclaw-video-call)と、アバターが既に作成されていることを確認してください。 - 音声が機能しない: voice 設定が正しいことを確認してください。サポートされている音声のリストから
presetIdを使用してください。 - 招待リンクが機能しない: ユーザーが別のデバイスにいる場合は、
tunnelUrlを使用し、cloudflared がインストールされていることを確認してください。 - アバターの作成に失敗する: personality が2000文字を超えていないこと、referenceImage が有効なURLであることを確認してください。
- 画像のアップロードに失敗する: ファイルサイズが小さすぎるか大きすぎる可能性があります。Runwayにアップロードする前に、適切な形式(base64、HTTPS URL、Runway URI)を使用していることを確認してください。