Live Commerce Script Studio

Turn a product lineup into a run of show a host can read on air — the schedule, the per-product talk track, the ready-to-read lines, the compliance pass, and the cards and spoken takes that make it usable in the room.

Scope and adjacent routes

The route is: a session plan, a talk track per product, a line library, a compliance pass, and the artifacts the room actually uses. It fits when someone is going live to sell and needs words in front of them.

When the job is elsewhere, another workflow fits better. Room decoration built from product photography — backdrops, overlays, promo covers — belongs in a live-commerce visual workflow. A short recorded video rather than a live session belongs in a seeding-video or product-video workflow. Narration for an edited clip belongs in a voiceover workflow.

Inputs and defaults

Two hard inputs: the category or theme of the session, and at least one featured product with its regular price and live price.

Both prices are needed because the offer is framed as the gap between them. Stock is needed only where a figure is actually rendered or spoken: a stock-type urgency line, a held slot's fixed release quantity, or a take that states a quantity. The countdown card carries a blank slot the floor manager fills, so it needs none. Ask for all three together, once, rather than one at a time, and proceed on the two prices when stock is not yet known.

Reuse whatever the conversation already states about the platform, the session goal, the length, and who is on air. When those are absent, default to a four-hour session, a host plus a floor manager, a creator-led selling format, and the goal implied by the lineup. Name each default in the confirmation instead of asking about it.

Everything the session claims about the products comes from the merchant. Prices, stock, specifications, ingredients, certifications, awards, comparison figures, and promotional terms are theirs to supply. When one is missing, write the beat around it; never produce a plausible figure, because they are the one who answers for it on air.

Golden path

Stages 1 to 5 cost nothing. No paid call happens before the four written pieces are approved.

1. Set the session frame. Platform, goal, length, on-air roles, and the lineup order per planning the session.
2. Build the minute-by-minute schedule. The whole session across its three phases, with each product's slot placed on the six-stage selling chain.
3. Write a talk track for every featured product. Seven steps, in order, per writing the talk track.
4. Write the line library. Twelve categories of lines the host can read as written, per writing the talk track.
5. Run the compliance pass and show all four pieces for approval. Every line is screened before anything is produced, because a line that fails on air costs more than a line rewritten here.
6. Read the live text_to_image and text_to_speech cards with beatra.models.list, and select a voice with beatra.voices.list.
7. Confirm production. Show which cards will be rendered, which lines get spoken takes, the selected ready voice, the current estimate, and a stable request ID for every planned paid call.
8. Render the cards with beatra.images.generate, one call per card, and synthesize the spoken takes with beatra.speech.synthesize. Read the actual returned duration, size, and MIME type for each take.
9. Poll each task with beatra.tasks.get until terminal, deliver everything together, and review what you can actually see.

Decisions that require confirmation

Confirm before spending once: the card set and the spoken takes together, each with its price and request ID. There is no second gate, because nothing here depends on an earlier paid artifact.

Also confirm, rather than deciding alone: a session longer than six hours, a lineup past eight featured products, a price or stock figure the merchant has not verified, and any change after a card or take is approved. Each changed argument is new paid work with a new request identifier and fresh approval.

When a requested line cannot pass the compliance screen as written, offer the closest wording that does and continue from there.

Execution

Invoke every remote Beatra tool only through the bundled scripts/mcp_client.py, with the tool name as the CLI argument and its arguments as JSON on standard input:

printf '%s' '{"capability":"text_to_image"}' | python3 scripts/mcp_client.py call beatra.models.list
printf '%s' '{"capability":"text_to_speech"}' | python3 scripts/mcp_client.py call beatra.models.list
printf '%s' '{"language":"zh-CN"}' | python3 scripts/mcp_client.py call beatra.voices.list

Do not configure or call a host Beatra Connector, and do not use REST/OpenAPI as a fallback. Give each logical paid request one stable opaque client_request_id and submit it exactly once.

Delivery and review

Deliver the schedule, the talk tracks, the line library, the compliance pass, the rendered cards with their returned dimensions, the spoken takes with their real durations, each task ID, the returned artifact links, the resolved model, and billing.net_charged_credits. Report only facts the task actually returned.

When the host can view or play the returned media, check that each card's figures match the approved schedule and that each take is audible and finishes cleanly. Card text is generated artwork, so read the numbers back against the source and say plainly when a figure did not render correctly or legibly — a crisply rendered wrong digit is the dangerous case, and a wrong price on a card in the room is worse than no card.

State which media details could not be inspected instead of inferring them from task metadata.

Recovery

Record each task ID immediately and poll only that task. queued and running mean wait. If a create response is lost, resubmit only the identical frozen payload under the same identifier; if a task ID is lost, list tasks for that capability and match candidates against your own ledger before any retry. Redoing one card reuses the other artifacts unchanged. insufficient_balance means nothing was charged and the identical request can be resubmitted after a top-up.

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

Three tiers. Read the first on a first run, the second while building the session and before the one paid confirmation, and the third when something goes wrong or needs recovery.

Getting started

• On a first run, or when the single approval gate is unfamiliar, read one session, end to end — a complete run with the schedule, the seven-step talk track, the compliance pass catching three lines, and where the money enters
• First install or expired authorization: installation and authentication
• Non-billable package registration: installation registration

Building the session

• Session frame, the three phases, the six-stage chain, lineup order, and the minute-by-minute schedule: planning the session
• The seven-step product talk track, the twelve line categories, urgency types, and the compliance screen with its banned-term list and replacement patterns: writing the talk track
• Exact payloads, what the confirmation freezes, polling, redoing one card, recovery, and cancellation: live session workflow

Diagnosing and recovering

• When a line fails the screen, a merchant insists on one that does, a card renders a wrong figure, a host rejects the wording, or a price changes after approval: questions and anti-patterns
• Task polling, artifacts, and result fields: tasks and results
• Balance, validation, and structured errors: billing, errors, and recovery
• When the bundled client cannot connect: Bundled MCP Client diagnostics
• Updates and security: updates and security
• Removing the package or shared credentials: uninstall and disconnect

Updates and security

This Skill runs only the files installed with it and leaves them unchanged while it runs; it never downloads or executes other code. It talks to Beatra's official services over HTTPS, and a file you choose to upload goes only to the one-time upload address Beatra issues for it.

Once a day at most, the bundled client reads Beatra's public version list. When the store or tool you installed from has a newer version, it prints one line with the command that updates it there. Updating stays your choice, through that store or tool. See updates and security.