> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To build and serve your own model, start at /deploy/development/quickstart and /deploy/development/overview. Deploying is the default path: reactor init scaffolds a workspace, reactor auth login authenticates, and reactor model deploy registers the model, publishes the release with the weights/ folder, and activates it on Reactor's GPUs, in one command from that workspace. Docker must be running, because the publish step builds the image locally. Bump model.version in reactor.yaml before redeploying a change, because a release that already has an image is reactivated as it is. Deployment access is granted per account, so contact team@reactor.inc if a deploy is refused. Every key in reactor.yaml is documented at /deploy/platform/reactor-yaml. Model code imports reactor_runtime; Python client code imports reactor_sdk. The runtime overview explains the model interface. Running the model on your own machine with reactor run is optional and needs a GPU you attach with --gpus; /deploy/development/local-testing covers that loop and pairs a complete brightness model with a Python client test in a separate brightness-test workspace.
> Reactor hosts multiple models, each with its own connect slug (modelName) and command/event schema. The video model catalog — slug, typed SDK package, and links to its schema — is at /model-api-reference/overview. Robotics policy documentation starts at /robotics/overview; The launch policies are Cosmos Nano DROID (/robotics/cosmos/nano-policy-droid/), DreamZero DROID (/robotics/dreamzero/droid/), and FLUX Action DROID (/robotics/flux-action/droid/), organized by model family and embodiment. Some models expose one slug per experience (e.g. HappyOyster); always take the slug from the model's own pages, never guess it.
> Fastest path to a working app: `npx create-reactor-app my-app --model=<slug>` scaffolds a complete app with secure auth wired up. Typed TypeScript SDKs are published as @reactor-models/<model>; Python uses the base reactor-sdk package.
> Auth: exchange an API key (rk_...) for a JWT via POST https://api.reactor.inc/tokens from your server. Never put the API key in client-side code.
> Append .md to any docs URL for clean Markdown. Search these docs via the MCP server at https://docs.reactor.inc/mcp.

# PixVerse R2 Persona overview

> Make a character from one image, a voice, a name, and a persona, then talk to it over a live call.

**PixVerse R2 Persona** is a character that you talk to in real time. Create the character from an
image, a name, and a persona, and choose its voice from a selection of real-time voices.

The character speaks and reacts in real time. Talk to it over your computer's microphone, and it
hears you and answers. You can also talk to it through text. Each sentence that the character speaks
also arrives as a transcript, so you can show subtitles.

You can use a character in more than one session. Save its `character_id`, and attach the character
in a later session instead of creating it again.

The PixVerse R2 Persona reference has four pages. This overview comes first. The
[schema](https://docs.reactor.inc/model-api-reference/pixverse-r2-persona/schema.md) lists every command and message. The
[prompt guide](https://docs.reactor.inc/model-api-reference/pixverse-r2-persona/prompt-guide.md) covers the image, the persona,
and how to talk to the character. The [tutorial](https://docs.reactor.inc/model-api-reference/pixverse-r2-persona/tutorial.md)
covers a character, a microphone, and a call, step by step.

PixVerse R2 Persona uses the same wire protocol as every other Reactor model. You open a session
with the [`Reactor`](https://docs.reactor.inc/sdk-reference/reactor-class) class, send named commands, publish and receive
tracks, and receive messages. Its model name is **`reactor/pixverse-r2-persona`**. The
[`@reactor-models/pixverse-r2-persona` typed SDK](https://docs.reactor.inc/sdk-reference/typed-model-sdk) adds named methods
and React hooks to the same protocol.

## At a glance

| Spec | Value |
| - | - |
| Model name | `reactor/pixverse-r2-persona` |
| Pricing | |
| Frame rate | 25 fps |
| Resolution | 720 × 1280 for a `9:16` character (the default), or 1280 × 720 for `16:9` |
| Input | One image, a name, a persona, and a voice from `list_voices`. Then your `mic` track or `say`. |
| Input track | `mic`, 48 kHz mono |
| Output tracks | `main_video` and `main_audio` (48 kHz mono) |

The model name, `reactor/pixverse-r2-persona`, is the name that you pass to the SDK. It is also the
scope of a token. The short slug, `pixverse-r2-persona`, names the docs folder, the typed SDK, and
the row for the model on [Pricing and billing](https://docs.reactor.inc/resources/billing.md).

## Key features

> [card] A character from one image
>
> Upload one clear picture, and give the character a name, a persona, and a voice. The character
> is ready in a few seconds. Save its `character_id` to use it again.

> [card] Talk or type
>
> When you publish your microphone, the character answers your speech. You can also send a line
> with `say`. Each sentence that the character speaks also arrives as a `transcript` line for
> subtitles.

> [card] Calls you can repeat
>
> Start a call, end it, and start another call with the same character. `session_state` tells you
> when the character can hear you and when you receive its video and voice.

## Quick start

> [tab] npm
>
> ```shell theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
> npx create-reactor-app my-persona-app --model=pixverse-r2-persona
> ```

> [tab] pnpm
>
> ```shell theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
> pnpm create reactor-app my-persona-app --model=pixverse-r2-persona
> ```

Create a session token on your server. Then connect with the base JavaScript SDK or the
`@reactor-models/pixverse-r2-persona` typed SDK. Do not put your `rk_` API key in browser code. To
create tokens, see [Authentication](https://docs.reactor.inc/authentication.md).

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import { Reactor } from "@reactor-team/js-sdk";

const reactor = new Reactor({ modelName: "reactor/pixverse-r2-persona" });
const video = document.querySelector("video")!;
const audio = document.querySelector("audio")!;

reactor.on("trackReceived", (name, _track, stream) => {
  if (name === "main_video") {
    video.srcObject = stream;
    void video.play().catch(console.error);
  }
  if (name === "main_audio") {
    audio.srcObject = stream;
    void audio.play().catch(console.error);
  }
});

reactor.on("message", (message) => {
  if (message.type === "transcript") {
    const line = message.data as { text: string };
    showSubtitle(line.text); // Implement showSubtitle() in your UI.
  }
});

reactor.on("statusChanged", async (status) => {
  if (status !== "ready") return;

  // Publish the microphone before the call so that the first thing you say is heard.
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  await reactor.publishTrack("mic", stream.getAudioTracks()[0]);

  const image = await reactor.uploadFile(portraitFile); // A File from your file picker.
  await reactor.sendCommand("create_character", {
    image,
    name: "Ava",
    persona: "You are Ava, a street photographer in an old town. You love light and cameras.",
  });
  await reactor.sendCommand("start_call", {});
  // Now speak into the microphone, or send a line with `say` once `speech_ready` is true.
});

await reactor.connect(await getToken()); // Implement getToken() on your server.
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import {
  PixverseR2PersonaProvider,
  PixverseR2PersonaMainVideoView,
  usePixverseR2Persona,
  usePixverseR2PersonaTranscript,
} from "@reactor-models/pixverse-r2-persona";

export function App({ token, portraitFile }: { token: string; portraitFile: File }) {
  return (
    <PixverseR2PersonaProvider jwtToken={token} connectOptions={{ autoConnect: true }}>
      <Call portraitFile={portraitFile} />
    </PixverseR2PersonaProvider>
  );
}

function Call({ portraitFile }: { portraitFile: File }) {
  const { status, publish, uploadFile, createCharacter, startCall } = usePixverseR2Persona();

  usePixverseR2PersonaTranscript((line) => {
    showSubtitle(line.text); // Implement showSubtitle() in your UI.
  });

  async function call() {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
    await publish("mic", stream.getAudioTracks()[0]);
    const image = await uploadFile(portraitFile);
    await createCharacter({
      image,
      name: "Ava",
      persona: "You are Ava, a street photographer in an old town. You love light and cameras.",
    });
    await startCall();
  }

  return (
    <>
      <PixverseR2PersonaMainVideoView audioTrack="main_audio" muted={false} className="w-full" />
      <button disabled={status !== "ready"} onClick={() => void call()}>
        Call Ava
      </button>
    </>
  );
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import asyncio
import os
from reactor_sdk import Reactor, ReactorStatus

async def main():
    reactor = Reactor(model_name="reactor/pixverse-r2-persona",
                      api_key=os.environ["REACTOR_API_KEY"])
    said = False

    @reactor.on_status(ReactorStatus.READY)
    async def on_ready(status):
        image = await reactor.upload_file("ava.jpg")
        await reactor.send_command("create_character", {
            "image": image,
            "name": "Ava",
            "persona": "You are Ava, a street photographer in an old town. You love light and cameras.",
        })
        await reactor.send_command("start_call", {})

    @reactor.on_message
    def on_message(msg):
        nonlocal said
        if msg["type"] == "transcript":
            print("Ava:", msg["data"]["text"])
        if msg["type"] == "session_state" and msg["data"]["speech_ready"] and not said:
            said = True
            asyncio.ensure_future(
                reactor.send_command("say", {"text": "Hi Ava! What do you like to shoot?"})
            )

    await reactor.connect()
    await asyncio.Event().wait()  # run until interrupted

asyncio.run(main())
```

## How it works

1. Connect to `reactor/pixverse-r2-persona`. The first `session_state` has the phase `idle`. Publish
   your `mic` track now, so that the character hears you from the start of the call.
2. Call `list_voices` to see the voices. To use `default_voice`, skip this step. Upload one image.
   Then call `create_character` with the image, a name, and a persona. The phase moves to
   `character_ready` with `character_id` set. In a later session, call `attach_character` with that
   id instead.
3. Call `start_call`. The phase moves through `starting` and `connecting` to `live`. `speech_ready`
   becomes true during `connecting`, about 2 seconds after the call opens.
4. Talk. Speak into the microphone, or send a line with `say`. The character answers on `main_video`
   and `main_audio`. Each sentence also arrives as a `transcript` line.
5. Call `end_call`, or let the call end by itself. The character stays current, so `start_call`
   starts the next call.

> [!NOTE]
>
> The character does not speak first. It waits for your first turn. To have the character greet
> the person, wait until `speech_ready` and `video_receiving` are both true. Then `say` a short line
> such as "Hello!". The character answers that line.
>
> The character does not answer speech that comes before `speech_ready` is true. It does not hear a
> published microphone that sends no samples. Speak after the character finishes its answer. If you
> speak while it answers, it may not hear you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.