Skip to main content

​
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:
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.
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.

​
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:
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:
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:
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