Update to HeyGen

{
  "description": "Create creator-led UGC unboxing videos, 30 seconds by default, with HeyGen Video 1, moving from a sealed package to a one-time reveal, product inspection, and grounded reaction. Use when the creator's discovery is the story, rather than a product-only packaging shot.",
  "included_files": [],
  "name": "ugc-unboxing",
  "skill_md_contents": "---\nname: ugc-unboxing\ndescription: Create creator-led UGC unboxing videos, 30 seconds by default, with HeyGen Video 1, moving from a sealed package to a one-time reveal, product inspection, and grounded reaction. Use when the creator's discovery is the story, rather than a product-only packaging shot.\n---\n\n# UGC Unboxing\n\nBuild anticipation around a real package, reveal early enough to reward attention, then show what was discovered. The creator's changing attention and specific reaction make this Unboxing; a carton opening alone is Product, so do not add a creator to a product-only request.\n\n## How this skill works\n\nThis file is self-contained: read all of it before producing, and do not load another UGC format. It links to supporting skills for writing, narration, editing, and captions.\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 ordinary production: importing supplied inputs, writing the product facts and person description, making the storyboard, and, after the one approval below, the voiceover, the storyboard crops, video clips, status reads, and assembly, within 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. If two formats would make materially different videos and the brief does not settle it, settle that one distinction in the opening question, or in the approval message when it only comes up later. Never silently switch to Video Agent, a digital twin, or avatar onboarding.\n\nEvery video must sound and feel like someone talking to a friend while showing something useful, never like a sponsored pitch. Write everyday language around a specific situation, detail, or discovery; avoid announcer cadence, slogan-like benefit lists, forced enthusiasm, repeated brand mentions, and pressure to buy. Keep handling, reactions, and pacing as natural as the speech. This does not remove sponsorship disclosures.\n\n## The viewing promise\n\nThe spine is PACKED → REVEAL → PRODUCT-FOCUS → SATISFACTION. The reaction must come from something visible: an object emerging, a finish catching daylight, a verified folding action. A synthetic gasp or \"I'm obsessed\" is not a revealed detail. Purchase history such as \"it finally arrived after weeks\" follows the claim rules below.\n\n## References and package\n\n- **References:** the product photos and a written description of the creator. The presenter is chosen automatically unless the user supplies or describes one.\n- **Package:** by default a plain unbranded brown shipping box; say so in the settings line, so the user can send a packaging photo instead. A supplied package photo controls packaging only, is not part of the product facts, and feeds the storyboard beside the product photos.\n- **Contents:** verify what the box contains and how the product comes out safely and visibly. A generic box is staging, not a claim about retail packaging. Do not invent brand graphics, inserts, wrapping, accessories, gifts, or \"everything included\" statements. Packaging must plausibly contain the product; do not derive exact dimensions from an image. If the exact package cannot be recreated, say so instead of substituting a fictional branded box or an unrelated beauty shot.\n\n## State continuity is the story\n\nKeep one creator, one hero product, and one package, and track this state table in the production ledger:\n\n| Stage | Package state | Product state | Creator action |\n| --- | --- | --- | --- |\n| Opening | Sealed/taped and visibly closed | Fully hidden | Attention on the unopened box |\n| Reveal | Open, shifted to the edge or removed | First visible appearance | Remove or present the object plausibly |\n| Inspection | Absent | In hand or on a stable surface | Show a real detail or simple verified action |\n| Resolution | Absent | Same object in final useful state | Small specific reaction, then natural finish |\n\nThe product never appears early behind the sealed box; describe the hidden state firmly in the opening clip. The box never returns after the reveal, including in later clips, and is never reset to closed for a new segment. No second product appears as the first emerges. A cut may skip tedious opening, but before and after positions must make physical sense: a hand starts a verified opening, then a hard cut shows the open box and the product already lifted and stable. Do not ask one shot to cut tape, unfold flaps, remove cushioning, free, rotate, and react while speaking; split into clear state transitions.\n\n## Runtime and progression\n\nFor 15s, use a compact arc: about 0–2s sealed anticipation, 2–5s reveal, 5–10s one or two useful product views, 10–15s a visible action and specific resolution. These are editorial beats inside generation clips. For 30s, finish the reveal early and add two evidenced details or a first-use demonstration; for 45s, add a different interaction or use context. If there is nothing more to show, ask in the approval message for useful product information instead of padding.\n\nThe first shot already has purposeful hand movement. Reveal by roughly the first third unless the user wants longer suspense, with the hero clearly visible and readable at phone size. Alternate a creator reaction with object-led detail rather than interchangeable smiling poses. Each continuation begins mid-thought with the product already out. A CTA is optional and must follow the user's real destination.\n\n## Speech and performance\n\nDefault to native speech for the visible creator: compact exact lines pointing to a verified, visible detail, with a brief earned pause at the reveal rather than adjectives over every transition. Direct a restrained reaction: eyes move to the revealed feature, a small pause, a natural change of expression; never a reaction before the product appears. A generated expression is not evidence of customer satisfaction. For off-screen narration over creator actions, use the voiceover-first flow below and keep the creator's mouth closed.\n\n## Prompt construction\n\nRestate product, package, and creator invariants in every prompt, with local shot times, hard cuts, framing, package state, hand placement, product visibility, exact dialogue, and silent directions. Tell the model which stage the clip covers; later prompts say the package is gone and the reveal must not repeat. In the storyboard, panels for shots after the reveal, as the state table sets it, show no package, show the already-unboxed product, and never add product details. Check each panel's package and product state against the state table. Keep one hero, a plausible fit in the box, no passing through cardboard, stable hands, and the correct item throughout.\n\n## Production workflow\n\n| Step | Result | User |\n| --- | --- | --- |\n| Start | Opening question answered, inputs imported | **Required:** answer, or say \"go\" for the defaults |\n| Prepare | Timestamped script, storyboard, settings line | None |\n| Approve | One message showing all three | **Required:** approve or ask for changes |\n| Produce | Voiceover where used, storyboard crops, Video 1 clips, assembly, captions | None |\n| Deliver | Final video once, then the clip links | Reviews the result |\n\nThe user sees the people, product, words, and settings together and approves them once before any paid video generation. Silence, elapsed time, or general delegation (\"just make it\", \"don't ask me anything\") settles defaults but does not approve an unseen storyboard or script; skip the approval only when the user names it, for example \"skip the approval\" (choosing \"lock it in\" when setting up an automated series names it for that series). Do not add other rounds: no separate storyboard and script approvals, no per-clip approvals, and no permission requests for status reads or retrieval. If later feedback materially changes an approved storyboard or script, revise it and get approval for that change before dependent generation. Respect a real host-enforced approval or access denial and describe its actual requirement.\n\n### Ask the opening question\n\nBefore any script, reference, or storyboard work, send one opening question. It lists the length, aspect ratio, resolution, any reference images or links, captions, and anything else the user wants, such as a setting, tone, language, script, or shot list, each with the default used when the user does not give one. It also says in plain words what HeyGen will generate for this format at that length, as in the example, and, when the host's image tool makes the storyboard, that the storyboard is not a HeyGen generation. Choices the brief already settles show as settled and are not asked again. When it is unclear what kind of video is wanted, for example when no product, site, or subject can be identified, ask that in the same message. Wait for the reply: \"go\" or \"use the defaults\" applies every default, and any choice the reply leaves open takes its default. A first message that already says to use the defaults or not to ask anything counts as that reply: state the settings in one line and go on. In an automated series, the setup choices and V01's answers count as the reply for every later video, and a scheduled run never asks. The defaults, which the approval message shows again and where the user can still change any of them:\n\n- **Length:** 30 seconds whenever the user names no length; the connection's default of a single clip of 15 seconds or less for an unstated length does not apply to this format. Ask about length only in the opening question. Honor 10, 15, or 45 seconds or another explicit length up to 45 seconds, the hard maximum; for a longer request, say so in one sentence and use 45.\n- **Aspect ratio:** 9:16 vertical, or 16:9 horizontal when the user chooses it. With 16:9, the storyboard panels, their crops, the clips, and the export are all 16:9.\n- **Resolution:** 1080p, or 2K or 768p when the user chooses it; 768p is shown to the user as \"about 720p\", in the opening question and the settings line. Video 1 makes 768p, 1080p, and 2K at both 9:16 and 16:9; pass the chosen value explicitly to `reference_to_video` (`768p`, `1080p`, or `2k`) and export at it.\n- **Presenter:** as this format sets out above. A person in supplied media must be the user or someone they are authorized to depict. If the user asks for no person in a format that needs one, say in the approval message how the video changes, for example a hands-only Product video instead.\n- **Voice:** one real voice chosen to suit the product and audience: from the voice catalog for a voiceover, or written as a voice description for a creator's native speech. Never invent a voice or generate audition samples.\n- **Captions:** on, through the [Captions skill](../captions/SKILL.md) after assembly.\n- **Product images**, when a product is shown: the photos or product links the user supplies, including in reply to the opening question; 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\nFor example:\n\n> Before I start, a few quick choices. Anything you skip uses the default:\n>\n> - **Length:** 30 seconds (anything up to 45)\n> - **Shape:** 9:16 vertical, or 16:9 horizontal\n> - **Resolution:** 1080p, or 2K, or about 720p\n> - **References:** product or packaging photos or links, or a photo of the person who should unbox it? Otherwise I'll use the official product images, a plain brown shipping box, and a creator I describe.\n> - **Captions:** on\n> - **Anything else:** a setting, tone, language, or script you want\n>\n> At 30 seconds, HeyGen makes 2 video clips, with the speech recorded inside them and no separate voiceover: one clip for each 15 seconds or part of it, so 1 clip up to 15 seconds and 3 at 45. The storyboard picture comes from this app's image tool, not HeyGen.\n>\n> Reply \"go\" to use the defaults.\n\nPreserve the user's requested location, appearance, tone, language, accent, shot list, and script. 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. Put any open question about mechanics, such as how a pump, screw cap, or latch works, into the approval message rather than a separate round.\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 person description\n\nBefore the script, write two short text notes. They are never images; the storyboard prompt and clip prompts 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. Use an image as a product input only when it shows one product in one state; where code can run, crop a composite, multi-product, or banner image to the exact product so the real label and color survive, and otherwise use it for claims only and say so in one sentence. 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**Person description**, when a person or hands appear: apparent age range, face shape, eyes, brows, nose, lips, distinguishing marks, skin tone and texture, hair color, length, texture, and parting, build and posture, and the wardrobe for the ad (each garment's color and fit, footwear, and accessories with the side each is on, with no invented logos or readable text). For hands only, describe the skin tone, sleeve, and any accessories. A supplied photo or quick video of a real adult is the identity authority: describe that person, use a clear front-facing frame as an input to the storyboard, and keep a supplied video for `reference_videos`; the user must be that person or authorized to depict them. One description depicts exactly one adult, never a public figure unless the user is authorized to depict them. Otherwise describe the person the user asked for, or a plausible adult suited to the product and audience, with no stereotypes or invented credentials. Generated people may be invented; products may not.\n\n### Write the timestamped script\n\n**Clips.** Use the fewest HeyGen Video 1 clips, each up to fifteen seconds: fill each to fifteen and put the remainder in the last; if that remainder is under five seconds, move seconds into it from the previous clip (10 → 10, 30 → 15+15, 40 → 15+15+10, 45 → 15+15+15). Put several shots inside a clip with hard cuts; never split one shot across clips. With a voiceover, the final clip boundaries come from the narration's timing after approval.\n\n**Risky actions.** Video generation often duplicates or distorts liquids, thin applicators, hinges and other mechanisms, cables, transparent parts, and camera arcs around an object. Put each in at most one clip, staged simply with one hand, the object, and the surface it acts on, and fill other shots with low-risk views such as a static product, macro texture, scale in the hand, or a finished result.\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 spoken words to hit a number. A requested cut is a creative instruction, not a guarantee. When the user asks for an exact length, say in the approval message how closely it can be met.\n\n**Story.** Write the whole story before splitting it. Begin on a purposeful action or a specific spoken hook, not a greeting or setup pose; every later shot adds evidence, advances an action, reveals something, or resolves a question, and only the final segment gets a payoff. Write speech as one continuous conversation; sentences may cross cuts and clip boundaries. Budget about 14 characters per second for English, counting spaces and punctuation (about 210 for fifteen seconds), or about 15 for a voiceover at the default 1.1x (about 225); use 14 when the voiceover stays at normal speed, scale the budget for any other requested speed, and re-fit the script if the user changes the speed in the approval round. Other languages and slower voices need fewer. Plan no unearned holds, replayed introductions, repeated face-and-product poses, actions that outlast their purpose, smiling tails at clip ends, or broken physical causality, such as an emptied glass that refills without a new pour.\n\n**Words.** A line mentions only what is on screen while it plays. Would someone say this to a friend while showing it? Rewrite lines that sound like advertising copy or stage directions; make the first phrase specific to this product, drop repeated product names, and favor contractions and varied sentence lengths. Keep spoken words separate from visual directions; never voice \"bring the camera closer.\" Keep any CTA brief and tied to the user's real destination; never invent \"link in bio\" or an offer. Preserve an exact supplied script. Writing patterns are in [script writer](../script-writer/SKILL.md). Direct delivery to match: a relaxed pace, natural breaths, emphasis on the detail being shown, and the same attitude across clips. Put delivery direction in the voice choice, the voice description, or the prompt, never in the spoken words; a friendly voice cannot rescue sales copy.\n\n**Claims.** Ground speech in verified mechanics, visible details, and allowed claims. Everyday benefits evident from the design need no source. Use supplied testimonial-style lines, usage history, statistics, and comparisons as written; mark any the user did not supply \"[confirm]\" so the approval covers them. Never make medical or health claims, and never let delivery or visuals strengthen an approved claim.\n\n### Make the storyboard\n\nBefore approval, make one storyboard image for the whole video with the host's OpenAI image generation, preferring GPT Image 2.5 in its quality-oriented \"sunburst\" variant at high quality; if model or quality selection is not exposed, do not invent parameters or claim a setting was applied. Supply real images through the supported image input; a filename in a prompt conditions nothing. Build it from the person description and product facts, pasted verbatim, the supplied or official product photos that match the product states it shows, a clear front-facing frame of any supplied person, and any other photos this format feeds to storyboards; never from website screenshots, and never showing an inferred side. When a person's face appears in the video, at least one early panel shows it clearly, front-facing, head and shoulders. Every shot of the whole video gets its own panel, in order across all clips, and later its own crop; a clip sends at most nine crops, HeyGen's reference-image limit, so any shot beyond nine in one clip is a quick accent written in the prompt only, with no panel. Drawing every shot in one image keeps the person and product the same, and the outfit, setting, and light the same unless the approved script changes them, and lets each clip's first panel continue from the state the previous clip's last panel ends in.\n\nThe storyboard is one grid of equal panels, one per shot, read left to right, then top to bottom, in shot order, each panel the start frame of its shot, with the same phone-capture look and natural, healthy skin as the clip prompts. Every panel has the video's aspect ratio, 9:16 or 16:9, and shows that shot's framing and subject state; because each panel is later trimmed to that exact shape, the prompt says to keep the product's identifying detail and any face within the central area of each panel where the shot allows; trimming the edges of the frame is fine. Take the grid (columns × rows) and image size from the table below, which keeps every panel close to its shape at the tool's fixed sizes. When the image size is selectable, use instead the grid whose whole image is nearest square for the shot count, set the image to that grid's exact shape plus gutters, and request the largest size the tool allows. Leave any cells after the last shot empty in the gutter color; never add a shot to fill them. Separate the panels with thin, uniform gutters of one flat plain color and leave no other plain band or margin, so the image can be cut cleanly; nothing crosses a gutter, and the image has no text, numbers, or labels. Never squeeze or stretch a panel. When captions are on, keep essential product detail out of the bottom fifth of every panel.\n\n| Shots | 9:16 panels | 16:9 panels |\n| --- | --- | --- |\n| 1 | 1×1 at 1024×1536 | 1×1 at 1536×1024 |\n| 2–4 | 2×2 at 1024×1536 | 2×2 at 1536×1024 |\n| 5–6 | 3×2 at 1024×1024 | 2×3 at 1024×1024 |\n| 7–10 | 5×2 at 1536×1024, or 3×3 at 1024×1536 for 9 shots | 2×5 at 1024×1536, or 3×3 at 1536×1024 for 9 shots |\n| 11–12 | 5×3 at 1024×1024 | 3×5 at 1024×1024 |\n| 13–20 | 5×4 at 1024×1536 | 4×5 at 1536×1024 |\n\nBefore showing the storyboard, check it. Layout: the planned grid, exactly one panel per shot in shot order, equal panels of about the video's aspect ratio (about 0.49 to 0.67 as wide as they are tall for 9:16, about 1.5 to 2.05 for 16:9) and not stretched or squeezed, uniform plain gutters, and no wide plain bands (empty end cells of the planned grid are expected); the product's identifying detail and any face sit within each panel's central area where the shot allows; trimming the edges of the frame is fine. Product: the silhouette, proportions, colors, part counts, and label spelling and placement match the photos and facts, with no mirrored text, duplicate product, or invented feature. Identity: the same person in every panel, matching the description and any supplied photo, with the face checked in every panel that shows it. Continuity: the outfit, setting, and the product, package, or garment state in each panel are what the script sets for that shot, and each clip's first panel starts from the state the previous clip's last panel ends in. Skin: natural and healthy, neither smoothed nor over-textured, blotchy, or dirty. If the storyboard drifts, regenerate it once from its original inputs with one targeted correction, never by editing a drifted output; if it still fails, show it and name the remaining issue. Show only the final storyboard, in the approval message.\n\nAfter approval, if the voiceover's timing regroups the shots into different clips, give each clip the approved crops of its shots, in order; this needs no new approval and no new storyboard.\n\nThe storyboard is never sent to HeyGen; only its crops are (see Cut the storyboard into shot images). A supplied quick video of the person may stay in `reference_videos`. If no storyboard can be made, say so in the approval message. Then, or later for any clip whose crops cannot be used, send the original product photos and any supplied photo of the person instead, never a generated image of the product, with the product facts and person description in the prompt. Trim each photo, centered, to exactly the video's aspect ratio when that keeps the whole product and any person in frame, otherwise to the other of 9:16 and 16:9, and import the trimmed copy unless the original is already exact. If neither shape keeps them whole, never pad the photo: tell the user and ask for a photo at 9:16 or 16:9. Before the approval message, check in Python which product photos trim whole to 9:16 or 16:9; if none does, fold a request for a photo at 9:16 or 16:9 into the approval question. When a person appears and no photo of them was supplied, also say that the person will come from the written description only and may differ between clips and from the storyboard, and offer a photo of the person, one clip of up to 15 seconds, or a hands-only version.\n\nEvery reference image sent to HeyGen is exactly 9:16 or 16:9, made so by trimming, never by padding. Before each upload, check its exact shape and record its pixel size in the production ledger. If code cannot run, there are no crops: send only photos that are already exact, and tell the user which ones could not be used. If a clip that shows the product would then have no exact image, say so in the approval message and ask for a photo of the product at 9:16 or 16:9; never generate that clip from text alone.\n\n### Ask for approval once\n\nShow everything in one message:\n\n1. The storyboard image, introduced in one line as the start frames of every shot, read left to right and top to bottom, so panel N is shot N in the script table, rather than finished footage; when you found the product images yourself, the source images with their page, so the user can confirm the exact product and variant; and anything else this format shows for approval.\n2. A script table: every shot with its number, its target time span, the visible shot, and the exact spoken words, then the total runtime. Mark who speaks only when the video mixes on-camera speech and voiceover.\n\n   | # | Time | Shot | Spoken words |\n   | --- | --- | --- | --- |\n   | 1 | 0:00–0:03 | Close-up: one hand twists the cap off the bottle | \"Okay, the cap on this is genius…\" |\n\n3. One settings line with the length, the aspect ratio and resolution, the presenter (only where this format has one), the voice, the speed (voiceover only), and captions, for example: \"30s · 9:16 · 1080p · voice: warm, relaxed · 1.1x · captions on (say 'no captions' to turn them off).\"\n\nEvery message that asks for approval, including one asked again after an upload or a change, ends with one bold sentence right before the question, such as **\"Approving this will generate 2 video clips with HeyGen Video 1 and 1 voiceover.\"** Count one clip per planned generation (1 up to 15 seconds, 2 for 30, 3 for 45), and name the voiceover only when one is used; if a later choice changed the count from the opening question, add it, for example \"(up from 2, for 45s)\". Whenever you describe 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\nThen ask one question: **\"Approve, or tell me what to change.\"** Fold into it any product side the evidence does not show (\"Your photos show only the front, so I've kept the back out; send a photo of it if you want it shown\"), any \"[confirm]\" item, and any mechanics question. If the Captions flow cannot run here (no code execution, the final video cannot be read, or a file cannot be returned), or the host cannot run code to assemble several clips or to speed up a voiceover (which then stays at normal speed), say so in this message instead of promising it.\n\nFor a change request, revise only what was named (for a change to some shots, pass the current storyboard as an extra input with the change and ask to keep every other panel as it is, then check every panel again; a change to the person, product, or setting regenerates the storyboard from its original inputs; never edit a drifted output), show the full updated set, and ask again; number versions and use only the latest approved one. Timestamps are targets; small shifts that keep the approved words and shots need no new approval.\n\n### Native speech for an on-camera creator\n\nA visible speaking person speaks natively inside the Video 1 clip, preserving lip sync. Write one voice description per speaker (language, accent, pitch, timbre, pace, and natural delivery, for example \"English, light London accent; warm mid-low voice; relaxed pace, natural breaths, varied emphasis\") and paste it verbatim into every prompt with that person's speech, separate from the dialogue. Quote the exact dialogue, name the speaker, and require synchronized native speech with no other speaker, voiceover, music, or on-screen text; off-screen cutaways inside the clip may continue the same voice. Never add `generate_audio`, `voice_id`, or `lip_sync` to `reference_to_video`. Keep dialogue compact so the action stays readable, at normal speed with no time stretching. Keep the native audio in assembly; never mute a speaking person and dub them with synthesized speech. Prefer one speech treatment throughout; when a video mixes a native-speaking creator with a voiceover, never overlap them and never claim they share a voice. If an exact supplied line is too long for native speech in its clip, propose shorter copy or a voiceover in the approval message; never silently change the words.\n\nExact words come first. Video 1 can garble lines or fill gaps with invented speech, so every clip prompt whose native audio is kept states in its spoken-text section: \"Speak exactly the quoted words, in order. In every interval without quoted words, including before the first line, between lines, during silent shots, and after the last line, there is no speech of any kind: no mumbling, filler words, invented words, whispering, or background voices. Never fill silence with speech and never invent words.\" A clip with no quoted words gets only the second and third sentences. Clips the voiceover owns are muted in assembly and unaffected: they request no speech from the video model.\n\n### Voiceover first\n\nUse this for every off-screen voiceover. After approval, before any video:\n\n1. Synthesize the whole approved narration in one call with `create_speech_without_player` when listed (`create_speech` opens a player), as plain text (never SSML), using the voice from the approved settings line at HeyGen speed 1.0. Never set `speed`, or any other HeyGen speed or rate option, to 1.1 or to anything but 1.0. Follow [narrator](../narrator/SKILL.md) for the tool contract, but never open the voice picker again. Never synthesize one take per clip; every call is charged. When the user supplies a narration recording they are authorized to use, use it instead of synthesis and skip the speed-up unless they ask for one. Never imitate a celebrity or clone a voice from unrelated audio.\n2. Right after synthesis, speed the whole narration track up to 1.1x once, in Python with FFmpeg's `atempo=1.1` filter, which keeps the pitch. This is the default voiceover speed. If the user asks for a different speed, use that speed instead, applied the same way; normal speed, or a host that cannot run Python with FFmpeg, skips this step. Scale the returned word timestamps by the inverse of the speed (1/1.1 by default), or re-align the sped-up file, and use the sped-up duration and timings for every step below. It is the one allowed speed change: one fixed delivery speed applied once to the whole track, never per clip and never to fit a duration.\n3. Add no pauses: no `<break>` tags, SSML pauses, silence padding, any other slowing or speed change after this one, or time stretching, in synthesis or editing. Pictures follow the voiceover, never the reverse.\n4. Split the narration into clips using its duration and word timestamps: keep the approved clip grouping whenever each clip's narration fits 5–15 seconds; otherwise use 5–15 seconds each, the fewest clips, with each boundary at the approved shot cut nearest a sentence or phrase end. Keep the approved shot list: if the clip count changes, spread the approved shots across the clips and never add shots; a format's shots-per-clip rule yields to the approved shots. If no word timestamps are returned, align the audio by transcription; never divide words evenly. Each clip's `duration` is its narration segment rounded up to the next whole second, plus the final clip's payoff tail.\n5. In each clip's prompt, time the shots from the word timestamps, relative to the clip's start, so each visual change lands on the words that name it.\n6. Request no speech or music from the video model. In assembly, mute these clips and lay the narration track over them unchanged, trimming footage to the narration. The final clip may keep about one second of silent picture after the last word for the payoff settle; that is a picture tail, not narration padding, and the voiceover itself still gets no pauses.\n\nIn a video that mixes native speech and voiceover, these steps and the muting apply only to clips the voiceover owns, each a whole 5–15 second clip; native clips keep their audio. Otherwise prefer one treatment.\n\nIf the measured narration misses the requested length by more than about 10 percent, tell the user before generating video and offer a shorter or longer script. If the narration needs more clips than the approval message stated, say so before generating video and offer to trim the script to fit the stated number.\n\n### Cut the storyboard into shot images\n\nAfter approval, split the approved storyboard into one image per shot with Python (PIL or similar). Open the file the image tool returned; if that file is not available to Python, treat it as a cropping failure, never ask the user to download or re-upload it, and never redraw or regenerate panels. Find the content box inside any outer margins, then find the gutters in both directions: full-height columns and full-width rows of near-uniform plain color. If detection does not find one fewer gutter column than the grid has columns and one fewer gutter row than it has rows, divide the content box equally into the planned grid instead. Cut the panels apart left to right, then top to bottom, skipping any empty cells at the end, and trim each crop by the gutter and margin widths measured on the image, not by color, without scaling it; with equal division, inset each cell by the requested gutter width, or about 2% of the cell, instead. Keep the crops only if their number equals the number of panels and each is about the video's aspect ratio (0.49 to 0.67 as wide as it is tall for 9:16, 1.5 to 2.05 for 16:9) and not blank or one flat color; if gutter-based crops fail, retry once with equal division. Then trim the side that is over, centered, to the largest 9k×16k size inside the crop (16k×9k for a 16:9 video), so it has exactly the video's aspect ratio; never scale it unevenly or stretch it, and if more than about 16 percent would be cut, the crop fails. Then look at the crops side by side: each shows one shot, with no gutter line or part of another panel at any edge. Normal phone framing is fine: a crop may trim the top of a head, feet, hands, or background. It fails only when the product's identifying detail, such as its label, logo, or the garment's print, or most of the face is cut off. Crops that pass go ahead with no question to the user; never ask the user about crop framing. Save each crop as a PNG numbered in shot order, give each clip the crops of its shots, and record the storyboard's grid, its requested and returned size, and each crop's pixel size in the production ledger. Cropping fails only when code cannot run, the storyboard is not available to Python, or the crops still fail these checks after equal division. The crops are internal: never show them to the user.\n\nImport each crop with `import_asset_from_chat` in the form the adapter accepts (see Attachments: the crop's absolute local path for `file: string`), or by raw upload where code can reach the network. Never treat an OpenAI file identifier as a HeyGen `asset_id`. Send a clip's crops as its only reference images, at most nine, in the clip's shot order: Image 1 is the clip's first shot, Image 2 its second, and so on. Send them only as reference images, never in a first-frame or image-to-video field. A clip gets all of its crops or none, never a mix: if cropping fails, or any crop is rejected (including for size) or fails to transfer, that clip uses the photo fallback above. Tell the user in the next progress update and again in the delivery note, in one plain sentence per affected clip, which clip used the product photos and why, such as \"Clip 2 used your product photos instead of the storyboard shots, because the storyboard could not be split.\"\n\n### Generate the clips\n\nUse HeyGen Video 1 for all footage through `reference_to_video` with `model: \"heygen-video-1\"`. The connection's general rules sending visual productions over 15 seconds to Video Agent and an unstated length to a single clip of 15 seconds or less do not apply here: this workflow defaults to 30 seconds and meets any runtime with Video 1 clips assembled client-side. Always pass an integer `duration` of 5–15 seconds and the aspect ratio and resolution from the opening question explicitly (9:16 and 1080p unless the user chose 16:9, 2K, or 768p; the tool's defaults are 5 seconds, a frame that follows the first reference image, which for a 16:9 photo is landscape, and 768p), and use `prompt_enhancement: \"quality\"` by default (`\"disabled\"` when it would alter a tightly authored prompt). If the callable schema has no aspect-ratio field, send only references in the video's shape (the shot crops, or photos trimmed to it), since the first image sets the frame, and say so briefly. Pass references only as real `url` or `asset_id` objects, and use camelCase names such as `referenceImages` only when the callable schema uses them. Stay within the tool's limits: at most nine reference images, three reference videos, and three reference audio files. Reference audio only guides generation; it is not a soundtrack. Live tool schemas govern: never invent fields, copy an older API, or claim an undocumented capability is absent. Report a schema gap precisely, settle a material limitation before paid generation, and never switch accounts or environments silently. Do not use avatar engines or tools (`avatar_iii`, `avatar_iv`, `avatar_v`, `prepare_avatar_video`, `create_video_from_avatar`, `create_video_from_cinematic_avatar`), Video Agent, or a digital twin, even as a fallback; an avatar requested as presenter stays in this workflow through references built from real media. An explicit request for an avatar engine needs a separate avatar workflow, settled before any generation.\n\nWrite each prompt in plain sections: start frames, identity and product invariants, environment, timed shots with explicit hard cuts, physical interaction, camera and texture, spoken text or silence (with the exact-words lines for any native audio), continuity, and exclusions. With shot crops, open with: \"Images 1–N are the start frames of shots 1–N, in order. They are plans, not frames to copy. Render one continuous 9:16 video with hard cuts between the shots, and no panels, borders, split screens or text from the images. Match the person, product, wardrobe, and setting in them exactly; only each shot's motion is new.\" with N written as the clip's number of crops and 16:9 in place of 9:16 for a horizontal video, then list each shot with its time span, matching its image. When a clip has more than nine shots, mark each prompt-only accent shot \"[accent]\", leave it unnumbered, and add after the opener: \"Shots marked [accent] are quick inserts with no image or panel of their own.\" When product photos are sent instead of crops, open by saying the same of them: they are product references, not frames to copy; their framing and background are not the video's composition, and the video shows exactly one product. Keep IDs and planning labels out of creative prose. Paste the person description and the product facts verbatim, and state part counts, attachments, and the side of each asymmetric part positively (one bottle with one pump fixed to it). Each shot states framing, subject state, one principal action, and its visible endpoint; the next shot starts from that state. Nothing moves unless a visible hand moves it: in a shot without a hand, the object stays fixed and only the camera moves slightly. When captions are on, keep essential product detail out of the bottom fifth of the frame in every prompt. Start shots mid-action with modest camera moves; never pass through objects, show unevidenced sides, or stack complex interactions; no dissolves or slow motion unless requested. Generate no captions, subtitles, or caption-like lettering in the footage; captions come only from the Captions skill.\n\nAsk for authentic phone capture: natural window light, restrained exposure, deep enough focus to read the object, subtle sensor texture, real materials, and natural, healthy skin as a modern phone records it in soft light: an even tone whose fine texture stays subtle even in a close-up. Avoid waxy skin, beauty-filter smoothing, facial reshaping, oversaturation, glow, heavy sharpening, and decorative bokeh, and equally avoid exaggerated pores, blotchy or grey patches, dirt, sun damage, or freckles, spots, and wrinkles beyond what the person description or a supplied photo shows. When a creator holds a product near the face, frame at least from the shoulders up rather than filling the frame with skin. Place small imperfections in the environment, never on the person or the product. Keep one hero product, plausible hands and contact, consistent gravity, and no mirrors. Restate a continuity lock in every clip (person, product, setting, wardrobe, hands, light direction, prop states), and end only the final clip on the payoff with about a one-second settle; earlier clips hand off mid-thought, and each later clip continues from the prior action rather than reintroducing the product.\n\nSubmit all clips concurrently within service limits and record each clip's prompt, references, settings, `video_id`, and state; clip numbers, not completion order, set the edit order. Status reads are part of the authorized production: poll pending clips yourself with `get_model_video` at the returned interval or about every thirty seconds, and update the user at least every minute. If a render is still pending after about fifteen minutes, stop, say it is still rendering, and resume when the user asks. Retry a retryable read error once after its delay; never create a clip again to check progress. Never call `show_video` or open a player after submission, even though the connection's guidance shows a player after a generation call; poll `get_model_video` yourself, finish assembly and captions in the same run, and show only the final video, captioned unless the user turned captions off. Tell a failed lookup apart from a failed render, and reconcile an uncertain creation outcome with `get_model_video` before any new submission. Never invent batch APIs or idempotency keys. Record IDs, links, and the current stage in the ledger before any wait or interruption; if a real limit or terminal error stops progress, report the incomplete state and never call it delivered.\n\nDo not review finished clips for visual defects or regenerate them: a finished clip goes to assembly, and the user judges the result. If a render fails or is cancelled, explain the returned reason and ask whether to retry that clip; never retry automatically.\n\nIf HeyGen refuses a voiceover or clip because of the plan's allowance (HTTP 402, `quota_exceeded`, insufficient credit, or a message that the allowance is used up), stop submitting and never retry automatically. Keep polling every clip already submitted. Tell the user in plain words which clips are done and which were not made, with the limit and any renewal date HeyGen states, following the plan-limit rule in Ask for approval once. Offer what fits: a shorter video from the finished clips when they stand on their own, or making only the missing clips once the allowance renews. Never regenerate a finished clip, and never call an incomplete video delivered.\n\n### Assemble and caption\n\nAssemble the clips in order client-side by following the [video-editing skill](../video-editing/SKILL.md), at the approved aspect ratio and resolution. Here it only orders, joins, and mixes the Video 1 clips with their voiceover or native audio; add no other footage, stills, motion graphics, or stock. Music only when requested: a track the user is authorized to use, or original instrumental music made in code, mixed beneath the speech. A single clip with no voiceover and captions off needs no assembly.\n\nUnless the user turned captions off, hand the assembled video, approved script, language, and dimensions to the [Captions skill](../captions/SKILL.md), which only adds text layers and never changes footage or audio. If captioning fails, say why (or that the reason is unknown) and deliver the uncaptioned video without claiming captions.\n\nBefore display, run technical checks only: probe the export's duration, resolution, and audio stream.\n\n### Deliver\n\nShow the final video once, only after assembly and captions are finished, through the host's media display with its actual file or link. Only a single clip that needs no assembly and has captions off is shown directly, with its fresh `video_url` from `get_model_video`; with captions on, the captioned export is the final video, never the raw clip. Never pass a Video 1 ID, a local file, or an invented ID to `show_video`. Never show intermediate clips or drafts, and do not show the storyboard again or any crop. If display fails, retry with the same file; never regenerate to fix a player error. Finish the whole production without stopping after a submission or asking the user to come back, apart from the fifteen-minute render wait. Give the final video's measured duration and any material limitation; never claim a frame-accurate runtime or a full inspection without evidence. If display is unavailable, keep the export and report the limitation.\n\nUnder the video, list each HeyGen clip with its time span in the final video and its page in the HeyGen app, made by appending the `video_id` that `reference_to_video` returned for that clip to `https://app.heygen.com/videos/`, as in `https://app.heygen.com/videos/<video_id>`. Never list a clip's `video_url` here: it is a download link that expires. Tell the user the clips are saved in their HeyGen account, where they can open, download, and reuse them.\n\nKeep a production ledger of approvals, storyboard versions with their grid and the image size requested and returned, the pixel size of every reference image sent, and asset IDs, the product facts with their evidence sources and photographed and inferred sides, the person description, the approved script, the voice, clip IDs, and the export path. Store no secrets, and never treat expiring links as permanent. On follow-up, reuse the approved storyboard, product facts, person description, and finished clips, and refresh an expired link with `get_model_video` rather than regenerating. If a clip changes on follow-up, rerun assembly and captions on the updated edit. A narration change must not replace the product or person. Never publish to social accounts, create campaigns, or message third parties without separate explicit authorization and real publishing tools.\n"
}