Back to Details

integrate-character-embed

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Embed Characters in React (Avatars React SDK)

在React中嵌入虚拟形象（Avatars React SDK）

PREREQUISITES:
  • +check-compatibility
    — Project must have server-side capability (API key must never be exposed to the client)
  • +fetch-api-reference
    — Load the latest API reference from https://docs.dev.runwayml.com/api/ before integrating
  • +integrate-characters
    — Character (Avatar) must be created and session endpoint must exist
  • Project must use React (Next.js, Vite+React, Remix, etc.)
OPTIONAL:
  • +integrate-documents
    — Add knowledge base before embedding
Embed real-time avatar video calls in React applications using the 
@runwayml/avatars-react
SDK.
前置要求：
  • +check-compatibility
    — 项目必须具备服务端能力（API密钥绝对不能暴露给客户端）
  • +fetch-api-reference
    — 集成前请先从https://docs.dev.runwayml.com/api/加载最新的API参考
  • +integrate-characters
    — 必须先创建好Character（Avatar）且会话端点已存在
  • 项目必须使用 React（Next.js、Vite+React、Remix等）
可选要求：
  • +integrate-documents
    — 嵌入前先添加知识库
使用
@runwayml/avatars-react
SDK在React应用中嵌入实时虚拟形象视频通话。

Installation

安装

bash
npm install @runwayml/avatars-react
This is a client-side package. The server-side 
@runwayml/sdk
should already be installed from 
+integrate-characters
.
bash
npm install @runwayml/avatars-react
这是一个客户端包，服务端的
@runwayml/sdk
应该已经在
+integrate-characters
步骤中安装完成。

Option A: Simple — 
AvatarCall
Component

方案A：简单实现 —— 
AvatarCall
组件

The fastest way to embed a character. Handles WebRTC connection and renders a default UI automatically.
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function CharacterPage() {
  return (
    <AvatarCall
      avatarId="your-avatar-id-here"
      connectUrl="/api/avatar/session"
      onEnd={() => console.log('Call ended')}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
这是嵌入虚拟形象最快的方式，会自动处理WebRTC连接并渲染默认UI。
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function CharacterPage() {
  return (
    <AvatarCall
      avatarId="your-avatar-id-here"
      connectUrl="/api/avatar/session"
      onEnd={() => console.log('Call ended')}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

AvatarCall
Props

AvatarCall
属性

PropTypeDescription
avatarId
string
The Avatar UUID from the Developer Portal or API
connectUrl
string
Your server-side session endpoint (e.g., 
/api/avatar/session
)
onEnd
() => void
Called when the call ends normally
onError
(error: Error) => void
Called on connection or runtime errors
For custom avatars created in the Developer Portal, use the Avatar UUID as 
avatarId
.
属性类型说明
avatarId
string
来自开发者门户或API的虚拟形象UUID
connectUrl
string
你的服务端会话端点（例如 
/api/avatar/session
）
onEnd
() => void
通话正常结束时触发
onError
(error: Error) => void
连接或运行时出错时触发
对于在开发者门户中创建的自定义虚拟形象，请使用虚拟形象UUID作为
avatarId
。

Option B: Fully Custom — Hooks

方案B：完全自定义 —— Hooks

For full control over the UI, use 
AvatarSession
with hooks.
如果需要完全控制UI，可以搭配Hooks使用
AvatarSession
。

Components & Hooks

组件与Hooks

ExportTypeDescription
AvatarSession
ComponentProvider that manages the WebRTC session
AvatarVideo
ComponentRenders the avatar's video stream
UserVideo
ComponentRenders the user's camera feed
useAvatarSession
HookAccess session state: 
state
, 
sessionId
, 
error
, 
end()
useLocalMedia
HookControl user's media: 
isMicEnabled
, 
toggleMic()
导出项类型说明
AvatarSession
组件管理WebRTC会话的Provider
AvatarVideo
组件渲染虚拟形象的视频流
UserVideo
组件渲染用户的摄像头画面
useAvatarSession
Hook访问会话状态：
state
、
sessionId
、
error
、
end()
useLocalMedia
Hook控制用户媒体：
isMicEnabled
、
toggleMic()

Custom UI Example

自定义UI示例

tsx
'use client';

import {
  AvatarSession,
  AvatarVideo,
  UserVideo,
  useAvatarSession,
  useLocalMedia,
} from '@runwayml/avatars-react';
import type { SessionCredentials } from '@runwayml/avatars-react';

function CallUI() {
  const { state, end } = useAvatarSession();
  const { isMicEnabled, toggleMic } = useLocalMedia();

  return (
    <div className="relative w-full h-screen">
      {/* Avatar video takes full screen */}
      <AvatarVideo className="w-full h-full object-cover" />

      {/* User's camera in a small overlay */}
      <UserVideo className="absolute bottom-4 right-4 w-48 rounded-lg" />

      {/* Controls */}
      <div className="absolute bottom-4 left-4 flex gap-2">
        <button onClick={toggleMic}>
          {isMicEnabled ? 'Mute' : 'Unmute'}
        </button>
        <button onClick={end}>End Call</button>
      </div>

      {/* Connection state */}
      {state === 'connecting' && (
        <div className="absolute inset-0 flex items-center justify-center bg-black/50">
          Connecting...
        </div>
      )}
    </div>
  );
}

export function CustomAvatar({ credentials }: { credentials: SessionCredentials }) {
  return (
    <AvatarSession credentials={credentials} audio video>
      <CallUI />
    </AvatarSession>
  );
}
tsx
'use client';

import {
  AvatarSession,
  AvatarVideo,
  UserVideo,
  useAvatarSession,
  useLocalMedia,
} from '@runwayml/avatars-react';
import type { SessionCredentials } from '@runwayml/avatars-react';

function CallUI() {
  const { state, end } = useAvatarSession();
  const { isMicEnabled, toggleMic } = useLocalMedia();

  return (
    <div className="relative w-full h-screen">
      {/* 虚拟形象视频占满全屏 */}
      <AvatarVideo className="w-full h-full object-cover" />

      {/* 用户摄像头画面以小窗悬浮展示 */}
      <UserVideo className="absolute bottom-4 right-4 w-48 rounded-lg" />

      {/* 控制按钮 */}
      <div className="absolute bottom-4 left-4 flex gap-2">
        <button onClick={toggleMic}>
          {isMicEnabled ? '静音' : '取消静音'}
        </button>
        <button onClick={end}>结束通话</button>
      </div>

      {/* 连接状态提示 */}
      {state === 'connecting' && (
        <div className="absolute inset-0 flex items-center justify-center bg-black/50">
          连接中...
        </div>
      )}
    </div>
  );
}

export function CustomAvatar({ credentials }: { credentials: SessionCredentials }) {
  return (
    <AvatarSession credentials={credentials} audio video>
      <CallUI />
    </AvatarSession>
  );
}

Fetching Credentials for Custom UI

为自定义UI获取凭证

When using the hooks approach, you need to fetch credentials from your server endpoint and pass them to 
AvatarSession
:
tsx
'use client';

import { useState, useCallback } from 'react';
import type { SessionCredentials } from '@runwayml/avatars-react';
import { CustomAvatar } from './CustomAvatar';

export default function CharacterPage() {
  const [credentials, setCredentials] = useState<SessionCredentials | null>(null);
  const [loading, setLoading] = useState(false);

  const startCall = useCallback(async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/avatar/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ avatarId: 'your-avatar-id-here' }),
      });
      const data = await res.json();
      setCredentials(data);
    } catch (error) {
      console.error('Failed to connect:', error);
    } finally {
      setLoading(false);
    }
  }, []);

  if (credentials) {
    return <CustomAvatar credentials={credentials} />;
  }

  return (
    <button onClick={startCall} disabled={loading}>
      {loading ? 'Connecting...' : 'Start Conversation'}
    </button>
  );
}
使用Hooks方案时，你需要从服务端端点获取凭证并传递给
AvatarSession
：
tsx
'use client';

import { useState, useCallback } from 'react';
import type { SessionCredentials } from '@runwayml/avatars-react';
import { CustomAvatar } from './CustomAvatar';

export default function CharacterPage() {
  const [credentials, setCredentials] = useState<SessionCredentials | null>(null);
  const [loading, setLoading] = useState(false);

  const startCall = useCallback(async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/avatar/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ avatarId: 'your-avatar-id-here' }),
      });
      const data = await res.json();
      setCredentials(data);
    } catch (error) {
      console.error('连接失败：', error);
    } finally {
      setLoading(false);
    }
  }, []);

  if (credentials) {
    return <CustomAvatar credentials={credentials} />;
  }

  return (
    <button onClick={startCall} disabled={loading}>
      {loading ? '连接中...' : '开始对话'}
    </button>
  );
}

Integration Patterns

集成模式

Next.js App Router (Full Example)

Next.js App Router（完整示例）

Server route (
app/api/avatar/session/route.ts
): See 
+integrate-characters
for the complete server-side session creation code.
Client page (
app/character/page.tsx
):
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

const AVATAR_ID = process.env.NEXT_PUBLIC_AVATAR_ID || 'your-avatar-id';

export default function CharacterPage() {
  return (
    <div className="flex items-center justify-center min-h-screen">
      <AvatarCall
        avatarId={AVATAR_ID}
        connectUrl="/api/avatar/session"
        onEnd={() => window.location.reload()}
        onError={(error) => {
          console.error('Avatar error:', error);
          alert('Connection failed. Please try again.');
        }}
      />
    </div>
  );
}
服务端路由（
app/api/avatar/session/route.ts
）： 完整的服务端会话创建代码请查看
+integrate-characters
。
客户端页面（
app/character/page.tsx
）：
tsx
'use client';

import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

const AVATAR_ID = process.env.NEXT_PUBLIC_AVATAR_ID || 'your-avatar-id';

export default function CharacterPage() {
  return (
    <div className="flex items-center justify-center min-h-screen">
      <AvatarCall
        avatarId={AVATAR_ID}
        connectUrl="/api/avatar/session"
        onEnd={() => window.location.reload()}
        onError={(error) => {
          console.error('虚拟形象错误：', error);
          alert('连接失败，请重试。');
        }}
      />
    </div>
  );
}

Conditional Rendering (Show/Hide)

条件渲染（显示/隐藏）

tsx
'use client';

import { useState } from 'react';
import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function SupportPage() {
  const [showAvatar, setShowAvatar] = useState(false);

  return (
    <div>
      <h1>Customer Support</h1>

      {!showAvatar ? (
        <button onClick={() => setShowAvatar(true)}>
          Talk to an Agent
        </button>
      ) : (
        <AvatarCall
          avatarId="support-agent-id"
          connectUrl="/api/avatar/session"
          onEnd={() => setShowAvatar(false)}
          onError={(error) => {
            console.error(error);
            setShowAvatar(false);
          }}
        />
      )}
    </div>
  );
}
tsx
'use client';

import { useState } from 'react';
import { AvatarCall } from '@runwayml/avatars-react';
import '@runwayml/avatars-react/styles.css';

export default function SupportPage() {
  const [showAvatar, setShowAvatar] = useState(false);

  return (
    <div>
      <h1>客户支持</h1>

      {!showAvatar ? (
        <button onClick={() => setShowAvatar(true)}>
          联系客服
        </button>
      ) : (
        <AvatarCall
          avatarId="support-agent-id"
          connectUrl="/api/avatar/session"
          onEnd={() => setShowAvatar(false)}
          onError={(error) => {
            console.error(error);
            setShowAvatar(false);
          }}
        />
      )}
    </div>
  );
}

Error Handling

错误处理

Verbose Error Logging

详细错误日志

tsx
<AvatarCall
  avatarId="your-avatar-id"
  connectUrl="/api/avatar/session"
  onError={(error) => {
    console.error('Avatar error:', error);
    console.error('Error name:', error.name);
    console.error('Error message:', error.message);
    if (error.cause) {
      console.error('Cause:', error.cause);
    }
  }}
/>
tsx
<AvatarCall
  avatarId="your-avatar-id"
  connectUrl="/api/avatar/session"
  onError={(error) => {
    console.error('虚拟形象错误：', error);
    console.error('错误名称：', error.name);
    console.error('错误信息：', error.message);
    if (error.cause) {
      console.error('错误原因：', error.cause);
    }
  }}
/>

Debug Session State

调试会话状态

tsx
import { useAvatarSession } from '@runwayml/avatars-react';

function DebugPanel() {
  const { state, sessionId, error } = useAvatarSession();

  return (
    <pre style={{ fontSize: 12, position: 'fixed', top: 0, right: 0 }}>
      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
    </pre>
  );
}
tsx
import { useAvatarSession } from '@runwayml/avatars-react';

function DebugPanel() {
  const { state, sessionId, error } = useAvatarSession();

  return (
    <pre style={{ fontSize: 12, position: 'fixed', top: 0, right: 0 }}>
      {JSON.stringify({ state, sessionId, error: error?.message }, null, 2)}
    </pre>
  );
}

Browser Support

浏览器支持

BrowserMinimum Version
Chrome74+
Firefox78+
Safari14.1+
Edge79+
Users must grant microphone permissions when prompted. Camera permissions are needed if user video is enabled.
浏览器最低版本
Chrome74+
Firefox78+
Safari14.1+
Edge79+
用户收到提示时必须授予麦克风权限，如果启用了用户视频则需要摄像头权限。

Tips

提示

  • Always import the styles: 
    import '@runwayml/avatars-react/styles.css'
    when using 
    AvatarCall
  • 'use client'
    directive     is required in Next.js App Router for all components using the React SDK
  • Session max duration is 5 minutes — handle the 
    onEnd
    callback to show a reconnect option
  • Credentials are one-time use — if connection fails, fetch new credentials (create a new session)
  • For the full SDK source, examples, and issue tracking: github.com/runwayml/avatars-sdk-react
  • 始终导入样式：使用
    AvatarCall
    时需要导入
    import '@runwayml/avatars-react/styles.css'
  • Next.js App Router中所有使用该React SDK的组件都必须添加
    'use client'
    指令
  • 会话最长持续时间为5分钟 —— 请处理
    onEnd
    回调来展示重连选项
  • 凭证为一次性使用 —— 如果连接失败，请获取新的凭证（创建新会话）
  • 完整SDK源码、示例和问题追踪请访问：github.com/runwayml/avatars-sdk-react