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

# AI video avatar agents

> Bind a conversational agent to a rendered talking-head persona that can join a live video room as a digital host, or render an on-demand personalized clip from a script plus merge tags — queued, tracked to completion, and delivered with a verifiable content credential.

# AI video avatar agents

An **avatar persona** is a tenant-managed binding that holds two references:
one of your conversational **agents** (the dialog brain) and one rendered
talking-head provider **persona reference** — the avatar id you hold at your
chosen provider. The persona can then either **join a live video room** as a
digital host, or **render a personalized video clip** asynchronously from a
script template with `{{merge_tag}}` tokens and a per-recipient merge-field
map.

Reach for a persona when you want the same conversational brain to show up
visually — a concierge onboarding host, a policy-recap clip, a personalized
campaign send — rather than in a voice or messaging-only channel.

## Persona registry

The persona registry is capped at 50 entries per tenant. Create, list, or
update one under `/api/v1/video/avatar-agents`:

|                    | Request                           |
| ------------------ | --------------------------------- |
| List personas      | `GET /video/avatar-agents`        |
| Register a persona | `POST /video/avatar-agents`       |
| Update a persona   | `PATCH /video/avatar-agents/:id`  |
| Remove a persona   | `DELETE /video/avatar-agents/:id` |

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/video/avatar-agents" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding host",
    "agent_id": "agt_4f2b…",
    "provider": "tavus",
    "provider_persona_ref": "your-replica-id",
    "greeting": "Welcome aboard — let's get you set up.",
    "locale": "en-US",
    "enabled": true
  }'
```

On 201 the response carries the persona with a `vaa_`-prefixed id. Store only
the opaque provider persona reference here — Orbit never holds your provider
credentials; provisioning the provider account and minting the bot-participant
token happen in the avatar-runtime, which consumes a **join plan**.

<Note>
  A persona that must not be dispatched can stay in the registry: set
  `"enabled": false` to retain it without letting it join rooms or render
  clips.
</Note>

## Join a live video room as a digital host

When a persona is dispatched into a video room, the avatar-runtime requests a
join plan and joins the room as a bot participant that renders the talking-
head video driven by the bound agent's turns:

```bash theme={null}
curl -G "https://api.orbit.devotel.io/api/v1/video/avatar-agents/vaa_…/join-plan" \
  -H "X-API-Key: dv_live_sk_..." \
  --data-urlencode "room=my-room-name"
```

The join plan returns a dispatch descriptor that the avatar-runtime consumes: the
room name, the bound conversational agent id, the avatar provider and its
persona reference, and the persona's opening greeting. The room it joins is
the standard moderated, in-browser WebRTC room Orbit's Video API ships — the
digital host lists in the participant roster, moderator controls still apply,
and the session's recording and summary land on the contact record.

## Queue a personalized clip from a script

The async counterpart is a render job posted to `/api/v1/video/avatar-video-renders`:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/video/avatar-video-renders" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_agent_id": "vaa_…",
    "script_template": "Hi {{first_name}}, welcome to your {{plan_name}} plan overview.",
    "merge_fields": {
      "first_name": "Dana",
      "plan_name": "Premium support"
    },
    "locale": "en-US"
  }'
```

The script template accepts up to 5000 characters and any `{{merge_tag}}`
tokens — bare token names with no braces. A `merge_fields` map can supply up
to 20 keys, each key up to 64 characters, each value up to 500 characters;
the rendered clip speaks the substituted script. The render request is
persisted as a `queued` job with a `vavr_`-prefixed id, which your provider
integration or render runtime consumes (Orbit never calls your provider's
render API directly — same "no net-new infra" posture as the join plan).

Report progress back via `PATCH /video/avatar-video-renders/:id`:

* `rendering` — mark the job in-flight.
* `completed` — supply the finished clip's `output_url` and either the raw
  clip (`video_base64`, hashed server-side) or a pre-computed SHA-256 digest
  plus byte length, so Orbit mints the content credential without storing
  the clip itself.
* `failed` — with an error message preserved on the job.

Once `completed`, the clip's `output_url` is a plain HTTPS link — attach it to
a campaign send or a 1:1 MMS/WhatsApp message anywhere the existing content
pipeline accepts a generic media URL.

## Signed content credential per clip

Every render that reaches `completed` is minted a **content credential** — a
tamper-evident watermark plus disclosure manifest, the same synthetic-media
provenance guarantee Orbit already ships for cloned voice audio. The
credential is persisted on the render record and travels with the clip when
its `output_url` is attached downstream.

A reviewer confirms authenticity via the render surface's verify endpoint:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/video/avatar-video-renders/verify" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "token": "the-clip-content-credential-token" }'
```

Passing only the token validates it. Optionally also pass the clip — either
as base64 or a SHA-256 digest — and the verify response bind-checks it: a
valid token re-stapled onto a different clip reports a `video_mismatch`,
not a false pass.

## Where to go next

* [Video meetings and conferences](/guides/video-meetings) — the room a live
  avatar persona is dispatched into.
* [Video API reference](/api-reference/video) — the full scheduled-room
  endpoint surface the persona and render surfaces bind to.