UGC review video
Produce one hosted 9:16 MP4. Keep one creator identity through every board and clip. Each board is a 21:9 sheet of eight vertical 9:16 slots; one video clip turns those slots into eight internal hard cuts.
Runtime contract
- Use only tools exposed by the current OpenAI host and Higgsfield MCP surface.
- Use
ask_user_inputwhen the host exposes that exact callable. Useask_user_input_v3only when that exact variant is exposed. Otherwise ask one concise normal-chat question. Never use a legacy elicitation name or Codex's plan-only question mechanism as a ChatGPT substitute. - For each ChatGPT attachment, call
media_upload_and_confirmonce with the supplied file object. Keep its returnedmedia_id; do not callmedia_confirmafterward. - Authorized HTTPS image URLs may be passed directly in
medias[].value; the OpenAI generation tools import and confirm them automatically. Reuse the exact URL or returned confirmed ID. Do not invent a separate import tool. - Run ffmpeg, Python, downloads, probes, transcription, assembly, and uploads
only through
sandbox_exec, never a client-local shell. - For a sandbox-created output, call
media_uploadbefore the producingsandbox_exec, PUT the file to itsupload_urlin that same sandbox command, and callmedia_confirmonly after HTTP 200. Never pass a sandbox path tomedia_upload_and_confirm. - Workflow scripts are preinstalled at
$HF_WORKFLOWS/ugc-review-video/scripts/inside the sandbox. Run them from there; do not expect plugin-local scripts. - Use
generate_image_batchandgenerate_video_batchfor headless workflow stages. Each request is{index, params},params.countis1, and one call contains at most six requests. Keep stable indices across retries. - Wait on returned
{index, job_id}pairs withjobs_waitin groups of at most eight andtimeout_seconds:15. Ifall_terminal:false, wait the returnedpoll_after_secondsand poll only active or retryable lookup-failed jobs. Freeze completed indices. Never poll jobs through a legacy singleton status tool. - Never pass a batch
submission_failedentry without ajob_idtojobs_wait. Retry only rejected or failed indices, never the whole stage. unlim_choicemeans no job was submitted. Ask its message and resubmit the unchanged request with the user'suse_unlimchoice; never choose for them.- Do not substitute a different model when a locked model is unavailable. Report the incompatible slug and stop that phase.
Hard rules
- Use one
character_media_idfor every board and clip. Never regenerate it mid-run or replace it with an inline description. - Generate boards sequentially; generate ready clips through grouped batch calls only after every clip prompt is written.
- Never bake text into generation. Burn text only after render and only when the user opted in.
- Run the de-slop pass on every board. Never send a raw
gpt_image_2board to video unless both allowed Seedream attempts fail. - Default to English speech with an American accent unless explicitly changed.
- When a product is present, never greet or reintroduce it after board 1; later segments continue mid-thought.
- Hide model names, job IDs, internal phases, and intermediate mechanics from the user.
Safety and truth gate — before intake or generation
If any item below fails, do not generate and do not route around the gate:
- Creator authorization: use only a generated adult age 21+ or a consenting adult non-public person whose image the user is authorized to use. A supplied photo is not permission to impersonate its subject. If third-party consent is unclear, ask once; decline public figures, celebrities, minors, and deceptive identity use. Never clone or imitate a supplied person's voice.
- Allowed promotion: decline political persuasion and promotion of prohibited or age-restricted goods or services, including adult sexual content, products, or services; gambling; illegal or regulated drugs, drug paraphernalia, and prescription medication; tobacco or nicotine; weapons, explosives, or harmful materials; counterfeit or illicit goods; extremist goods; deceptive or high-risk financial services; malware or spyware; fraud; and covert surveillance. A neutral educational mention is not a product promotion and belongs outside this workflow.
- Truthful claims:
approved_claimsis the complete allowlist of product claims supplied by the user. Preserve each allowed claim verbatim; never strengthen, combine, infer, or derive another claim. With no allowlist, create claim-free copy about visible materials, controls, application, packaging, and other directly observable mechanics. - No synthetic testimonials: a generated creator is a host or demonstrator, never a real customer. Do not invent purchase, ownership, use, results, before/after outcomes, ratings, reviews, social proof, relationships, or lived experience. First-person experience is allowed only when a consenting user supplies the exact script and confirms it describes their own experience.
- Transparent framing: describe product-present output as a brand demo, creator concept, or sponsored creative—not an organic customer review. When a post package is requested, include an appropriate ad/sponsorship disclosure.
Duration and arc
| Total duration | Boards | Clip durations |
|---|---|---|
| 4–15s | 1 | total duration |
| 16–19s | 2 | balance both to at least 4s; e.g. 18 → 14+4 |
| 20–30s | 2 | 15, remainder |
| 31–45s | 3 | 15, 15, remainder |
| 46–60s | 4 | 15, 15, 15, remainder |
| >60s | ceil(D/15) | 15 each, final clip at least 4s |
Assign board roles as follows:
- N=1:
FULL_ARC(HOOK → MAIN → CLOSER). - N=2:
HOOK+SETUP, thenAPPLY+CLOSER. - N=3:
HOOK,MAIN,CLOSER. - N=4:
HOOK,REVEAL,APPLY,CLOSER. - N>4:
HOOKfirst,CLOSERlast,REVEAL/APPLYbetween.
Phase 0 — Intake
After the safety and truth gate passes, parse an optional product photo or URL,
duration, creator photo or requested gender, and
explicit overrides for location, hair, ethnicity, outfit register, mood, props,
language, accent, music, approved_claims, and on-video text.
Classify specificity:
auto: 1–5 words with no scenario; choose the complete treatment.guided: 1–3 sentences of tone or rough flow; preserve that direction.director: 4+ sentences, scenario, shot list, or location sequence; map the supplied beats one-to-one to slots.
Ask only for real gaps, bundled into one question: duration (offer 10s, 15s,
30s, 45s) and creator photo/gender when absent. Never ask for a product merely
because none was supplied; lock product_reference:null and
product_description:null and continue with creator-led, scenario-driven UGC. Include
an accent or physical quirk option only when the brief already signals origin or
deliberately unusual character energy. Never ask about locked models, aspect
ratios, boards, resolution, audio, batching, or identity training.
Do not start paid generation until the required creator input and duration are resolved. The later text/post-package choice is the only sanctioned second ask.
Phase 1 — Normalize the optional product
If a product photo or URL was supplied, read references/product-intake.md and
follow it exactly. Resolve once:
product_reference: confirmed attachmentmedia_idor authorized HTTPS hero image URL;- canonical
product_description; tier:luxury,premium, ordrugstorefrom visual packaging cues only;categoryand exact usage/opening mechanic.approved_claims: exact user-supplied strings, or an empty list.
Reuse those values verbatim downstream. Never infer price, invent claims or
creator experience, or
replace a blocked/thin product page with a stock or generated product. If no
product was supplied, skip the reference, keep both product fields null, and
use the no-product branches in ugc-board.md, ugc-clip.md, and monologue craft.
Phase 2 — Lock the creator
If the safety gate established that the user is authorized to use an attached
creator photo, call media_upload_and_confirm with type:"image", save its
media_id as character_media_id, and do not ask for confirmation again.
Otherwise read references/ugc-character.md, resolve the required variety rolls
and creator prompt, then submit one headless image request:
{"requests":[{"index":0,"params":{"model":"soul_2","prompt":"<creator prompt>","count":1,"aspect_ratio":"3:4","quality":"2k"}}]}
Wait with jobs_wait until terminal. On success save the returned job_id and
result_url as character_media_id and character_url. This identity is a
mandatory board input. Keep wardrobe fixed unless the story explicitly changes
context.
Phase 3 — Write the monologue
Read references/monologue-craft.md. Preserve only allowlisted user-supplied
claims and the requested tone; never invent the creator's history or experience.
apply its density, hook, persona, story-shape, accent, and anti-slop rules. Split
the final monologue into N board segments. Save the exact full text to
output/script.txt in the later sandbox assembly command; if a hook plate may be
burned, also save its headline to output/hook.txt.
Phase 4 — Generate boards sequentially
Read references/ugc-board.md. For K=1..N, build the complete board prompt and
submit exactly one generate_image_batch request with stable index K:
{"requests":[{"index":1,"params":{"model":"gpt_image_2","prompt":"<board prompt>","count":1,"aspect_ratio":"21:9","resolution":"2k","quality":"high","medias":[{"value":"<product_reference>","role":"image"},{"value":"<character_media_id>","role":"image"}]}}]}
For K>1 append the cleaned previous board job ID as the final image media. If
there is no product reference, remove it and renumber every @ImageN declaration
to match the remaining media order. Wait until terminal before continuing.
Mandatory de-slop pass
For each completed raw board, take the completed result_url returned by
jobs_wait and submit one generate_image_batch request using model
seedream_v5_pro, that HTTPS result URL as canonical role image,
aspect_ratio:"21:9", resolution:"2k", and this prompt:
When the run is productless, replace every product-preservation clause in the prompt
with do not introduce any product, package, brand, or sales prop.
KEEP EXACTLY the framing, composition, slot layout, camera distances, poses, subjects and product of this horizontal storyboard sheet and every one of its side-by-side vertical slots — no reframe, no zoom, no crop, no re-layout, no change to the scene, to any person's face / hair / body, or to the product design. CHANGE ONLY micro-realism, applied identically in every slot: true-to-life pore-level skin with natural texture and fine vellus hair, real material detail, even natural daytime light with gentle highlight roll-off and faint true sensor noise, a flat authentic iPhone photo, deep focus. PRESERVE each face's exact shape / width / proportions 1:1 — do NOT squeeze / narrow / slim / stretch any face. AVOID AI-slop: waxy plastic skin, airbrushed poreless skin, beauty-filter smoothing, over-saturation, HDR glow / bloom / halos, oversharpening, teal-orange grade, shallow depth of field, bokeh, cinematic / DSLR look. Keep the product blank / unbranded, no added text, no watermark, no baked slot labels.
The OpenAI generation route imports that URL as a concrete media_input and
normalizes the generic image role to Seedream's image_references wire field.
Never pass the raw board job ID to this i2i call. Wait until terminal and replace
the board pair with the cleaned job ID and URL.
On moderation failure retry once with seedream_v5_lite; if that also fails,
retain the raw board and report the degraded fallback internally.
Phase 5 — Write and submit clips
Read references/ugc-clip.md. Write every clip prompt before submitting any
video. Carry K, N, duration, board role, monologue segment verbatim, specificity,
persona, and board/character/product references.
Submit clips with generate_video_batch, stable index K, and groups of at most
six. For N>6, finish one group before submitting the next because the current
OpenAI surface cannot accept a larger batch. Each request uses:
{"index":1,"params":{"model":"seedance_2_5","prompt":"<clip prompt>","count":1,"aspect_ratio":"9:16","resolution":"1080p","duration":15,"mode":"omni_reference","generate_audio":true,"medias":[{"value":"<clean_board_job_id>","role":"image"},{"value":"<character_media_id>","role":"image"},{"value":"<product_reference>","role":"image"}]}}
Drop the product media when absent. Seedance 2.5 produces native speech with
mode:"omni_reference" and generate_audio:true; never call
generate_audio. Wait for all clips to become terminal. Retry only failed
indices with the corrected prompt; a successful retry replaces the old job ID at
that index.
Phase 6 — Frozen-frame QA
Before stitching or displaying clips, inspect evenly spaced frames, every product close-up when a product is present, and 2–3 mid-word frames. Require:
- when a product is present, exactly one hero product and no clones;
- at most two hands per person, including mirrors and frame edges;
- absent features remain absent; cap/button/prop state stays consistent;
- labels are not gibberish, mirrored, or a different real brand;
- when a product is present, its scale matches the holding hand;
- no doubled lip edges, face drift, baked text, or subtitles.
For a staging failure, correct and rerun only that clip. For lip artifacts, cut spoken words first. For baked text, rerun once, then remove it in post. Freeze every accepted index.
Phase 7 — Assemble and export
For N=1, the accepted clip URL is the final video URL; do not run a sandbox.
For N>=2, call media_upload first for final.mp4. Then run one
sandbox_exec command that downloads accepted clips in stable board order,
writes an explicit concat manifest, concatenates with stream copy and hard cuts
only, verifies the output with ffprobe, and PUTs it to the reserved upload URL:
ffmpeg -f concat -safe 0 -i clips.txt -c copy output/final.mp4
Use background:true for long assembly and poll its log_path at least every
60 seconds without starting a duplicate process. After HTTP 200 call
media_confirm with type:"video". If detached execution returns
deadline_exceeded, use bounded foreground calls that each finish within the
current 120-second maximum; never use nohup as a fallback.
Phase 8 — Optional text and post package
If the brief did not answer it, ask one bundled delivery question: Subtitles,
Hook, Both, or No text (default), plus whether a post package is wanted.
For text, read references/subtitles.md. Timings must come from a word-level
transcript of the final audio, never planned beats. Run the preinstalled scripts
from $HF_WORKFLOWS/ugc-review-video/scripts/ inside sandbox_exec; reserve and upload
final_captioned.mp4 through the sandbox-output flow. If no speech is detected,
burn nothing and keep final.mp4.
If requested, return a chat-only post package: one comment-bait caption with an unanswered open loop, 3–5 hashtags, one pinned comment that answers or adds observable detail, an appropriate ad/sponsorship disclosure for product-present marketing, and a one-line loop note. Never burn it into the video.
Delivery
Return exactly one confirmed hosted video URL and total duration. When captions
were requested, return final_captioned.mp4 and retain final.mp4 as the clean
master. Do not expose job IDs or intermediate assets.
References
references/product-intake.md: product normalization and staging contractreferences/ugc-character.md: Soul creator prompt and continuity rulesreferences/monologue-craft.md: speech density, voice, hooks, and story shapesreferences/ugc-board.md: eight-slot GPT Image board promptreferences/ugc-clip.md: eight-cut Seedance promptreferences/subtitles.md: optional transcript-timed text burn
Do not load sibling UGC workflow references; their product-only, unboxing, tutorial, try-on, and SaaS contracts conflict with this skill.