Beatra Universal

What you end up with. Per run, one of:

• Images — one to four, one by default.
• Video — a clip, plus a separate last-frame still you can ask for on the

models that offer one.

• Music — a song or instrumental, delivered as every clip the model returns.
• Narration — an audio file.
• A reusable cloned voice.
• A rewritten production prompt, as text.
• Public social data, returned as JSON.

A returned file is delivered with whichever of its real dimensions, duration,
format, and size the finished task actually reports. The exact rendered format
comes from the model that runs, and is reported on delivery rather than
promised in advance.

Turn a requested outcome into the smallest verified Beatra workflow, complete
it through the shared connection, and return only what the task actually
produced. Use the host's native text and visual understanding to analyze a
brief, source media, or returned public social content. Use Beatra to look up
public social data and to create and manage images, video, music, speech,
reusable voices, uploads, model choices, and asynchronous task results.

Reuse the destination, prompt, source media, format, language, voice, model,
public social target, important controls, and accepted results already present
in the conversation. Infer ordinary details when they do not change the paid
payload. Ask only when a missing answer changes the requested result, cost,
explicit model commitment, voice-owner consent, destructive cancellation, or
another user-controlled high-impact choice.

Use the bundled client only

Run every Beatra operation through the bundled
scripts/mcp_client.py. Do not configure or use a host Beatra Connector. Never
use REST/OpenAPI as a fallback. For an ordinary call, run:

python3 scripts/mcp_client.py call <tool-name>

Provide exactly one JSON object on stdin. Do not put user content, local paths,
or credentials in command arguments. The bundled client adds transport
attribution itself and performs its cached, best-effort, non-billable
beatra.installations.register step automatically; registration failure never
blocks the user's requested work. Use
Bundled MCP Client diagnostics only when this
path needs diagnosis.

Connect once across media

When the connection is new, missing, expired, or explicitly being changed, run:

python3 scripts/authorize.py

The browser supports sign-in or account creation and then one Allow decision.
The helper prints the approval link at once, waits for Allow (leave it running),
stores the Device Token privately, verifies it with one non-billable call, and
prints Beatra is ready. When it prints BEATRA_AUTH_PENDING, show the user
the approval link, then run the same command again until it prints
Beatra is ready. Every run continues the same approval, so the user approves
only once, and an Allow given while nothing runs connects on the next Beatra
command. Never expose the approval code or
ask the user to confirm approval in chat. Authorize once for the full Beatra
connection; changing between image, video, music, speech, and public social
lookup does not need another grant. After installing or replacing it,
start a new agent session when the host discovers Skills only at session
startup. See installation and authentication
for connection recovery and
installation registration for the
automatic non-billable registration behavior.

Choose the smallest path

• For public posts, notes, videos, accounts, comments, or trends, use

beatra.social.tools.search, then beatra.social.tools.get, then one
beatra.social.execute with operation_key, the schema_hash just copied
from that tools.get, arguments, and one client_request_id. Follow
public social data. If those tools are not exposed,
say they are not available on this connection. Do not invent an
operation_key, call beatra.models.list for social lookup, or turn a
lookup into generation. Continue only with media the user already asked for.

• For a new image, guided composition, or base-preserving edit, use

beatra.images.generate, beatra.images.transform, or
beatra.images.edit. Follow images.

• For video-prompt enhancement, text-to-video, opening-image animation, ordered

references, a required last frame with an optional first frame, source editing,
or extension, use beatra.videos.enhance_prompt,
beatra.videos.generate, beatra.videos.animate,
beatra.videos.generate_from_references,
beatra.videos.interpolate, beatra.videos.edit, or
beatra.videos.extend. When the request is text-led and there is no usable
still, the first paid stage is beatra.videos.enhance_prompt or one
beatra.images.generate keyframe. That gift does not authorize a later video
call. Before generate, animate, interpolate, reference, edit, or extend, call
beatra.models.list with that route's exact capability (for example
{"capability":"text_to_video"} or {"capability":"image_to_video"}), admit
the payload, write the shortest admitted duration (audio-led and extend rules
unchanged), and show the production card.
Choose with videos, then load
video controls or
video recipes only when needed.

• For a talking presenter, spoken delivery, or digital-human clip, synthesize the

narration first with beatra.speech.synthesize, then animate a portrait with
beatra.videos.animate, passing that narration as driving_audio. The video
card's admitted formats and durations both constrain what you synthesize, so
read {"capability":"image_to_video"} and {"capability":"text_to_speech"}
before the speech call. Those two free reads surface every conflict this route
can raise before the first paid call — the audio format both cards must
accept, the spoken length against an admitted duration, and the portrait's own
fit. Raise all of them in a single message before the
first paid call rather than one at a time. The returned audio's real duration
and format still have to be re-checked against the card after synthesis.
Follow video recipes.

• For a song, instrumental, or reference-guided track, use

beatra.music.generate. Follow music.

• For narration, browse only when a voice is still needed with

beatra.voices.list, then use beatra.speech.synthesize. Create a reusable
voice with beatra.voices.clone only after explicit voice-owner consent and
the production card. Follow
speech and voices.

• When model selection, compatibility, supported controls, or an estimate

matters for image, video, music, or speech, copy an exact
{"capability":"..."} payload from models and treat
the returned interface card as current truth. Do not maintain model, price,
language, default, or reference-limit lists from memory.

• When the user asks how many credits remain or whether a live estimate fits,

call beatra.wallet.get. When they ask what was charged, call
beatra.wallet.ledger. Both are read-only.

• When a model card comes back carrying a top_up block, relay its tiers as the

card lists them and in that order. Do not rank them, do not talk one down, and
do not pick one for the user. Which tier suits them is their call, made on the
wallet page with the whole list in front of them. Never quote a tier from
memory.

Do not silently turn the request into another operation. Respect a concrete
model choice and report incompatibility instead of substituting a different
model or dropping an unsupported control.

Keep the user's wording

Carry the user's own subject, constraints, and negations into the prompt, and
expand it only as far as the chosen route actually needs. When you add wording
the user did not give — style, lighting, mood, instrumentation, or camera
language — say in your reply what you added. Some routes must add wording of
their own: music replaces a named artist with musical
qualities.

Send the enhance_prompt control only when the selected model's interface card
lists it. Sending an explicit true or false narrows which models auto may
choose, and an explicitly named model that does not expose it rejects the
request. beatra.videos.enhance_prompt is a separate paid tool that rewrites a
brief into a production prompt by design.

A returned result that does not match the prompt is a reportable outcome, not
something to hide behind a reworded retry.

Upload local media safely

When an input exists only as a local image, video, or audio file, use only:

python3 scripts/mcp_client.py upload <path> --mime-type <type>

The command validates the beatra.assets.upload grant, uploads the unchanged
bytes, and returns an artifact reference. Never send a filesystem path to a
generation tool, use host HTTP, or hand-write the grant and PUT flow. Respect
the 100 MB general ceiling and any lower limit returned for the selected model.
Ordinary media upload has no generic rights-attestation step. A sample for
beatra.voices.clone is the hard exception: before upload and cloning, obtain
explicit confirmation that the user owns the voice or has the owner's
permission, and only then set consent_attested: true. See
uploads.

Keep the paid boundary clear

Creative planning, authorization, upload preparation, voice browsing, model
discovery, public social tool search and inspection, recent-task listing,
credit-balance and ledger reads, and estimates are non-billable. Image, video, music, speech, voice-clone,
video-prompt-enhancement, and public social execute consume credits and return
an asynchronous task. Public social execute is prepaid. Video-prompt
enhancement is the postpaid exception: it
returns text only, never starts video generation, and a successful task
settles from actual tokens after completion.

A direct, well-specified request to create or look up authorizes that exact
paid request once for image, music, speech, social execute, or a gift-sized
video-prompt or keyframe stage. It does not authorize
beatra.videos.generate, beatra.videos.animate,
beatra.videos.interpolate, beatra.videos.generate_from_references,
beatra.videos.edit, beatra.videos.extend, or beatra.voices.clone. Before
those video or clone calls, show the production card and wait for the user's
answer:

1. Work — what will be made, in the user's own words, and which call makes it.
2. Credits — the provisional estimate from the live card just read, never a

remembered number.

1. Count — how many paid calls this turn. A retry with changed arguments is

another one.

1. Identity — one new opaque client_request_id per call, minted only once

that call's payload is final.

1. If the user stops here — name what they already hold and keep, such as an

accepted opening frame, a synthesized narration, or an enhanced prompt. When
this is the run's first paid call, say plainly that nothing has been paid
for yet, rather than naming an artifact that does not exist.

1. If the balance is insufficient — relay the returned message and its top-up

URL exactly, and wait.

Show the route's live-card duration, resolution, and aspect beside the estimate,
taking the shortest admitted duration and lowest admitted resolution unless the
user named a higher tier; audio-led and extend rules are unchanged. Planning,
comparison, or “make the clip” is not approval; approving this card is. Do not
ask the user to confirm they have enough credits — the connection reports the
balance itself — and do not create client_request_id or submit before they
approve.

Public social lookup is never folded into a video or clone production card. When it needs
confirmation, it gets its own card. For it, copy the schema_hash from
beatra.social.tools.get into execute with
operation_key, arguments, and one client_request_id. Show the
operation_key and the credit price returned by tools.get. Do not show
schema_hash to the user and do not ask for a model. Voice cloning always
also requires the explicit consent attestation described above.

Create one stable 1..128-character client_request_id only after the validated
paid payload is final. It names one logical paid operation. Submit
exactly once, save the returned task_id, and poll that same task with
beatra.tasks.get. Never poll a row whose submission returned no task_id;
reconcile with beatra.tasks.list instead. An identical retry keeps the same request ID and the exact
validated paid payload; the ID itself and transport attribution are not
part of the payload identity. Any accepted paid-argument change is new
paid work with a new ID and confirmation.

Honor a returned deadline_at. Otherwise stop active polling after 30 minutes,
report the current task state and resume route, and never duplicate slow work.
Cancel with beatra.tasks.cancel only when requested. If cancellation conflicts
with a terminal transition, continue with the same task.

Public social validation or a failed lookup is not a beatra.models.list
event. Keep error.code, read error.message or error.data.message, and
do not change a model. Follow tasks and results
for task identity and polling. For media generation validation or model
incompatibility only, follow
billing, errors, and recovery.

Recover without duplicating work

If a task ID is lost, use beatra.tasks.list with a plausible capability, then
call beatra.tasks.get for every plausible candidate. List items omit the full
input, so compare each detailed task.input with the saved payload before
deciding that it is the same work. For media generation, also compare resolved
model, media, and options. For public social lookup, compare operation_key,
arguments, and schema_hash. Never create a replacement because a response was
lost or a task is still queued or running.

On insufficient_balance, relay the returned public message, keep its top-up
URL exact, translate the rest, and retry the same
frozen client_request_id only after the user says they have topped up. State
that nothing was charged only when the error says so. Do not invent a top-up
operation or an account mutation. Use the topup_url from beatra.wallet.get
or the URL inside the 402 message. When the user asks which top-up amount to
buy, read questions and anti-patterns. Connection
revocation belongs in the Beatra Console.

On a failed public social lookup, keep error.code and read the platform
wording in error.message or error.data.message. Change arguments only when
that message names a field or ID, then use a new client_request_id. Otherwise
keep the same ID and the same payload. Do not suggest changing a model.

Deliver returned truth

While a task is still queued or running, report the stage that
task.progress actually returns instead of narrating an invented pace. Treat
its percent as a phase marker rather than a completion fraction: it moves on
fixed server steps, holds one value for the whole generation wait, and must never
be handed to the user as a share of the work finished. An unchanged stage or
percent is not evidence that the task is stuck. When a response carries no
progress at all, say the task is still running and leave it there.

On completion, report the task_id, terminal status, every returned result,
and actual usage. For media generation, also report the resolved model. For
artifacts, include every returned link or ID plus dimensions, duration, MIME
type or format, and size when present. For public social lookup, deliver the
inline JSON or JSON artifact; do not look for a resolved model or a generated
media file. Deliver non-artifact results such as an activated cloned voice_id
when returned. Report billing.net_charged_credits; include gross charge and
refund only when present. Use the exact returned task.links.assets
destination for asset management.

Never infer completion, file URLs, quality, usage, refunds, or credit totals.
State honestly when the host cannot visually inspect or play a returned file.
Preserve structured errors and give the smallest recovery step.

References by task

Three tiers. Read the first on a first run, the second once a route is chosen,
and the third only when something needs diagnosis or recovery.

Getting started

• On a first run, or when one job spans more than one medium, read planning a multi-medium run for the order of decisions and where each paid boundary falls
• First connection and automatic registration: installation and authentication and installation registration

Building the request, one medium at a time

• Public social posts, accounts, comments, and trends: public social data
• Image generation, transformation, and editing: images
• Video route selection, controls, and request patterns: videos, video controls, and video recipes
• Songs, instrumentals, references, and music delivery: music
• Narration, voice discovery, and consent-gated voice cloning: speech and voices
• Local image, video, or audio preparation: uploads
• Current model compatibility, controls, and estimates: models

Diagnosing and recovering

• When a user reports a result that misses the brief, a refused model, a stuck or lost task, or an unexpected charge, read questions and anti-patterns
• Bundled commands and connection diagnosis: Bundled MCP Client diagnostics
• Task progress, recovery, results, balance, and errors: tasks and results and billing, errors, and recovery
• Verified automatic updates and persistent controls: automatic updates and safety
• When the user wants to stop: stopping use and removing shared credentials

Keep updates safe and removable

Before ordinary commands, the bundled client performs a silent check at most
once every 24 hours. When a higher version is available from its fixed official
discovery address and immutable official CDN source, the client may install it
automatically without separate confirmation. It verifies the archive,
manifest, and every packaged
file, then replaces only package-owned files. If checking, downloading,
verification, replacement, rollback, or recovery fails, the current
installation remains usable and the original command continues. Update failure
never justifies a paid retry.

The per-installation choice persists:

python3 scripts/mcp_client.py update --auto off
python3 scripts/mcp_client.py update --auto on
python3 scripts/mcp_client.py update --check

The first command disables silent checks, the second restores automatic
updates, and the third reports the official available version without replacing
files. Read automatic updates and safety
for the full verified-update contract. For removal or credential cleanup,
follow stopping use and removing shared credentials.
Never directly delete the shared ~/.beatra connection state.