> ## 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 tutorial

> Connect, publish a microphone, create a character, start a call, show subtitles, and handle refusals.

This walkthrough uses the base JavaScript SDK so that you can see each model command. It publishes a
microphone, creates a character from one image, and starts a call. Then it talks to the character by
voice and by text, and shows the answers as subtitles. The snippets build on each other in one
browser module.

Your app supplies three things that this page does not show:

* `getToken()`, which asks your server for a session token. The [Authentication](#authentication)
  section shows the server side.
* `portraitFile`, which is a `File` object from a file picker.
* A page with one `<video>` element, one `<audio>` element, and a `<p id="subtitle">` element.

## Installation and setup

Install the base JavaScript SDK:

```shell theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
npm install @reactor-team/js-sdk
```

To start from a complete example app instead, run
`npx create-reactor-app my-persona-app --model=pixverse-r2-persona`.

## How PixVerse R2 Persona works

A session holds one character and one call at a time. `create_character` or `attach_character` sets
the character. `start_call` opens a call. Then `session_state` moves through `starting` and
`connecting` to `live`. During the call, the character speaks on `main_video` and `main_audio`.
While `speech_ready` is true, the character hears your `mic` track and your `say` commands.

A command reply tells you only that the model accepted the request. It does not tell you that the
character is live or that it answered. For that, wait for the messages that follow, such as
`session_state` with `speech_ready` and the `transcript` lines. The `session_state` snapshot always
agrees with these messages, so keep a copy of it and draw your UI from that copy.

## Authentication

Create the session token on your server so that your `rk_` API key never reaches the browser. This
route exchanges the key for a short-lived token that can only start `reactor/pixverse-r2-persona`
sessions. The Python SDK exchanges the key for you, so it needs no route.

```typescript app/api/token/route.ts theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import { NextResponse } from "next/server";

export async function POST() {
  const response = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: {
      "Reactor-API-Key": process.env.REACTOR_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      authorization_details: [
        { type: "session", resources: { models: { match: ["reactor/pixverse-r2-persona"] } } },
      ],
    }),
  });
  if (!response.ok) {
    return NextResponse.json({ error: await response.text() }, { status: response.status });
  }
  const { jwt, expires_at } = await response.json();
  return NextResponse.json({ jwt, expires_at }, { headers: { "Cache-Control": "no-store" } });
}
```

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

async def main():
    reactor = Reactor(model_name="reactor/pixverse-r2-persona", api_key=os.environ["REACTOR_API_KEY"])
    await reactor.connect()  # The SDK exchanges the key for a token.

asyncio.run(main())
```

See [Authentication](https://docs.reactor.inc/authentication.md) for token lifetimes and for how to keep a token fresh for a
whole session.

## 1. Connect and show the tracks

Connect to `reactor/pixverse-r2-persona`. Attach `main_video` to the video element and `main_audio`
to the audio element. Before a call, `main_video` streams black frames in the aspect ratio that you
set, and `main_audio` is silent.

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

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

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);
  }
});

let lastRefusal: ReactorError | undefined;
reactor.on("error", (error) => {
  if (error.operation === "sendCommand") lastRefusal = error;
});

type SessionState = {
  phase: string;
  character_id: string | null;
  speech_ready: boolean;
  mic_forwarding: boolean;
  end_reason: string | null;
  last_error: { code: string; reason: string; retryable: boolean } | null;
};
let state: SessionState | undefined;
reactor.on("message", (message) => {
  if (message.type === "session_state") state = message.data as SessionState;
});

await reactor.connect(await getToken());
```

Connect from a user action, such as a button click. Because of the user action, the browser lets the
page play audio and lets you open the microphone. Before you send commands, wait for the `ready`
status. When you connect, the model sends a `session_state` with phase `idle`.

## 2. Publish the microphone

Publish `mic` before `start_call`, so that the first thing you say reaches the character. If a
published microphone sends nothing, the character hears nothing. If the user declines the
microphone, the call still works with `say`.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
let mic: MediaStreamTrack | null = null;
try {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: { echoCancellation: true, noiseSuppression: true, channelCount: 1 },
  });
  mic = stream.getAudioTracks()[0];
  await reactor.publishTrack("mic", mic);
} catch {
  mic = null; // The call still works with `say`.
}
```

`session_state.mic_forwarding` turns true after your microphone reaches the character during a call.
Use it to show a "listening" indicator.

## 3. Create a character

Read the voices, upload the image, and create the character. The reply is `character_ready` with
`character_id`. Save that id, because step 6 uses it again. The helper below waits for a phase. The
later steps use it too:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
function waitForPhase(phase: string): Promise<SessionState> {
  return new Promise((resolve) => {
    const onMessage = (message: { type: string; data: unknown }) => {
      if (message.type !== "session_state") return;
      const next = message.data as SessionState;
      if (next.phase !== phase) return;
      reactor.off("message", onMessage);
      resolve(next);
    };
    reactor.on("message", onMessage);
  });
}

const voicesReply = await reactor.sendCommand("list_voices", {});
const { default_voice } = voicesReply!.data as { default_voice: string };

const image = await reactor.uploadFile(portraitFile);
const created = await reactor.sendCommand("create_character", {
  image,
  name: "Ava",
  persona: "You are Ava, a street photographer in an old town. You love light and cameras.",
  speaking_style: "Friendly and relaxed. Short, natural sentences.",
  voice: default_voice,
  aspect_ratio: "9:16",
});
if (created?.type !== "character_ready") {
  throw new Error(lastRefusal?.message ?? "The model refused this command.");
}
const characterId = (created.data as { character_id: string }).character_id;
```

The model creates the character in 2 to 4 seconds. If the model refuses the request, the command
resolves `undefined`, and the `error` event carries the code, such as `invalid_image` or
`content_policy`.

## 4. Start the call

Send `start_call`. The phase moves to `starting`, then to `connecting`. When the first frame of the
character arrives, the phase moves to `live`. When capacity is free, this takes 8 to 10 seconds.
`speech_ready` turns true during `connecting`, so the character can listen before its video shows.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const live = waitForPhase("live");
await reactor.sendCommand("start_call", {});
await live;
```

`start_call` declares no reply, so the command resolves `undefined` both when the model accepts it
and when the model refuses it. A refusal, such as `busy` or `no_character`, arrives on the `error`
event. While the call waits for capacity, `session_state.wait_position` gives the place in line.

## 5. Talk and show subtitles

Each sentence that the character speaks arrives as a `transcript` line. The next line with the same
`turn_id` and `sentence_index` replaces a line with `final` false. Use those two fields as the key
for your subtitles:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
type Transcript = {
  text: string;
  final: boolean;
  turn_id: string | null;
  sentence_index: number;
  prompt_id: string | null;
};
const lines = new Map<string, string>();

reactor.on("message", (message) => {
  if (message.type === "transcript") {
    const line = message.data as Transcript;
    lines.set(`${line.turn_id}:${line.sentence_index}`, line.text);
    subtitle.textContent = line.text;
  }
  if (message.type === "question_received") {
    lines.clear(); // A new answer starts.
  }
  if (message.type === "input_declined") {
    subtitle.textContent = "(That was declined.)";
  }
});
```

Now speak into the microphone, or send a line of text. `say` works while `speech_ready` is true:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const said = await reactor.sendCommand("say", { text: "Hi Ava! What do you like to shoot?" });
if (said === undefined) throw new Error(lastRefusal?.message ?? "The model refused this command.");
```

The character does not speak first. To open the call, wait until `speech_ready` and
`video_receiving` are both true. Then immediately send one short line, such as "Hello!". The
character answers that line, so the user hears a greeting instead of silence.

The `said` reply carries a `prompt_id`. The `question_received`, `transcript`, and `input_declined`
messages for that turn carry the same `prompt_id`. A turn from the microphone has a null
`prompt_id`. `question_received` arrives about 0.3 seconds after `say`. The first `transcript` line
arrives about 5 seconds after `say`, when the character starts to speak.

The character also sends `character_action`, which describes a gesture in words, such as a wave. You
can show it or ignore it.

## 6. End the call, and call again

Send `end_call` to end the call. The reply is `call_ended` with `end_reason` and `duration_seconds`.
The character stays current, so `start_call` starts another call with it.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const ended = await reactor.sendCommand("end_call", {});
mic?.stop();
```

A call can also end without `end_call`. It ends after 300 seconds with nothing said
(`idle_seconds`), at 1,800 seconds (`call_max_seconds`), or on a failure. Watch `session_state` to
see when a call ends, and offer "Call again":

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("message", (message) => {
  if (message.type !== "session_state") return;
  const next = message.data as SessionState;
  if (next.phase === "ended") {
    // next.end_reason is "ended_by_client", "idle", or "max_duration". Offer "Call again".
  }
  if (next.phase === "failed" && next.last_error) {
    const { code, retryable } = next.last_error;
    // character_not_found: create the character again. upstream_capacity: wait a few seconds, then retry.
  }
});
```

In a new session, send `attach_character` with the saved id instead of uploading the image again.
The reply is `character_ready` at once. The model checks the id when the next call starts. If the
id is unknown, that call fails with `character_not_found`, and the model clears `character_id`:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
// Later, in a new session of the same model:
await reactor.sendCommand("attach_character", { character_id: characterId });
await reactor.sendCommand("start_call", {});
```

## Surfacing refusals

When the model refuses a command, only that command fails, and only your client gets the refusal.
Read the refusal from the `error` event whose `operation` is `"sendCommand"`. Show it next to the
control that sent the command. Do not show it as a connection problem, because the session is still
connected.

A call failure is different. The model accepted `start_call`, but the call then ended on an error.
The phase becomes `failed`, and `session_state.last_error` carries the code, a reason, and whether a
retry may work.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("error", (error) => {
  // error.code is the model's code, such as "not_live".
  if (error.operation === "sendCommand") showRefusal(error.code, error.message);
});
```

The [schema](https://docs.reactor.inc/model-api-reference/pixverse-r2-persona/schema.md#refusals) lists every code.


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