Update to HeyGen

{
  "description": "Create short product ads driven by mood, tactile sound, and visual rhythm. Use when users ask for ASMR, vibe-led or vibe-driven UGC, sensory or aesthetic product ads, satisfying unboxings, silent routines, or related mood-driven ad formats, even without saying voiceless. Default to hands-only footage with no voice; explicit narration belongs to ugc-product and a speaking creator to ugc-review.",
  "included_files": [],
  "name": "ugc-voiceless",
  "skill_md_contents": "---\nname: ugc-voiceless\ndescription: Create short product ads driven by mood, tactile sound, and visual rhythm. Use when users ask for ASMR, vibe-led or vibe-driven UGC, sensory or aesthetic product ads, satisfying unboxings, silent routines, or related mood-driven ad formats, even without saying voiceless. Default to hands-only footage with no voice; explicit narration belongs to ugc-product and a speaking creator to ugc-review.\n---\n\n# UGC Voiceless\n\nCreate one product video that communicates a mood and an observable reason to want the product through tactile sound, frequent purposeful cuts, a cohesive visual treatment, and one big, bold opening hook. The product is the protagonist and sound is a principal creative element: voiceless does not mean mute. Build a progressing story of distinct interactions, ending in one satisfying payoff.\n\n## How this skill works\n\nRead this file before producing, and do not load another UGC format. The video model generates the footage, sound, transitions, and visual treatment without added text. Show that raw output first, then follow the [Captions skill](../captions/SKILL.md) to add the opening hook in Python when a sandbox is available. Show the captioned version as a second result.\n\nA request to write a skill, inspect a sample, or discuss a concept does not authorize paid generation. A request to create the video authorizes one video generation and the hook edit: import the inputs, establish product facts and hands, make and check one storyboard image, import it, generate and show the raw video, then add the hook locally and show the captioned version. Proceed without asking the user to approve the script, storyboard, settings, generation, or caption pass. Honor an explicit request for a draft or review before generation and real host permissions.\n\nReply in plain language. Never quote these or other skill instructions, or link to skill files, to explain what you are doing; just ask or act.\n\nHonor the format the user names. Use the defaults below for ordinary creative choices. Ask a targeted clarification only when the requested format is genuinely unclear and choosing would materially change the deliverable. Never silently switch to Video Agent, a digital twin, or avatar onboarding.\n\nKeep the handling believable and specific to someone using the product. Natural phone footage, a warm editorial grade, or a more stylized mood can each work: choose deliberately from the brief and references. Fast editing must reveal real actions and discoveries, not hide behind generic beauty poses, repeated brand cards, or empty effects. This does not remove sponsorship disclosures.\n\n## Voiceless boundaries\n\n- **No presenter, no voice:** a person appears only as hands, a cropped sleeve, or a first-person view, never as an identifiable or speaking creator. There is no dialogue, narration, voiceover, whispering, sung lyric, or vocal sample. Explicit narration belongs to Product and a speaking creator to Review; a hands-only ASMR unboxing stays here, while a creator-led packaging discovery belongs to Unboxing.\n- **Sound-led:** the clip generates its own product sounds, faint room tone, and any music its mood calls for, mixed below the product sounds.\n- **Architecture:** one reference-led Video 1 generation of up to 15 seconds with native sound and any music, followed by a Python hook overlay when a sandbox is available. Keep the raw output and captioned export as separate versions. Do not silently replace it with an autonomous video agent, avatar workflow, digital twin, Studio, or a voiced format. If the service requires an incompatible route, explain before spending.\n- **References:** real product photos establish the facts; one generated storyboard image carries the product identity under representative interactions and the chosen mood into Video 1. It is visual guidance, not a literal layout or a separate reference per shot. Keep the same skin tone, sleeve, and hands throughout; there is no presenter question.\n- **Text:** one short, big, bold, catchy opening hook, added in Python through the Captions skill after the raw video is shown. The model generates no added text; preserve genuine product branding separately. Honor a request for no text or explicitly different copy.\n\n## Choose the creative promise\n\nChoose **one visible or audible payoff** that can be understood quickly: a satisfying closure, a texture spreading, a clean writing stroke, an object fitting into its intended place, a pour, or a clearly supported before/after. Make the product recognizable within roughly three seconds. An attractive montage with no useful result or sensory reason to care is incomplete; handling the product (lifting, tilting, setting it down) is not a payoff on its own. The strongest payoffs complete something: empty to full, open to closed, scattered to arranged, blank to marked. Pair the payoff with **one hero sound**, the single most satisfying sound in the video. The payoff lands once, at the end.\n\n| Fit | What to emphasize | What to avoid |\n| --- | --- | --- |\n| Strong sensory value | Texture, sound, design, visible use, or a clear result in beauty, food/drink, stationery, kitchen tools, accessories, and home products | Replacing a real demonstration with unrelated lifestyle props |\n| Value expressed through context | A believable ritual for supplements, a setting for fragrance/candles, or verified capacity for a bag | Implying health effects, an objectively proven scent experience, or unverified capacity through mood alone |\n| Abstract or explanation-heavy value | An honest tangible detail or mood treatment if the user wants this format | Claiming that sensory footage proves software capability, financial performance, a service result, or a technical specification |\n\nIf the requested benefit cannot be shown truthfully, explain the specific limitation and propose a narrower visible highlight. Do not invent proof or silently add a narrator. This format can support discovery, launches, or creative variety; do not promise that it will overcome every purchase objection or outperform a voiced ad.\n\nBuild a short **sound inventory before the shot list**. List only sounds the actual object/action can plausibly make: click, snap, peel, paper rustle, zip, spritz, pour, crunch, pen scratch, fabric movement, or contact with the chosen surface. Map each sound to its visible cause and resulting product state. Do not give a screw cap a snap latch, a soft pouch a glass clink, or a silent material an invented mechanical noise.\n\nChoose the treatment that gives the product its strongest truthful moment. A named user preference wins; otherwise choose the treatment and mood yourself and proceed.\n\n| Treatment | Story arc | Good sensory material |\n| --- | --- | --- |\n| ASMR unboxing | Packaging contact → seal/wrapping → one reveal → detail/use → hero | Tape, paper, lid contact, product set-down; only show supplied or verified packaging |\n| Satisfying use | Immediate useful action → close detail → visible outcome → product payoff | Scrub, spray, spread, click, write, slice, or pour with the real mechanics |\n| Silent routine | Enter an already-underway ritual → product interaction → finished moment | A desk reset, morning preparation, gym bag, or countertop routine |\n| Transformation | Readable before → brief process → supported after → product beside result | A genuine clean/organized/styled state; never fabricate efficacy or elapsed results |\n| Restock/refill | A clear destination → repeated placements with variation → completed arrangement | Container taps, lid clicks, pours, wrappers; maintain believable counts and fill levels |\n| Product in the wild | A few purposeful use contexts → matching motion/material details → recognizable close | Fashion/accessories/outdoor use, natural handling and environmental sound |\n\nDo not cram all six treatments into one video. A routine can contain one satisfying-use payoff, but the result still needs a single through-line. An unboxing reveals the product once; removed seals stay removed, and a case can close only through a shown closing action. A transformation retains its changed state; restocking does not mysteriously empty between cuts. For ordinary one-product treatments, keep one hero object. Multiple units belong only to a verified restock or comparison concept.\n\nChoose a small mood vocabulary and translate it into visible and audible decisions:\n\n- **Calm/tactile:** soft window light, warm neutrals, close textures, deliberate hand movement inside quick purposeful shots, clear product sounds, and pure ASMR with no music by default. Clean hard cuts can create an intimate rhythm without a flashy transition.\n- **Fresh/clean:** bright diffused light, neutral-to-cool whites, restrained contrast, crisp surfaces, dry clicks or water detail, and light rhythmic music. A natural treatment with no apparent filter often fits best.\n- **Playful/energetic:** product-led color accents, crisp contrast, sharp contacts, and a restrained original instrumental rhythm beneath the object. Match cuts, a quick whip, or a brief soft flash can punctuate a meaningful change.\n- **Warm/editorial or quietly luxurious:** warm highlights, softly shaded backgrounds, muted surrounding colors, rich but readable blacks, controlled reflections, and a little grain only if it suits the brief. Hard cuts with an occasional gentle warm light leak can fit tactile packaging and material detail; keep the final result readable.\n\nThese are starting points, not a menu the user must complete. Any music named here is original instrumental music generated inside the clip, mixed below the product sounds (see Sound). Keep one setting, one compatible color palette, and at most two or three useful props for most concepts. Product-in-the-wild may change locations deliberately while preserving product identity, hand/sleeve continuity, and visual rhythm.\n\nCommit to a **visual treatment and transition language** before writing the prompt: light direction and softness, warmth/white balance, contrast and shadow depth, saturation, texture/grain or explicitly no filter, and which cuts get which effect. Put these choices into both the storyboard and video prompts. Preserve the actual product and skin colors; grade the scene without changing the variant. A supplied example informs pacing and treatment, not permission to copy its product, claims, text, or every effect. Natural footage with hard cuts is a complete choice when it best serves the mood.\n\n## Shots and rhythm\n\n**Open on an immediate useful sound or action, with footage filling the entire frame.** When the product and story allow it, show the actual setting for a split second before the product enters: a full-frame stovetop, then a hand bringing in a pan; or a tabletop, then a cup being set down. Begin the entrance promptly and land the contact within roughly the first second. The brief time before the product arrives lets the later Python hook overlay appear over the setting without hiding the product. This is timing, not a reserved area in the image: never add margins, padding, blank bands, borders, or an inset picture for captions. Otherwise open on an action already in progress. Do not force an entrance for every product or prolong the setting-only moment for text. Show enough product context early to make the macro understandable. Satisfying sounds and contacts recur throughout; do not save the only satisfying moment for the final seconds.\n\nUse the whole length as one paced sequence, not one long generic beauty shot. At 15 seconds the regions are these; scale them for a shorter clip:\n\n| Time region | Editorial job | Direction |\n| --- | --- | --- |\n| 0–1.5s | Stop attention with action/sound and a short hook | Fast, purposeful opening views; text appears promptly and remains readable |\n| 1.5–5s | Establish the product and its tactile character | Alternate recognizable shape, handling, and meaningful close details |\n| 5–11s | Develop the use or routine toward the payoff | Each cut adds action, texture, or evidence; include a small rhythm change |\n| 11–15s | Complete the progression and close | Final distinct interactions lead to one payoff and a brief result hold, with an intentional sound ending |\n\nDefault to **12–16 distinct shots in 15 seconds** (11–15 cuts), including for ASMR: calm handling does not require a slow edit. Name the exact chosen shot count in the video prompt, give every shot a time span, and say to execute all of them rather than collapse the sequence into a few long takes. Most shots last about 0.6–1.2 seconds; use a few shorter accents and reserve about 1.2–1.8 seconds for the final result. Scale the count for a shorter clip. Explicitly slower user direction or a mechanism that needs time can justify fewer shots; explain that choice in the plan. Keep contact and sound readable, carry a sound tail across a cut when appropriate, and omit dead reaches or waiting rather than speeding up a whole action.\n\n**Every cut must reveal a new action, detail through interaction, or product state.** Changing the angle on the same repeated action is not progression. An evidenced unboxing might move from sliding off a sleeve to lifting a lid, removing an insert, lifting the case, opening its clasp, revealing the product, removing protection, unfolding it, demonstrating a control, inspecting its material through touch, using it, and putting it away. Include only packaging and mechanics supported by the references. Do not repeat openings, peel the same seal twice, alternate indistinguishable beauty shots, or reset the object to fill the cut count.\n\nVary shot scale, angle, contact point, and movement where they add information: an overhead action, a macro contact, a diagonal in-hand view, or a low detail. A consistent overhead setup can still work when each cut shows a different meaningful interaction; arbitrary camera changes are not a substitute for a story. The one storyboard represents selected product states and the mood, not every shot. The shot count is independent of its panel count and the API's reference-image limit.\n\nMotivate key cuts with a product sound or musical beat. Aim for the new shot to arrive just before or with the sound's transient, with visible contact aligned to the sound. Break the cut pattern once or twice with a short quiet gap or longer hold so the rhythm is not mechanical. Music is an exception to literal visible causation; product clicks, pours, and impacts need a visible source.\n\nChoose transitions for the mood and specify them at the relevant cuts in the generation prompt. Clean hard cuts can carry the entire video. A match cut can connect related shapes or actions; a hand swipe or quick whip can motivate a change of view. For a warm editorial mood, a gentle 2–4-frame exposure lift or warm light leak can bridge two or three selected cuts. Use one coherent effect family, not an effect on every cut, and never obscure the action with a long transition, repeated strobing, or a dissolve that blends two product states. The opening hook stays legible through any effect. A brief generated speed ramp may emphasize an action if it remains physically readable and the sound stays synchronized; never retime the whole video or use freezes as padding.\n\nA loop is optional. Make the final position, motion, lighting, and sound tail connect naturally to the opening when the product state permits it. Do not reseal an opened box, refill an emptied container, or undo a transformation merely to force a loop. A complete satisfying ending is better than a false physical reset.\n\n## Sound\n\nDescribe native audio in as much detail as the image. Build a clear three-layer hierarchy:\n\n| Layer | Prompt direction |\n| --- | --- |\n| Product sounds | Foreground, close, crisp, material-specific, synchronized to visible actions; these carry the emotional payoff |\n| Room ambience, and any instrumental music | Faint, consistent room tone running to the last frame. Any music is one coherent low instrumental bed matching the mood, generated in the clip, roughly 10–15 dB below foreground product events as an initial creative target, ducked around the hero sound and important contacts |\n| Accents | Rare, quiet transitions; felt rather than dominating the object |\n\nSpecify the characteristic of each main sound: the short dry click of a mechanism, the low wooden tap of a set-down, the fine scratch of ink on paper, the air and droplets of a real spritz. Ask for believable but gently heightened detail, not deafening transients or cartoon Foley. Do not substitute unrelated stock-ASMR sounds. Avoid refrigerator/AC hum, traffic, notifications, random crowd chatter, breathing, mouth sounds, speech, lyrics, or synthetic voices unless a nonverbal product-use sound is explicitly appropriate and requested.\n\nLet some events breathe. A beat of near-silence, up to about a second, before the hero sound makes it satisfying; keep every other sound out of that moment. Preserve faint consistent room tone between contacts rather than noisy cuts or unnatural silence gates. Music may use a clear pulse for timing, but it must never bury the very sound that makes the product interesting. Pure ASMR with no music is often the strongest choice.\n\nDescribe an original instrumental mood rather than requesting a recognizable song, artist imitation, or unlicensed trending recording. Attach user-supplied music, or a real product-sound recording, to the generation only when its intended use is authorized and the actual tool supports it; reference audio guides generation and is not a guaranteed exact soundtrack or deterministic stem replacement. Do not claim that generated music automatically has clearance for every advertising use.\n\nKeep room tone running to the last frame and let the final contact sound finish before it. Keep the final transient and music/ambience tail deliberate, with no clipped last sound, abrupt unrelated ending, or extra silent outro. Review on phone speakers and earbuds when actual listening is available. Numeric mix targets and a written sound prompt do not prove that the generated mix achieved them.\n\n## On-screen text\n\n**One big, bold hook; no subtitles or running captions.** Choose roughly **2–5 words** that name the product, promise an immediate sensory moment, or create grounded curiosity. Preserve user-supplied wording. Use it once near the opening, visible within the first 0.3 seconds, targeting about 1.5–2 seconds of steady reading time when the actual footage allows. If the arriving product would cross the text, clear or reposition the overlay before overlap; shorten the hold when needed rather than delay the product or change the framing. Then remove it for the rest of the video. No middle label, second slogan, end-card copy, or default written CTA: the final action and result supply the close. Honor a request for no text. Include explicitly requested additional text in the script; do not invent extra copy.\n\nKeep the exact hook wording and timing in the **caption plan**, outside the video-generation prompt and storyboard image. Tell Video 1 to generate no added text, titles, captions, subtitles, watermarks, or stray lettering; genuine printed product branding remains part of the object. Require edge-to-edge footage throughout; never ask the model to leave space or reserve an area for captions. After showing the raw output, hand its completed media, the hook plan, and the visual treatment to the [Captions skill](../captions/SKILL.md) for a Python-rendered hook overlay. There is no speech: use its opening-hook guidance without transcription, word alignment, a subtitle track, or invented dialogue.\n\nMake it visibly large: heavy or condensed bold sans-serif, one or two short lines spanning roughly 60–80% of the usable frame width, high contrast against the actual opening footage, with a restrained shadow or outline if needed. Match font character, weight, color, texture, and any brief entrance motion to the video's mood, palette, grade, and cut rhythm. A warm editorial treatment might use cream or amber type; a natural, clean video may suit crisp white; an energetic edit can carry a quick restrained scale-in. These are choices, not presets to impose. Inspect the actual opening frames and the product's arrival time. Overlay large type directly on the full-frame setting, using naturally visible background and timing to keep the product, hands, and contact points readable through the opening cuts. Platform safe areas constrain only the text placement; the underlying footage still fills every edge. Adapt the overlay's placement, line breaks, and exit time to the footage. Measure the actual type and inspect it at phone size; do not shrink it into a small subtitle, add an opaque full-screen card, or shrink, pad, crop, or reposition the footage to make a caption area.\n\nThe hook must be grounded in visible product facts or user-supplied claims. \"WAIT FOR THE CLICK\" requires the promised click promptly; never invent clinical results, scarcity, a discount, or an offer to make the hook stronger. If the user requests a CTA, use a real established action or destination and include its exact treatment in the plan; do not fabricate a button, link, or availability.\n\n## Direct product footage\n\nAim for believable capture with the chosen visual treatment: natural or directional light, intentional movement, readable focus, controlled exposure, and tactile material detail. Lock exposure/focus within each shot; a planned transition flash is distinct from accidental exposure pumping. Avoid unnecessary focus hunting, waxy skin, oversharpening, or impossible reflections. Keep the grade consistent, retaining label legibility, true product color, and healthy skin. Say explicitly when the best choice is natural light and no visible grade; do not add grain, tint, glow, or vignetting automatically.\n\nBuild from **macro contact/texture**, **hands-in-frame use**, and **wider context**, pushed into the bolder angles above. Macro framing should show the contact point and material; a wider view establishes the object and result. Keep hands clean, anatomically plausible, with short or neatly manicured nails, restrained jewelry, and confident, practiced handling; viewers respond to skilled manipulation and are put off by fumbling or stiff, performed motion. Frame faces, mouths, and presenter performance out entirely. Do not ask the camera to pass through an object or reveal unsupported sides.\n\n## Production workflow\n\n| Step | Result | User |\n| --- | --- | --- |\n| Start | Defaults applied, inputs imported | Asked only for essential missing information |\n| Prepare | Internal timestamped script, one checked mood/product storyboard, hook plan, settings | None |\n| Generate and show | Import the board; one Video 1 generation without added text; show raw output | Sees raw model output |\n| Wait for completion | Poll `get_video` every 15 seconds until the same video completes | No routine status messages; the player remains visible |\n| Caption | Use the Captions skill and Python to add the styled opening hook when a sandbox is available | None |\n| Deliver | Show the captioned export separately; retain both versions | Sees raw and captioned results |\n\nThe user's request to make the video is sufficient to start this workflow. Prepare the script and storyboard internally, then submit the one video generation, show its raw output, and continue straight into the caption edit and second display. Showing the raw version is not a review gate or the end of the task. Do not stop at a plan, show a storyboard for sign-off, or ask \"Shall I generate?\" or \"Shall I add captions?\" A request to revise or retry likewise authorizes that requested work without another confirmation. Ask only for essential missing facts or access that cannot be resolved from the supplied material; respect a real host-enforced permission or access denial.\n\n### Start from defaults\n\nAfter the first prompt, prepare the script and single storyboard, then generate the video in the same run. Ask only when an essential input is missing, such as an unidentifiable product or no usable product image after checking available sources. Otherwise apply these defaults without a confirmation round:\n\n- **Length:** 15 seconds, made as one `reference_to_video` generation, whenever the user names no length; honor an explicit length of 5–15 seconds. Never ask for a length. For a longer request, explain the single-clip limit and settle a shorter version or a separate longer-video workflow without adding narration by default.\n- **Presenter:** none; hands only, as set out above.\n- **Voice:** none. Sound comes from the product, faint room tone, and any music, all generated in the clip.\n- **Opening hook:** on, one short bold phrase added with the Captions skill in Python after the raw result is shown. \"No captions\" or \"no text\" turns it off; then show only the raw version rather than a duplicate export.\n- **Music:** set by the mood and generated in the clip: none for calm ASMR; light instrumental music, mixed below the product sounds, for fresh, playful, and luxurious moods. Honor any supplied music preference; otherwise choose and record it internally.\n- **Product images**, when a product is shown: the supplied photos; if there are none, official product images found online, which you say you are using. Ask for a photo only when none can be found. Never generate or substitute a lookalike product.\n- **Frame:** 9:16 at 1080p; this format is portrait only, so say so if another shape is asked for.\n\nCheck whether a sandbox can run Python, read the completed media, render an overlay, and return the edited file. If not, still generate and show the raw video, and state the observed reason the captioned version cannot be made here. Do not move the hook back into the video model or imply that captions were added. If Python rendering is available, use it without a separate permission request.\n\nPreserve the user's requested location, mood, treatment, text language, shot list, and on-screen text. Infer audience and purpose from the brief, product, or site. Never ask the user to choose models, clip counts, transport types, reference roles, or rendering internals. Use the references to establish mechanics, such as how a pump, screw cap, or latch works. Choose evidenced interactions when an optional mechanism is unclear.\n\nUseful references show the complete product, important details, packaging when relevant, and any key mechanism or use action. A short real handling clip can establish both mechanics and its characteristic sound. Do not demand a professional shoot, multiple angles, separate recordings, or a prescribed number of files when the supplied media already suffice. If the user offers to capture more, suggest stable phone footage in soft light, a clear close-up of the action, and a quiet nearby recording of its sound; avoid room noise and music covering the product.\n\nResolve the product/variant, highlight, intended mood, text language, and any essential exact CTA or offer from the existing brief. Choose the creative details yourself. Do not invent a mechanism, contents, or outcome: use a supported interaction or payoff when the uncertain detail is optional. Ask a targeted factual question only if the user's specifically requested demonstration depends on an unknown fact that the references cannot establish. Missing mood or styling preferences never block production.\n\n**Attachments:** import each relevant attachment once with `import_asset_from_chat`, sending the representation the exposed adapter accepts: the absolute local path for `file: string`, or the host's actual `{file_id, download_url}` object for the object form (limit 200 MiB). Never fabricate a path, `file_id`, or URL, and never ask the user to reselect a file that imported. Keep the returned `asset_id`; `\"processing\"` is not proof of readiness. If an import fails with a resumable asset, resume it instead of importing again. If no usable representation exists or an import fails, and `open_asset_library` is listed, open it once and ask the user to add the same files there; if no bridge exists, name the missing one precisely. For a product page, use authorized reading to find the real product images and visible details, and keep marketing claims distinct from packaging facts. Never turn a file object into a path string. Resume with the schema's resume field (`resume_asset_id` or `resumeAssetId`). Open `open_asset_library` only for that fallback, a photo request, or when the user asks to browse their HeyGen assets. Use raw upload (`create_asset_upload`, a real PUT from an execution environment, then `complete_asset_upload`) only when those tools are exposed and usable. Try the compatible import before reporting failure, and report a missing bridge separately from a real HeyGen upload error.\n\n### Write the product facts and hands description\n\nBefore the script, write two short text notes. They are never images; the storyboard prompt and clip prompt paste them verbatim.\n\n**Product facts**, when a product is shown. A real product image is required: never generate a product from a name or description, substitute a lookalike, or fill a gap with a stock image. For the source photos used to establish these facts, isolate the exact product and variant from a multi-product or banner image where code permits; otherwise use that image for claims only and say so in one sentence. This source-photo cleanup is not a requirement to crop the generated storyboard. Record the object count, silhouette, proportions, colors, material, finish, closures, controls, visible lettering, handling states (cap attached, cap removed beside the bottle), and one size anchor, relative to a hand or to familiar surroundings, never invented dimensions. State part counts, attachments, and the side of each asymmetric part positively (one bottle with one pump fixed to it; one handle on the right when the logo faces the camera). Mark each side photographed or inferred; an inferred side never appears in a storyboard or shot, and if the user wants it shown, ask for a photo of it. Keep visible facts, user-confirmed mechanics, and claims separate, with supplied claim wording exact; preserve genuine branding and never introduce another brand.\n\n**Hands description:** describe one adult's skin tone and texture, nails, sleeve color/material, and any accessories with the side each is on. Keep faces and bodies out of the planned frames; there is no need to invent facial features or request a presenter portrait. When the user supplies a hand/handling reference, use its visible details and a suitable frame as storyboard input; the user must be authorized to depict the person. Otherwise choose plausible adult hands without stereotypes or invented credentials. Keep the same hands, sleeve, and accessories in every interaction. Generated hands may be invented; products may not.\n\nAdd the sound inventory to the product facts, each sound with its visible cause.\n\n### Write the timestamped script\n\n**Clip.** Make the whole video as one HeyGen Video 1 generation. Specify its exact shot count, every shot's time span, and the chosen transition at each cut. Its `duration` is the requested or default length in whole seconds: 15 by default, never more than 15. The full timeline must fit that duration without overlaps or gaps; transition effects fit within it, not on top as extra runtime.\n\n**Risky actions.** Liquids, thin applicators, hinges, cables, transparent parts, and camera arcs can duplicate or distort. Stage at most one complex interaction per shot, with clear contact, a simple camera move, and a visible endpoint. Separate successive mechanisms into distinct shots and retain the resulting states. Use low-risk interactions for the other beats, such as sliding packaging, lifting an insert, touching a texture, setting the product into place, or showing a supported use result. Do not fill the fast cut count with repeated static beauty shots or stack several mechanisms into one rushed shot.\n\n**Runtime.** A finished video within about 10 percent of the requested length meets the request unless the user asked for an exact length. Never stretch footage, loop an action, freeze an ending, or cut a sound short to hit a number. A requested cut is a creative instruction, not a guarantee. When the user asks for an exact length, state the actual timing limitation in a progress update without turning that update into a confirmation gate.\n\n**Story.** Write the whole story first. Begin with a quick product entrance when it suits the product, or a purposeful action or satisfying product sound already in progress, never a logo card or a slow reach. For an entrance, specify the brief setting-only interval, entrance path, and contact time in a continuously full-frame shot; keep hook timing in the separate caption plan, never reserve a physical area for it. Every later shot adds evidence, advances an action, reveals something, or resolves a question, and only the end gets the payoff. Plan no unearned holds, replayed introductions, actions that outlast their purpose, or broken physical causality, such as an emptied glass that refills without a new pour.\n\n**Claims.** Ground on-screen text and visible results in verified mechanics, visible details, and user-supplied claims. Everyday benefits evident from the design need no source. Preserve supplied claim wording, and omit invented testimonials, usage history, statistics, or comparisons rather than adding a confirmation step. If a claim essential to the user's requested concept lacks evidence, ask for that specific fact. Never make medical or health claims, and never let sound, mood, or visuals strengthen a supplied claim.\n\n### Make one mood and product storyboard\n\nGenerate **one image for the whole video**, using the host's OpenAI image generation and real product photos as actual image inputs. Prefer its quality setting when exposed; never invent model or size parameters. This is a mood and consistency reference, not a contact sheet of every planned shot. Show a recognizable hero view plus roughly three to five representative interactions or product states within the same image: enough to establish silhouette, material, scale in the hand, handling, setting, and the chosen lighting/color treatment. Choose the layout for clarity; a compact landscape 16:9 board usually gives the product room. It does not need one panel per shot, portrait panels, exact gutters, or a separate image for each scene.\n\nPaste the product facts and hands description into the image prompt and supply the real product images through the supported input. Ask for the same product, variant, hands, sleeve, surface, and treatment across all views. Show only evidenced sides and mechanically plausible states from the planned story. No faces, duplicated physical products within a view, invented packaging, numbers, labels, hook text, or added lettering. Genuine branding remains accurate to the supplied photos. The board can show the same object in separate views; keep one hero product throughout the generated sequence, with no duplicates.\n\nChoose the board's aspect ratio with the video tool's actual controls in mind. When output `aspectRatio` is supported, pass 9:16 explicitly for the video regardless of the board's shape. If output shape follows the first reference and cannot be set, generate this single board in 9:16 from the outset. Do not distort, split, or crop its panels into separate references. Check the returned image dimensions and whether the live tool can accept them; do not invent an exact reference-image ratio requirement from the output-resolution rules.\n\nInspect the one board internally for product silhouette, part counts, label spelling and placement, true color, hand continuity, credible interaction states, and the selected light/grade. Reject invented sides or mechanisms. If it drifts, regenerate the board once from the original real photos with a targeted correction, never by editing a drifted product. If it still fails, use the original product-photo fallback below and note the limitation in a progress update. Never send a known inaccurate product reference to generation or stop to request storyboard sign-off.\n\n### Finish the internal plan and proceed\n\nKeep the single storyboard, complete timestamped shot list, product-state progression, sound cues, transitions, exact opening hook, and settings in the production notes. Do not present them as an approval package or require a reply. In a concise progress update, state the chosen treatment and that the video makes one HeyGen clip, then continue in the same run.\n\nThe clip is a HeyGen generation that counts against the user's plan. While preparing, call `get_current_user` once. When it shows the free plan or no remaining credits, add one plain sentence to the progress update stating the returned plan or allowance and that this video uses one generation; this is information, not an approval request. State only what HeyGen returns; never guess an allowance, a cost, or a renewal date. Whenever describing a plan limit, say only what the current plan includes, the limit, and any renewal date HeyGen states; never list plans or prices, promote an upgrade, or link to a pricing, checkout, or upgrade page.\n\nUse the latest user instructions. If the user changes the brief before submission, update the affected script or prompt and proceed. Regenerate the one board only when the product, hands, setting, treatment, or represented interactions change; a hook-wording or cut-timing change alone needs no new image. Number versions so only the current plan reaches the video model. Honor an explicit review-first request, but do not invent one.\n\n### Send the single reference image\n\nImport the **whole checked board once** with the adapter's supported import/upload path (see Attachments). Pass its returned ready asset or accessible URL as one item in `reference_images`/`referenceImages` for `reference_to_video`. Do not crop panels, generate per-shot images, create a nine-reference requirement, or use it as an image-to-video first frame. Preserve the board's composition during transport. A supplied handling video or real product-sound recording may also guide mechanics or sound when authorized and supported; neither creates a need for scene-by-scene image references.\n\nIf the board cannot be generated accurately, imported, or accepted by the live tool, use the original real product photo(s) as the identity reference and carry the chosen mood and full shot sequence in the text prompt. Explain the substitution in a progress update and delivery note, then continue without requesting permission for the fallback. Never substitute an invented product or silently generate from text alone; if no real usable reference remains, explain the missing input before spending. Keep the distinction between a missing file bridge and a rejected asset.\n\n### Generate the clip\n\nUse `reference_to_video` with `model: \"heygen-video-1\"`, an explicit integer `duration` of 5–15 seconds (15 by default), output aspect ratio 9:16, and 1080p resolution. This generation produces the raw footage and sound; the opening hook is added afterward in Python. Send the single board as a real `url` or ready `asset_id` reference; map snake_case names to camelCase only when the callable schema uses them. Use `prompt_enhancement: \"disabled\"` when available for the tightly authored timeline; preserve the specified actions and pacing. Stay below the live prompt limit (currently 16,000 characters) and within its asset limits. Inspect the live schema rather than inventing transition or overlay fields: footage, sound, and visual-treatment direction belongs in the prompt; hook copy and styling belong in the separate caption plan. Never switch accounts or environments silently, and settle an incompatible required route before spending.\n\nStart the prompt with the actual duration and shot count: \"One complete 15-second portrait voiceless product ad, with 14 distinct shots and 13 cuts. Execute every timed shot below; do not collapse them into a few long takes. Each shot advances the interaction, with no repeated actions or product-state resets.\" Substitute the planned count and duration. Use plain sections for reference role, product and hands invariants, mood/look, timed shots and transitions, audio, continuity, and exclusions. Do not include the hook wording or ask the model to render it.\n\n**Give the whole board this explicit role:**\n\n> Image 1 is a mood and product-identity guide showing the same product under different interactions. Its layout is NOT the video layout, NOT a sequence of literal start frames, and NOT a frame to animate. Use it to keep the product's shape, materials, colors, details, hands, and chosen visual treatment consistent. Render full-screen live-action shots of one hero product, following the timed action list below. Never show a storyboard, collage, contact sheet, panels, borders, split screen, repeated tiled products, or a camera panning across the reference image. The written timeline controls the actions and cuts, regardless of how many views are on the board.\n\nFor a real-photo fallback, replace that paragraph with the actual reference roles: the photos establish product identity and mechanics; their composition/background need not be copied. Never describe a fallback photo as a generated storyboard. A style-reference video guides only the chosen edit/look unless it also establishes verified mechanics of this exact product; do not copy its brands, text, or unrelated props.\n\nPaste the product facts and hands description verbatim. State part counts, attachments, asymmetric details, and the initial product/packaging state. Each timed shot specifies framing, one principal interaction, its resulting state, its synchronized product sound, and the transition to the next shot. Cover 0.00s through the planned duration without gaps. Preserve each state until a shown action changes it: removed wrapping stays removed, accessories stay where placed, and an open case closes only when a hand closes it. Nothing moves without a visible hand or a physically clear force; a still product permits camera movement, not self-motion.\n\nFor example, a short excerpt for an evidenced sliding-sleeve package might read:\n\n> 0.00–0.70s: overhead close view, already mid-action as the fingers slide the sleeve off the carton; dry cardboard friction, sleeve finishes beside it. Hard cut at 0.70s.\n>\n> 0.70–1.55s: diagonal close view, thumb lifts the now-exposed lid; brief cardboard flex, contents become visible. A soft warm 3-frame light leak leads into the next shot without hiding the contact.\n>\n> 1.55–2.40s: macro view, fingertips lift the visible protective insert clear; fine paper rustle, the product beneath is now exposed. Hard cut; no replay of the sleeve or lid action.\n\nThis is only an excerpt: the actual prompt lists every shot through the final payoff. Use only interactions supported by the real product. Fast cuts must not skip a necessary mechanical cause or turn a reveal into several repeats.\n\nPut the chosen **visual treatment and transitions** directly into the video prompt, not only into the board: light direction, shadow depth, white balance, saturation, material highlights, grain or no filter, and the selected effects at named cuts. Keep consistent exposure within shots and real product color throughout. Use believable hands and contact, no faces, no camera passing through objects, no unsupported sides, no waxy or exaggerated skin texture. Every shot, including the opening, fills the entire video frame.\n\nInclude this framing instruction in the video prompt:\n\n> Fill the entire 9:16 frame with live-action footage from the first frame through the last. No margins, padding, letterboxing, pillarboxing, blank bands, borders, inset picture, or reserved caption area. Do not shrink the scene, zoom out, or move the product aside to make room for text. Generate no added text, titles, captions, subtitles, or watermarks; preserve the product's genuine printed branding.\n\nWhen an entrance fits the product, add an action direction such as:\n\n> 0.00–0.30s: the real stovetop fills the frame edge to edge. At 0.30s a hand brings the pan in from outside the frame and sets it on the stove by 0.90s, with a synchronized contact sound. Keep the same natural framing throughout; only the product enters the setting. Continue into the next timed action without an empty hold.\n\nAdapt the object, setting, and exact timings to the real product and full shot list. This is a brief interval before the product enters, not physical space for text. Never include a request to leave room for captions, or put the hook wording in the video prompt or storyboard.\n\nDescribe native audio as carefully as the picture: close material-specific sounds synchronized to visible causes, faint consistent room tone through the final frame, and the planned hero sound. Any original instrumental music stays below the product sounds and ducks around key contacts; when off, request no music. Ban speech, narration, whispering, breathing, vocals, and lyrics. Preserve sound tails across quick visual cuts when appropriate, with no clipped final contact or silent outro.\n\n**Before submitting**, check the exact shot count against the complete timeline, distinct interactions and state progression, the single reference's nonliteral role, the chosen grade/transitions, edge-to-edge footage with no caption margins, no generated text, no voice, music setting, portrait output, and duration. Keep the hook wording and timing in the separate caption plan, or omit that plan when the user requests no text. Do not require a reference image for each shot or cap the shot count at the image-reference limit. Resolve a real input or schema blocker before spending; do not use an avatar engine, Video Agent, Studio, or a digital twin as a fallback.\n\nSubmit once and record the prompt, board version and asset, settings, returned `video_id`, and current state. Call `show_video` once with that ID immediately, including while generation is pending, to show the **Raw model output** in the inline player. If no player is available, display the completed media through the host when ready. Keep that raw result available; do not replace it with the edited export.\n\n**Keep the task running through generation and the hook edit.** After mounting the player, call `get_video` with the same ID and repeat every **15 seconds** while generation is pending or processing. Wait between calls; honor a longer server-required delay when returned. Poll silently: do not narrate individual checks or send routine \"still generating,\" \"not finished yet,\" or elapsed-time updates. The player supplies visible progress. Its push updates do not replace these status reads, because the agent needs the completed media to continue editing. Do not end the turn, wait for another user message, or abandon a pending render after fifteen minutes or any other arbitrary elapsed-time cutoff.\n\nWhen `get_video` confirms completion, leave the status-polling loop and immediately retrieve the completed raw media, using `get_model_video` only if needed for model details or a fresh `video_url`. Continue in the same run through the Captions skill, Python rendering, inspection, and display of the separate captioned version. Completion of the raw render is a handoff to editing, not task completion: do not finish until the hook caption has been added and the edited result shown. Honor a no-text request, an explicit user stop, or a real terminal failure or unavailable captioning capability; report the specific blocker honestly rather than claiming success or polling a failed render forever.\n\nRetry a retryable read error once after its delay; never create another clip to check progress. Distinguish a failed lookup from a failed render and reconcile an uncertain creation outcome with status reads before any new submission. Never invent batch APIs, idempotency keys, media IDs, or URLs. Record the clip ID and current stage before waits or interruptions. For a failed or cancelled render, report the actual reason; do not automatically create extra videos. When the user requests a retry, perform that replacement without asking for confirmation again.\n\nIf HeyGen refuses the clip because of the plan's allowance (HTTP 402, `quota_exceeded`, insufficient credit, or a message that the allowance is used up), never retry automatically. Tell the user that the video was not made, with only the limit and any renewal date HeyGen states, following the plan-limit guidance above. Offer to make it once the allowance renews only when HeyGen states a renewal; do not invent one.\n\n### Add the opening hook with the Captions skill\n\nAfter showing the raw model output and confirming generation has completed, use the [Captions skill](../captions/SKILL.md) in the available Python sandbox. Pass the completed raw clip, its dimensions and duration, the video mood and visual treatment, and the hook wording/timing. Give this format-specific brief: **one catchy hook caption, big and bold, styled to fit the actual video's palette, typography, energy, and overall vibe, appearing only at the beginning**. Use roughly 2–5 words, visible immediately or within 0.3 seconds, targeting about 1.5–2 seconds of reading time when the footage allows, then completely gone. When the opening includes an entrance, inspect when the product actually enters and overlay the hook directly on the full-frame setting before its arrival. Clear or reposition the text before it would cover the arriving product or hands, shortening the hold if needed. Use only the existing footage and change the overlay, never the video's framing or timing; do not create margins, padding, blank bands, or a caption panel. Honor exact user wording and a no-text request.\n\n**Require a big, bold, deliberately styled hook.** Choose a distinctive font and usually a color treatment that fit the video's mood; give the lettering enough scale, weight, and character to grab attention. Do not settle for boring, generic default text just because it is readable. Inspect the rendered opening and revise the typography, color, or layout locally if it feels bland. Even a calm or natural treatment should feel intentionally designed; keep the styling readable and coherent with the footage.\n\nUse the Captions skill's opening-hook, layout, Python-rendering, and inspection guidance. This is a hook-only handoff, not its ordinary UGC speech-subtitle preset: no transcription, word alignment, subtitle track, mid-video text, or closing caption. Match the hook to the footage rather than imposing a fixed white subtitle style or bottom position. For this parent format, show raw output first and the captioned result second; do not apply a final-only display rule. Carry forward the user's production request without another approval step.\n\nKeep the original raw clip intact. Render a separate captioned export with the same footage, cuts, framing, duration, and native audio; only the opening text treatment changes. Let the Captions skill check spelling, timing, style fit, safe placement, and readability over the actual video, and fix caption defects locally. Continue through fixable local rendering errors until the hook is added and the export is ready to show. If a sandbox or required media/rendering access is unavailable, or a concrete rendering failure prevents completion after local recovery, preserve and show the raw output and explain the specific limitation. Do not ask the video model to generate the hook as a fallback or claim a captioned version exists.\n\n### Deliver both versions\n\nLeave the **Raw model output** visible, then show **With hook caption** as a separate playable result through the host's media display using the actual exported file or URL. Do not overwrite the raw file or replace its player. When the raw player is already mounted, keep it and add only the edited result. Include clearly labeled references to both versions at completion so the user can reopen each. With no text requested or no working caption path, deliver the raw version and state why there is no second version.\n\nUse a real HeyGen ID only for tools that accept it; never pass a local captioned file as an invented video ID. If display fails, retry the same media rather than regenerate. Give measured duration when available. Link the raw clip to its HeyGen page, made by appending the `video_id` that `reference_to_video` returned to `https://app.heygen.com/videos/`, as in `https://app.heygen.com/videos/<video_id>`, so the user can open, download, and reuse it from their account. Use that page as the lasting raw reference, not the expiring `video_url`; refresh a raw playback or editing URL with `get_model_video` when needed. Keep the captioned export's separate file or URL available, and do not claim it is saved in HeyGen unless it was actually uploaded.\n\nWhen inspection is available, sample the raw footage for distinct actions, continuous product states, absence of a literal storyboard layout or added lettering, full-frame footage without caption margins, and the chosen treatment. Check sound when listening is available and probe technical properties when tools are available. Report material limitations honestly; these checks do not authorize automatic extra generations. A requested footage fix authorizes that replacement without a second confirmation. Caption defects use a local rerender of the same raw footage.\n\nAsk for feedback on the **mood, progression, product fidelity, sound, and opening hook**. For a revision, use the observed issue:\n\n- **Hook:** one short bold phrase, visible immediately, exact spelling, readable over the opening cuts, then gone; no accidental extra text.\n- **Progression:** each cut advances a distinct interaction or product state. Replace repeated handling, beauty poses, and re-openings with a useful next action.\n- **Pace:** the requested frequent cuts occur, with readable contacts and one deliberate payoff; remove dead reaches and long generic holds.\n- **Treatment:** hard cuts or the selected effect family fit the mood, and the grade or natural look stays coherent without changing the product color.\n- **Sound:** product contacts have visible causes, the hero event lands, music stays subordinate, and there is no voice or clipped ending.\n- **Fidelity:** the actual product, plausible hands, correct mechanics, and state progression survive; the board's grid/layout never appears as footage.\n\nWhen the user requests variants, change the concept, opening, treatment, setting, camera language, or music choice purposefully while keeping the same product facts. Variants remain single portrait clips of up to 15 seconds; do not automatically produce a test pack. Use campaign metrics only when supplied and relevant, without promising attribution or conversion performance.\n\nFor a requested revision, preserve the established product facts, storyboard, and unaffected decisions. Change hook wording, style, placement, or timing by rerunning the Captions skill against the saved raw clip; do not regenerate footage for a caption-only edit. If the user requests different footage, change the video prompt narrowly and regenerate the board only when its represented content or look changes, then show the new raw result and caption it. A new model render may change other details; do not promise a frame-identical patch. Do not add narration or change the product to fix the result.\n\nKeep a production ledger of the user's request and any later revisions, the one storyboard's version and dimensions, reference asset IDs, evidence-backed product facts and photographed versus inferred sides, hands description, complete timed script, exact hook and placement, caption style/timing and reusable code, visual treatment and transitions, music choice, clip ID, current status, raw source, and separate captioned export. Store no secrets and do not treat expiring links as permanent. Reuse accepted inputs and refresh expired URLs on follow-up rather than regenerating. Never publish to social accounts, create campaigns, or message third parties without separate explicit authorization and real publishing tools.\n"
}