| name | topview-prompt-builder |
| description | Assembles Topview UGC prompts with avatar id, product upload, scene, voice, and duration for ad tests and product holders |
| version | 0.1.0 |
Topview Prompt Builder
Specialized prompt assembler for Topview UGC. Best fit for ad tests, avatars holding a product, talking-head scripts, and product demos generated from a URL. Emits the parameter object the Topview MCP expects.
When to invoke
- Any UGC ad test where an avatar holds or demonstrates a product.
- Talking-head scripts narrated by a Topview AI presenter.
- Product demo videos generated from a product URL with auto-script.
- Face-swap or try-on scenarios using Topview's dedicated feature.
- Any video task routed by
.specs/architecture/PROVIDERS.md to Topview.
Inputs
avatar_id: string. Topview avatar identifier from the catalog.product_asset: string. URL or path to the product image or 3D asset.scene: string. Background scene description (bright kitchen, studio white, home bathroom).script: string. Spoken script the avatar reads. Keep within duration.voice_id: string. Topview voice id matched to language and persona.language: string. pt-BR, en, es.duration_seconds: integer. 15, 30, or 60 typical.aspect: string. 9:16, 1:1, 16:9.cta_overlay: string, optional. Text overlay shown at the end (max 40 chars).from_url: string, optional. Product URL for auto-script mode.
Process
- Validate inputs. Require
avatar_id, voice_id, aspect, duration_seconds. Require at least one of script or from_url.
- If
from_url is set and script is empty, mark the call as auto-script mode and let Topview scrape the URL.
- Estimate script reading time at ~2.3 words per second. If the script overflows
duration_seconds by more than 10 percent, trim from the end and warn.
- Compose the parameter object: avatar_id, voice_id, script (or from_url), scene, product_asset, aspect, duration, language, cta_overlay.
- Pick the MCP tool name based on mode:
topview_avatar_generate for script mode, topview_url_to_video for URL mode, topview_face_swap for try-on.
- Run a sanity pass: avatar exists in the catalog map, voice matches language, aspect is supported.
- Return the assembled params, the MCP tool name, and the estimated cost.
Outputs
params: object. Ready-to-pass parameter object.mcp_tool: string. Topview MCP tool name.estimated_duration_seconds: number. Computed from script length.cost_estimate_usd: number.warnings: array of strings.
Examples
Example 1: avatar holding a perfume bottle, 15s ad
Input: { avatar_id: "ava_brunette_29", product_asset: "outputs/perfume.png", scene: "bright bathroom counter", script: "This perfume changed my morning routine. Three sprays and I am out the door.", voice_id: "voice_pt_br_warm_female", language: "pt-BR", duration_seconds: 15, aspect: "9:16", cta_overlay: "Shop now" }
Output: { params: {...}, mcp_tool: "topview_avatar_generate", estimated_duration_seconds: 14, cost_estimate_usd: 0.45, warnings: [] }
Example 2: URL-driven demo
Input: { avatar_id: "ava_male_35", from_url: "https://store.example.com/skincare-serum", voice_id: "voice_en_us_neutral_male", language: "en", duration_seconds: 30, aspect: "9:16" }
Output: parameter object with from_url mode and the corresponding MCP tool.
Failure modes
- avatar_id not in catalog: surface a clear error and suggest the closest match by tags.
- voice_id mismatched to language: auto-pick the default voice for the language and warn.
- script overflows duration even after trimming: refuse and ask the caller to shorten or pick a longer duration.
- product_asset unreachable: throw a descriptive error with the resolved URL or path.
Related skills
video-prompt-builder: generic dispatcher that delegates here when Topview is the chosen provider.wavespeed-batch: cheaper alternative for batch hook tests.higgsfield-prompt-builder: alternative for cinematic shots not suited to UGC.qa-tech-specs: validates the rendered video against platform specs.
