Video Prompt Builder
Generic, provider-agnostic dispatcher for video generation prompts. Reads the routing matrix in .specs/architecture/PROVIDERS.md, decides which provider should run the piece, and delegates to the right specialist (higgsfield-prompt-builder, topview-prompt-builder, wavespeed-batch, hyperframes-prompt-builder).
When to invoke
- Any video generation step in the pipeline (
brief -> script -> creativewhen creative type is video). - When a piece declares
type: videoin.specs/pieces/*.md. - A/B testing video hooks across providers and the orchestrator needs a single entry point.
- Re-running the same brief on a different provider after an A/B winner is picked.
- When an upstream agent has a brief but does not know which provider to choose.
Inputs
brief: object. Visual brief with at leastsubject,motion,mood,aspect,duration_seconds.task_kind: string. One ofcinematic_reel,motion_control,ugc_product_holder,product_demo,talking_head,batch_hook_test,motion_typography,data_viz_reel,programmatic_short.piece_path: string, optional. Path to the piece file. May containprovider_override.video.dry_run: boolean, optional. When true, returns the resolved provider and parameters without calling the MCP.
Process
- Read
.specs/architecture/PROVIDERS.mdand parse the Video matrix into atask_kind -> providermap. - If
piece_pathis set and containsprovider_override.video, use the override. - Else look up
task_kindin the matrix. If unknown, fall back to the matrix default forcinematic_reel. - Verify the chosen provider has the env vars set (
HIGGSFIELD_MCP_ACTIVE,TOPVIEW_API_KEY,WAVESPEED_API_KEY,HYPERFRAMES_ACTIVE). - Map provider to specialist skill: Higgsfield ->
higgsfield-prompt-builder, Topview ->topview-prompt-builder, Wavespeed ->wavespeed-batch, Hyperframes ->hyperframes-prompt-builder. - Translate
brieffields into the input shape the specialist expects. - Invoke the specialist and capture its
paramsandmcp_tooloutput. - If
dry_run, return the resolved provider, the params, and the MCP tool. Otherwise call the MCP and return the artifact reference. - Log the run to
data/video-usage.jsonlwith timestamp, provider, task_kind, and outcome.
Outputs
provider_used: string.params: object. Final parameter object ready for the MCP call.mcp_tool: string. The MCP tool name.artifact_ref: string, when not in dry_run. Path or URL to the generated video.cost_estimate_usd: number.
Examples
Example 1: cinematic reel routed to Higgsfield
Input: { brief: { subject: "model in linen suit", motion: "tracking shot", mood: "editorial", aspect: "9:16", duration_seconds: 6 }, task_kind: "cinematic_reel" }
Output: { provider_used: "higgsfield", mcp_tool: "higgsfield_seedance_generate", params: {...} }
Example 2: UGC ad routed to Topview
Input: { brief: { subject: "skincare bottle held by avatar", motion: "static", mood: "friendly", aspect: "9:16", duration_seconds: 15 }, task_kind: "ugc_product_holder" }
Output: { provider_used: "topview", mcp_tool: "topview_avatar_generate", params: {...} }
Example 3: weekly KPI reel routed to Hyperframes
Input: { brief: { headline: "Semana 21 em números", aspect: "9:16", duration_seconds: 12, variables: { leads: 42, delta_pct: 12 } }, task_kind: "programmatic_short" }
Output: { provider_used: "hyperframes", mcp_tool: "hyperframes_render", params: { composition_spec: {...}, render_args: {...} } } — local render via the hyperframes + hyperframes-cli skills.
Failure modes
- task_kind not in matrix: log a warning and use the cinematic_reel default.
- Required env var missing for the chosen provider: drop to the next provider in the matrix and surface a warning.
- Specialist skill returns an error: surface it and do not auto-retry on a different provider unless the caller opts in.
- Duration exceeds provider limit: trim to the provider max and surface a notice.
Related skills
higgsfield-prompt-builder: specialist for Soul, DoP, Seedance.topview-prompt-builder: specialist for UGC and avatar-driven ads.wavespeed-batch: specialist for cheap batch hook tests.hyperframes-prompt-builder: specialist for HTML-rendered motion typography, data-viz reels, and parametrized programmatic shorts.llm-router: separate dispatcher for text generation; same pattern, different domain.qa-tech-specs: validates the final video against the platform spec.