AI Video Realism Retoucher

Polish one selected realism issue in an existing AI-generated short video while carrying forward the shot elements the user already accepts. Use this focused route for artificial-looking light, synthetic material texture, over-saturated color, or repeated visual detail in a product clip, ad shot, social video, or other short-form footage.

Start from one source clip and one chosen problem cluster. The result is one source-led visual retouch, rather than a new sequence or a broad video production job. Keep the supplied subject, framing, camera movement, timing, scene mood, and other named details as must-keeps, then report any visible drift after delivery.

Inputs and defaults

The hard input is one accessible existing source video. Reuse its destination, the selected visible problem, the user's must-keeps, and audio intent when they are already known. Ask a compact question only when the user has not identified which single problem to prioritize or a missing choice changes the paid payload.

Unless the user chooses otherwise:

• address one problem cluster: light, material texture, color saturation, or repeated detail;
• use model: "auto" only when the live auto-eligible set has compatible source-ratio and duration behavior; otherwise select one compatible live model before the paid confirmation;
• omit an explicit aspect ratio only when the frozen live model card says the output is source-derived; otherwise show its default or an admitted explicit aspect-ratio control and obtain confirmation; and
• omit duration only when the frozen live model card says the duration is source-derived and can retain the required timing; otherwise show its output limit, default, or admitted explicit duration control and obtain confirmation;
• leave audio policy unset unless its treatment matters; request audio_setting: "origin" only when preserving source audio matters and the live card supports it; and
• create one opaque, stable client_request_id only after the paid payload is final.

This focused retouch does not create a timeline or a new multi-shot sequence. For creation from an idea, multiple clips, a broader content change, or an extension beyond the clip, use beatra-ai-video-studio to select the right video route.

Golden path

1. Inspect the available source. Watch the source when the host can do so, and record its actual MIME type, byte size, duration, source ratio, the selected issue, destination, and must-keeps. An upload is only transport; it is not visual analysis. If the host cannot watch the clip, treat the issue as user-reported and do not claim a visual source or result review.
2. Write one retouch direction. Name the visible defect to improve and the details that should remain recognizable. Use focused retouch workflow when the wording, preservation priorities, or source facts need more precision.
3. Upload and read live admission facts. For a local file, use the bundled upload helper, which performs the granted HTTPS PUT and returns an artifact reference. Query beatra.models.list with video_edit before a model, source-media compatibility, duration, audio, output, or price choice affects the request.
4. Show the video admission card. After beatra.models.list admits the complete payload, show route video_edit, tool beatra.videos.edit, source, one problem cluster, exact instruction, must-keeps, live-card duration and ratio behavior (including any output limit or approved explicit control), resolution if set, provisional live estimate, the fact that the 600-credit signup gift usually cannot start this video, and what happens if the balance is short. When duration is a sendable control rather than source-derived, write the shortest admitted integer. Planning, comparison, or “make the clip” is not approval. Do not create client_request_id or submit until the user confirms they have topped up or already have enough credits for this estimate.
5. Execute once through the bundled client. Use the bundled scripts/mcp_client.py for every remote Beatra tool: put the MCP tool name after call and pass its JSON arguments on standard input. Do not configure or call a host Beatra Connector, and do not use REST/OpenAPI as a fallback. Submit the frozen arguments once and retain the returned task ID.
6. Poll, review, and deliver. Poll the same task with beatra.tasks.get until terminal; a slow task is still the original task. When the source and delivery are viewable, compare the chosen issue and must-keeps. Deliver every returned artifact or link plus actual terminal model, dimensions, duration, billing facts, task ID, and observed drift. When the host cannot view the delivery, mark visual review incomplete rather than inventing a result.

Decisions that require confirmation

Confirm before the paid edit, before choosing a paid model instead of auto, before accepting any live-card default or output limit that changes source ratio or timing, before choosing an explicit ratio or duration, before choosing an audio policy, or before accepting weaker preservation for the selected repair. One changed source, instruction, model, duration, ratio, audio policy, or optional control is new paid work and receives a new request ID, a new admission card, and fresh top-up or balance confirmation. On insufficient_balance, relay the returned message, keep the top-up URL inside the balance error exact, and retry the same frozen client_request_id only after the user says they have topped up.

Recovery and next step

If a create response is lost, reconcile the original work with beatra.tasks.list and beatra.tasks.get before replaying the byte-for-byte identical request with the same ID. Never make a second paid edit because the first task is queued or running. A user-requested cancellation uses beatra.tasks.cancel once, then continues polling the same task to terminal.

After a visible result, recommend at most one focused, unexecuted next edit. A different correction is a new paid request; do not label it as a free revision or silently rerender the clip.

Account balance

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. Do not invent an account-balance or top-up tool. Do not make wallet.get a required step before every paid submit.

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.

References by task

• Read focused retouch workflow to build the source-led request, admit it against a live model card, and review or recover the exact task.
• Read installation and authentication only for first installation or expired credentials, and installation registration for best-effort package registration.
• Read tasks and results for task and artifact fields, and billing, errors, and recovery for returned balance and validation outcomes.
• Read Bundled MCP Client diagnostics when the bundled client needs diagnosis; do not configure a host Connector.
• Read automatic updates and safety for update guarantees and controls, or uninstall and disconnect when the user asks to remove the package or shared credentials.

Runtime and safe automatic updates

Before ordinary Beatra commands, the bundled client may silently check this installed package channel for a newer version, at most once every 24 hours. When a higher version is available, it installs the update automatically without separate confirmation. It downloads only from fixed official Beatra discovery and immutable CDN paths, verifies the archive, manifest, and every packaged file, and replaces only files owned by this package. It rejects redirects, downgrades, unsafe archives, unexpected destinations, and a different package, channel, or locale. If any update or recovery step fails, the current installation remains usable and the original command continues.

The setting persists for this installation:

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

Use the first command to disable silent checks, the second to restore them, and the third to inspect the official available version without changing files. See automatic updates and safety for official sources, integrity checks, replacement scope, and recovery.