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

> Tracks, session lifecycle, commands, refusals, and messages for PixVerse R2 Persona.

This page is the protocol reference for PixVerse R2 Persona. It covers the tracks, the session
lifecycle, the commands, the refusals, and the messages. The model streams the character on
`main_video` and `main_audio`. It hears you on `mic`. When the session reaches `ready`, send
commands with `reactor.sendCommand()`.

## Tracks

| Track | Direction | Type |
| - | - | - |
| `mic` | Input | Audio, 48 kHz mono. Your microphone. While a call runs, the character hears it. |
| `main_video` | Output | Video, 25 fps during a call. 720 × 1280 for a `9:16` character, or 1280 × 720 for `16:9`. |
| `main_audio` | Output | Audio, 48 kHz mono. The character's voice, in sync with the video. |

Before a call and between calls, `main_video` streams black frames in the aspect ratio that you set,
at 5 fps, and `main_audio` carries silence. During a call, from `live` on, the tracks carry the
character at 25 fps. While the video stalls, the last frame repeats.

Publish `mic` before `start_call` whenever the user may speak. If a published microphone sends
nothing, the character hears nothing. The character does not answer speech that comes before
`speech_ready` is true.

## Session lifecycle

A session holds one **character** and at most one **call** at a time:

* `create_character` makes the character from one image, a voice, a name, and a persona.
  `attach_character` makes a saved character current.
* `start_call` starts a call. The call ends on `end_call`, on a failure, or when the session ends.
  It also ends after `idle_seconds` with nothing said to the character, or at `call_max_seconds`.
  The character stays current, so the next `start_call` starts a call with the same character.

`session_state` reports the phase:

| Phase | Meaning |
| - | - |
| `idle` | No character. |
| `creating_character` | The model creates the character. This takes 2 to 4 seconds. |
| `character_ready` | A character is current, and no call runs. |
| `starting` | The call waits for generation capacity. `wait_position` says the place in line. |
| `connecting` | The call is open, but the character's video has not arrived yet. `speech_ready` can turn true in this phase. |
| `live` | The character's video plays. Talk to the character. |
| `ending` | The call closes. This usually takes less than a second. |
| `ended` | The call ended without a failure. `end_reason` says how. The character stays current. |
| `failed` | The call failed. `end_reason` and `last_error` say why. The character stays current, except after `character_not_found`. |

Several clients can join one session. Each client gets `session_state` when it connects, sees every
broadcast message, and hears the character. The character hears the `mic` track of every client.
When a client leaves, the call continues. When the session ends, the call ends.

Replies go only to the client that sent the command. `question_received`, `transcript`,
`character_action`, `input_declined`, and `session_state` go to everyone.

## Commands

| Command | Typed method | Description | Reply |
| - | - | - | - |
| `list_voices` | `listVoices()` | List every voice that you can give a character. | `voices` |
| `create_character` | `createCharacter()` | Create a character from one image, a voice, a name, and a persona. | `character_ready` |
| `attach_character` | `attachCharacter()` | Make a saved character current. | `character_ready` |
| `start_call` | `startCall()` | Start a call with the current character. | none (`session_state` follows) |
| `say` | `say()` | Say something to the character, as text. | `said` |
| `end_call` | `endCall()` | End the call. | `call_ended` |
| `get_state` | `getState()` | Read the session state. | `session_state` |

The typed SDK, `@reactor-models/pixverse-r2-persona`, has one method for each command on
`PixverseR2PersonaModel` and on the `usePixverseR2Persona()` hook. `startCall` resolves `undefined`.
The other methods resolve their reply message. If the model refuses the command, they resolve
`undefined`.

Parameter and message fields keep their snake\_case names. Pass the `FileRef` that `uploadFile`
returns as `image`. `PixverseR2PersonaModel` also has `publishMic(track)` and `unpublishMic()` for
the `mic` track.

### `list_voices`

List every voice, and get `default_voice`. You can send it in any phase. The model replies with
`voices`. Each voice has `voice` (the name to pass to `create_character`), `description`, and
`languages`.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const reply = await reactor.sendCommand("list_voices", {});
const { voices, default_voice } = reply!.data as {
  voices: { voice: string; description: string; languages: string[] }[];
  default_voice: string;
};
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { listVoices } = usePixverseR2Persona();
const reply = await listVoices();
const voices = reply?.voices ?? [];
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reply = await reactor.send_command("list_voices", {})
voices = reply["data"]["voices"]
default_voice = reply["data"]["default_voice"]
```

### `create_character`

Create a character from one image, a voice, a name, and a persona, and make it current. You can send
it in `idle`, `character_ready`, `ended`, and `failed`. The phase moves to `creating_character`.
About 2 to 4 seconds later, the model replies with `character_ready`, which carries `character_id`.
The phase then becomes `character_ready`. If the model refuses the request, the previous character
stays current, if there is one.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `image` | upload reference | none | Required. One image of the character. PNG, JPEG, or WEBP, at most 20 MiB and 40 megapixels. The model applies the orientation that a phone photo records. The model crops the center of the image to `aspect_ratio`. |
| `name` | string | none | Required. Up to 20 characters. The character uses it to introduce itself. |
| `persona` | string | none | Required. Who the character is and how it behaves, up to 4,000 characters. Write only what the character knows and does. The character can read a stage direction in this field aloud. |
| `speaking_style` | string | `""` | Language, tone, and reply length, up to 1,000 characters. If blank, the character uses short, natural sentences in the language that the user speaks. |
| `voice` | string | `""` | A `voice` from `list_voices`. If blank, the model uses `default_voice`. |
| `refusal_reply` | string | `""` | What the character says when the content policy declines something that you say to it, up to 500 characters. If blank, the character politely changes the subject. |
| `aspect_ratio` | `"9:16"` or `"16:9"` | `"9:16"` | The shape of the character's video: 720 × 1280 or 1280 × 720. |

Upload the image with `uploadFile()`. Then pass the [`FileRef`](https://docs.reactor.inc/sdk-reference/types#fileref) that
it returns.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const image = await reactor.uploadFile(portraitFile);
const reply = 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: "marin",
  aspect_ratio: "9:16",
});
const characterId = (reply?.data as { character_id: string } | undefined)?.character_id;
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { uploadFile, createCharacter } = usePixverseR2Persona();
const image = await uploadFile(portraitFile);
const character = await createCharacter({
  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: "marin",
  aspect_ratio: "9:16",
});
const characterId = character?.character_id;
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
image = await reactor.upload_file("ava.jpg")
reply = 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.",
    "speaking_style": "Friendly and relaxed. Short, natural sentences.",
    "voice": "marin",
    "aspect_ratio": "9:16",
})
character_id = reply["data"]["character_id"]
```

### `attach_character`

Make a character from an earlier session current, without creating it again. You can send it in
`idle`, `character_ready`, `ended`, and `failed`. The model replies with `character_ready` at once.
Its `character_name`, `voice`, and `aspect_ratio` are null, because the model does not know them.

The model checks the id when the next call starts. If the id is unknown, that call fails with
`last_error` code `character_not_found`, and the model clears `character_id`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `character_id` | string | none | Required. A `character_id` from `session_state` in an earlier session of this model. |

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("attach_character", { character_id: savedCharacterId });
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { attachCharacter } = usePixverseR2Persona();
await attachCharacter({ character_id: savedCharacterId });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("attach_character", {"character_id": saved_character_id})
```

### `start_call`

Start a call with the current character. You can send it in `character_ready`, `ended`, and
`failed`. The command resolves when the model accepts the request. Then `session_state` moves
through `starting`, `connecting`, and `live`.

`speech_ready` turns true during `connecting`, about 2 seconds after the call opens. When capacity
is free, `start_call` to `live` takes 8 to 10 seconds. A wait for capacity in `starting` adds to
that time. The wait lasts up to 120 seconds.

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

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { startCall } = usePixverseR2Persona();
await startCall();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("start_call", {})
```

### `say`

Say something to the character, as text. You can send it while `speech_ready` is true, during
`connecting` or `live`. When the model delivers the text, it replies with `said`, which carries the
`prompt_id` of the turn. Then the character sends `question_received` and speaks its answer on
`main_audio`. It sends one `transcript` line for each sentence. If the content policy declines the
text, the character sends `input_declined` and says its refusal reply instead.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `text` | string | none | Required. What you say, up to 800 characters and 800 bytes of UTF-8 (about 260 Chinese characters). |

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const reply = await reactor.sendCommand("say", { text: "Hi Ava! What do you like to shoot?" });
const promptId = (reply?.data as { prompt_id: string } | undefined)?.prompt_id;
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { say } = usePixverseR2Persona();
const said = await say({ text: "Hi Ava! What do you like to shoot?" });
const promptId = said?.prompt_id;
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reply = await reactor.send_command("say", {"text": "Hi Ava! What do you like to shoot?"})
prompt_id = reply["data"]["prompt_id"]
```

### `end_call`

End the call. You can send it in any phase, and you can safely send it again. After the call ends,
the model replies with `call_ended`, which carries `end_reason` and `duration_seconds`. The
character stays current.

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

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { endCall } = usePixverseR2Persona();
const ended = await endCall();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("end_call", {})
```

### `get_state`

Read the session state. You can send it in any phase. The model replies with `session_state`. You
rarely need this command, because the model sends `session_state` when you connect and on every
change.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const state = await reactor.sendCommand("get_state", {});
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { getState } = usePixverseR2Persona();
const state = await getState();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
state = await reactor.send_command("get_state", {})
```

## Refusals

When the model refuses a command, nothing changes, and the command fails. Only the client that sent
the command gets the error. The error carries a stable `code` and a `reason` that you can show to
your user. The model never refuses `list_voices`, `end_call`, or `get_state`.

| Command | Codes |
| - | - |
| `create_character` | `invalid_input`, `invalid_image`, `invalid_voice`, `busy`, `content_policy`, `upstream_rejected` |
| `attach_character` | `invalid_input`, `busy` |
| `start_call` | `busy`, `no_character` |
| `say` | `invalid_input`, `text_too_long`, `not_live`, `send_failed` |

* `invalid_input`: a blank `name`, `persona`, or `text`, or an id that is not a `character_id`.
* `invalid_image`: the model cannot read the image, or the image is over 20 MiB or 40 megapixels.
* `invalid_voice`: the voice is not in `list_voices`.
* `text_too_long`: the text is over 800 bytes.
* `busy`: a call is starting or running, or the model is creating a character.
* `no_character`: `start_call` when no character is current.
* `not_live`: `say` while no call is listening (`speech_ready` is false).
* `send_failed`: the model could not deliver the text. Retryable.
* `content_policy`: the content policy declined the image or text.
* `upstream_rejected`: the generation service refused the image or text.

`create_character`, `attach_character`, and `say` can also fail with three upstream codes.
`upstream_unavailable` means that the model could not reach the generation service. A retry may
work. `upstream_auth` and `upstream_protocol` mean a deployment problem on the Reactor side of the
contract. Report them with `trace_id`.

In JavaScript, a refusal fires the `error` event with `operation: "sendCommand"` and the code. Then
the awaited command resolves `undefined`. A command that declares a reply resolves `undefined` only
when the model refuses it. `start_call` declares no reply, so it also resolves `undefined` on
success. For `start_call`, only the `error` event shows a refusal. In Python, `send_command()`
raises a `ReactorError` with the code.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("error", (error) => {
  if (error.operation === "sendCommand") showRefusal(error.code, error.message);
});

const said = await reactor.sendCommand("say", { text });
if (said === undefined) return; // Refused. The error listener has the reason.
```

See [Replies and refusals](https://docs.reactor.inc/sdk-reference/using-the-sdk.md#replies-and-refusals).

### Failures

A failure that no command caused is not a refusal. It ends the call, sets the phase to `failed`, and
sets `last_error` on `session_state`. `last_error` has these fields:

| Field | Type | Meaning |
| - | - | - |
| `code` | string | A stable code to branch on, from the table below. |
| `origin` | string | `request` (the input was invalid), `state` (not allowed now), `upstream` (the generation service refused or failed), or `platform` (a failure on the Reactor side). |
| `reason` | string | A sentence to show. |
| `retryable` | boolean | Whether a retry without changes may work. |
| `upstream_code` | string or null | The code from the generation service, if it gave one. |
| `trace_id` | string or null | Identifies the request when you report the failure. |

| Code | When |
| - | - |
| `upstream_capacity` | No capacity is free now, or none came free within the 120-second wait after `start_call`. Retryable. |
| `character_not_found` | An attached `character_id` does not exist for this model. The model clears `character_id`. Create the character again. |
| `media_join_failed` | The model could not set up the media for the call. Retryable. |
| `no_video` | The character's video did not arrive within 45 seconds after the call opened. Retryable. If this happens repeatedly, the cause may be a declined image or persona. |
| `media_lost` | The character's video stopped for `stall_seconds`, or its media connection dropped. Retryable. |
| `upstream_interrupted` | The generation service ended the call early. Retryable. |
| `upstream_unavailable` | The model could not reach the generation service. Retryable. |
| `upstream_auth`, `upstream_protocol` | A deployment problem on the Reactor side of the contract. Report it with `trace_id`. |
| `platform_failed` | A failure on the Reactor side. Retryable. |

## Messages

| Message | Sent to | When it arrives |
| - | - | - |
| `session_state` | everyone | On connect, on every change, and in reply to `get_state`. |
| `character_ready` | the caller | Reply to `create_character` and `attach_character`: `character_id`, `character_name`, `voice`, `aspect_ratio`. |
| `voices` | the caller | Reply to `list_voices`: `voices` and `default_voice`. |
| `said` | the caller | Reply to `say`: the `prompt_id` of the turn. |
| `question_received` | everyone | The character received one of your turns: `turn_id`, and the `prompt_id` from `say`, or null for speech on `mic`. |
| `transcript` | everyone | One sentence that the character spoke. See the payload below. |
| `character_action` | everyone | A gesture that the character makes with an answer, described in words: `text`, `turn_id`, `prompt_id`. |
| `input_declined` | everyone | The content policy declined a turn, and the character says its refusal reply instead: the `prompt_id`, or null for speech. |
| `call_ended` | the caller | Reply to `end_call`: `end_reason` and `duration_seconds`. |

### `transcript` payload

| Field | Type | Meaning |
| - | - | - |
| `text` | string | The sentence, as spoken. |
| `final` | boolean | Whether the text is settled. The next line with the same `turn_id` and `sentence_index` replaces a line with `final` false. |
| `speaker` | string | Always `character`. |
| `turn_id` | string or null | The answer that the line belongs to, as `question_received` named it. Lines of one answer share it. |
| `prompt_id` | string or null | The `prompt_id` of the `say` that the line answers. Null for an answer to speech. |
| `sentence_index` | integer | The position of the line in the answer, from 0. |

### `session_state` payload

| Field | Type | Meaning |
| - | - | - |
| `phase` | string | See [Session lifecycle](#session-lifecycle). |
| `character_id` | string or null | The id of the current character. Save it for `attach_character`. |
| `character_name` | string or null | The name of the current character. Null for an attached character. |
| `voice` | string or null | The voice of the current character. Null for an attached character. |
| `aspect_ratio` | string or null | `9:16` or `16:9`. Null for an attached character until its first call goes `live`. |
| `wait_position` | integer or null | While `starting`, the place in line for generation capacity (1 is next), when known. |
| `speech_ready` | boolean | True when the character can hear you: `say` and `mic` reach it. |
| `video_receiving` | boolean | True while the character's video arrives on `main_video`. |
| `audio_receiving` | boolean | True while the character's voice arrives on `main_audio`. |
| `mic_forwarding` | boolean | True after your `mic` track reaches the character during this call. |
| `last_frame_age_ms` | integer or null | During a call, milliseconds since the last frame of the character. |
| `call_started_at` | number or null | Unix time, in seconds, at which the current or last call became `live`. |
| `call_elapsed_seconds` | number | Seconds that the current or last call was `live`. It stops at the end of the call. 0 before the first call. |
| `call_max_seconds` | integer | The maximum length of a call (1,800). |
| `idle_seconds` | integer | After this long with nothing said, a `live` call ends as `idle` (300). |
| `stall_seconds` | integer | After this long without character video, a `live` call ends as `media_lost` (10). |
| `end_reason` | string or null | In `ended` and `failed`, why the last call ended. Null otherwise. |
| `last_error` | object or null | Why the last call failed. See [Failures](#failures). The model clears it when a call starts. |

`end_reason` is one of seven values. `ended_by_client` (`end_call`), `idle`, and `max_duration` end
in `ended`. `start_failed` (the call never went live), `media_lost`, `upstream_interrupted`, and
`platform_failed` end in `failed` with `last_error`.

## Complete example

This example creates a character from an image and starts a call. When `speech_ready` turns true,
it says one line to the character. It also prints the subtitles. The
[tutorial](https://docs.reactor.inc/model-api-reference/pixverse-r2-persona/tutorial.md) adds the microphone, subtitle
handling, and character reuse.

```typescript 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" });
let greeted = false;

reactor.on("error", (error) => {
  if (error.operation === "sendCommand") console.error(error.code, error.message);
});

reactor.on("message", async (message) => {
  if (message.type === "transcript") {
    console.log("Ava:", (message.data as { text: string }).text);
  }
  if (message.type === "session_state") {
    const state = message.data as { speech_ready: boolean; phase: string };
    if (state.speech_ready && !greeted) {
      greeted = true;
      await reactor.sendCommand("say", { text: "Hi Ava! What do you like to shoot?" });
    }
    if (state.phase === "ended" || state.phase === "failed") greeted = false;
  }
});

reactor.on("statusChanged", async (status) => {
  if (status !== "ready") return;
  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", {});
});

await reactor.connect(await getToken()); // Your server issues the token.
```


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