Motion Graphics Generator

Submit-only: starts MG generation and returns jobId. A successful job creates a project motion-graphic asset in the media pool/library; use track_progress when the next step needs the finished MG asset id.

When calling submit_motion_graphic, the prompt is the Gemini brief. Write it using the brief fields in this skill; do not send a loose one-line prompt.

MG brief workflow

Use motion-graphic-gen as the brief-writing layer. It tells the agent how to talk to Gemini; scenario skills such as talking-head-guide provide timing, form, placement, and background context.

1. Gather inputs — content, user words, project identity (Design Style / brand), references, duration, canvas size, and any scenario-specific timing / form / background decisions.
2. Align or choose Direction — if a scenario skill provides a visual identity workflow, use that first. Otherwise ask when style is unspecified; use the user's style verbatim when they gave one; make a best guess only when they ask you not to pause.
3. Compose the 8-field brief — the minimum useful brief is Content + Background. Add other fields only when they carry real information.
4. After submission — if the user only asked to create an MG, tell them generation has started and can continue in the background. If the next step depends on the finished MG, use track_progress to get outputAssetId, then place that project asset and review it in context.

Context first

Before choosing Direction or writing the brief, collect the strongest context available.

Context may come from:

• User intent — explicit style, vibe, reference, must-have content.
• Project identity — active Design Style, brand colors, fonts, or prior accepted MG.
• Usage context — where this MG will appear: talking-head overlay, full-screen title, product demo, social ad, data explainer, logo intro, etc.
• Visual context — representative or target frame: lighting, background density, subject placement, and legibility needs.
• Content role — chapter marker, lower-third, quote, list, diagram, CTA, and similar roles.
• Technical constraints — duration, canvas size, transparent / opaque background, available assets, template / reference.

Scenario skills decide why, when, where, and in what context the MG appears. motion-graphic-gen turns that context into a strong Gemini brief without redoing scenario-specific editing decisions. If another skill provides these decisions, use them directly. If used standalone, gather the missing context yourself or ask only for the missing high-leverage decision.

How to write a good MG brief for Gemini

Your job: turn the user's request into a brief Gemini can produce a distinctive, intentional MG from — not AI slop.

What you're actually doing. Your output is a single text string — a brief — sent to Gemini. Two things change everything:

1. Gemini only sees the brief. Not your chat with the user, not your reasoning, not the direction you both confirmed in alignment. If you decided something in chat but didn't write it into the brief, Gemini doesn't know it.
2. Gemini is the designer. It picks typography, exact colors, internal composition, and motion timing based on the direction you name. Prompts that pre-specify execution (px, hex, animation specs, final canvas placement) consistently produce worse results than prompts that name a direction and let Gemini execute.

Your real job is to assemble the right inputs, not to design. Gather content, the user's words, project identity, the aligned direction, and useful context; write them plainly into the brief; let Gemini design.

Above all else, the user's request comes first. Anything they explicitly specified — style, color, layout, font, vibe, reference — is non-negotiable input. Pass it through verbatim, build around it, and do not override or polish it. Respect the user's intent: do not over-design, do not over-extend. Your craft is in elevating the user's intent within the space they left open, not in reinterpreting what they already gave you.

The sections below are for filling the gaps the user left open.

Design Thinking

Use design thinking to choose or confirm the Direction. It is not a fixed style menu, and it should not override the user's stated style.

Default quality bar: distinctive, production-grade, and intentional. When the user has not specified a style and asks you to proceed, choose a specific visual direction with a point of view. Do not fall back to safe, basic, or generic just because the style is unspecified.

Before writing the prompt, understand the context and commit to a clear aesthetic direction:

• Purpose: What does this MG convey? Who watches?
• Tone: Consider specific flavors such as maximalist editorial, vintage newspaper front page, 80s 复古印刷, brutalist / raw, kinetic typography, playful / toy-like, refined / luxury, dark editorial, dark tech aesthetic, cinematic, hand-drawn, editorial pull-quote, NYT infographic, stamp badge, dashboard editorial, frosted glass card, brutally minimal, Apple keynote minimal, pitch deck minimal, etc. Use these as inspiration, not defaults.
• Constraints: Target size for this MG asset, duration, no interaction, Design Style / brand spec (if provided), the video footage it overlays.
• Memory: What is the one idea the viewer should remember after 3 seconds?

Critical: choose a clear conceptual direction and give Gemini enough context to execute it with precision. Maximalist and restrained MGs can both work — the key is intentionality, not intensity. Restrained does not mean plain: minimal or refined directions still need a named design language and clear intent. Plain/simple/basic is not a Direction.

MG Aesthetics Guidelines

Use aesthetic thinking to choose the Direction and useful context, not to dictate Gemini's execution.

• Typography / color / motion / spatial composition — mention them only when the user, brand, reference, or scenario makes them important. Otherwise, let Gemini interpret the Direction.
• Atmosphere and visual details — for transparent overlays, atmosphere lives inside the overlay's own forms, such as panels, texture, accents, or internal translucency. Full-screen cards are different: they intentionally become their own visual surface.
• Prompt richness — match the brief to the aesthetic. Maximalist directions may need richer descriptive context; minimalist directions usually need restraint.

Align with the user

You are the junior designer; the user is the manager. Direction is the high-leverage choice — surfacing it before generation is much cheaper than regenerating after.

This is the generic alignment rule for motion-graphic-gen. If a scenario skill provides a stronger visual identity workflow — such as an active Design Style, visual picker, or first-anchor process — follow the scenario workflow first.

You MUST ask for any new MG with no specified style — and, when it isn't obvious, whether it sits over the video as an overlay or takes the whole frame (that answer is the coverage parameter). The user often has a video tone in mind you can't infer from one line of request, even when the request looks obvious. Give them at least three candidate directions with a one-line rationale for each, in their own language, and let them pick or override. Spread the options across the aesthetic spectrum — three distinct directions, not three flavors of the same one. The goal isn't to find the single perfect answer; it's to expose flavors they wouldn't have asked for so they can mix and match.

When the task needs visual style alignment, check the project context first. If there is an active Design Style, use it as the confirmed visual language unless the user asks to change it. If there is no active Design Style and the user has not given a clear style direction, use normal design judgment to decide whether text options or image-backed style choices will align expectations best.

Catalog Design Style presets are available as visual style options with image previews. When a preset may genuinely fit the user's requested MG direction, first look at the available catalog candidates with list_presets, then decide whether any are reasonable visual starting points. They do not need to match every detail of the user's request; show preset cards when their overall look would set useful visual expectations and can be adapted in generation. Prefer preset cards over text-only choices in that case, because seeing the look is usually clearer than naming it. Do not force catalog presets when none are reasonably close; use the user's stated direction or normal design judgment instead.

When using catalog presets, call manage_design_style with action: "list_presets"; pass scenario only when it is clear. Pick 6 matches using each preset's description as agent-facing matching guidance when there are enough reasonable matches; use fewer only when fewer presets genuinely fit. Never render the full catalog as user-facing visual cards. Use widget-forms to collect any needed intake, and render each catalog choice as <visual-option preset-id="..."/>. Do not invent value, name, or media for catalog choices, and do not mix custom non-preset directions into the same visual picker. If a custom direction would help, describe it in prose outside the picker. Do not repeat catalog descriptions under the picker unless the user asks for details. Frame catalog cards as visual starting points, not required choices: briefly make clear in the user's language that they can pick a close option or describe a different direction, and do not mark the visual picker as required. After showing catalog cards, offer one lightweight quick choice/chip to refresh the set (for example, "换一批" in Chinese) so the user can ask for another set without typing. If the user can also describe a different direction, say that in normal prose rather than adding more quick choices. If the user asks to refresh, call list_presets again and show a different set of up to 6 reasonable matches. Do not repeat presets already shown in the current style-picking exchange; show fewer than 6 rather than repeat. A refresh response is still a catalog picker, so keep the same lightweight refresh affordance available after it. Apply the user's pick with action: "apply_preset". Do not create or update a Design Style from an unconfirmed recommendation. If a scenario-filtered result feels too narrow or the user asks for other styles, call list_presets again without scenario before answering.

For a batch of related MGs in one scene or topic, ask once for a shared direction — don't invent a different aesthetic per item, and don't ask per MG.

The only times to skip the ask:

• The user has already named a style ("做 editorial 杂志风的", "做个 80s 复古印刷", "magazine style 那种") — use it verbatim, they've spoken.
• The user has explicitly waved off alignment ("直接做" / "don't ask, just do it"): make your best guess, name it in chat, then continue with the normal brief, frame-inspection, and consistency workflow.

Multi-MG consistency

Treat multiple MGs in the same video as one visual system, not separate one-off designs. Opening titles, chapter markers, quote cards, list cards, and CTAs may have different forms, but they should share a coherent direction, typography logic, color system, motion language, and level of visual density unless the user asks for a deliberate contrast.

One video, one visual style. One MG role, one anchor. Use a first MG when it creates useful evidence: in-frame proof for an unconfirmed direction, or a reusable role anchor for a repeated role. A confirmed Design Style provides visual language; it does not automatically provide a reusable asset for every role.

"Directly do it" skips user style confirmation, not reuse planning or in-frame review.

Before composing briefs for a batch, group planned MGs by role. A role is the same visual job with the same structure, not just another MG in the same video. Then choose the reference source for each role:

• Same role + same structure + changed content → submit a new asset from the accepted role anchor with :template. Keep the layout, typography, colors, spacing, motion, and visual treatment identical; change only the specified content.
• Any structure, form, or canvas-role difference → use :style. Let the current brief decide the new MG's form, size, background, and content while borrowing the visual language.
• New or different role → start from a matching template when one exists. Template refs from an active Design Style are normal template IDs. For now, templates are generation references, not direct-apply targets: pass the matching template ID directly in referenceAssetIds. Use :template only when preserving the same structure; use :style when the requested content/count/form differs. If there is no matching template, use the confirmed Direction and any relevant style reference. Do not adapt a role anchor from another role into a different structure.

For same-role MGs, shared colors or Direction are not enough. Using the role anchor as a template reference keeps layout and motion consistent while letting Gemini update all text/content safely.

After a role anchor exists and passes review, remaining same-role MGs may be submitted in parallel from that role anchor.

Applying the Design Style

Design Style is the project's confirmed visual language. It can provide colors, fonts, style guidance, and template refs. It helps Gemini keep MGs in the same visual family, but it does not replace the brief: still provide Content, Background, and any needed Timing, Size & shape, or context.

When to use or create it

Use an active Design Style when one exists. Do not create a Design Style just because a one-off MG needs a style; use the user's direction or the normal alignment flow instead. Create or apply a Design Style only after the user confirms a project-level visual direction, chooses a preset, accepts a sample, or asks for a reusable visual system. Never create or update a Design Style from an unconfirmed guess.

What to pass to submit_motion_graphic

When submitting a new MG under an active Design Style, pass:

1. designStyle: "core" — project identity: colors, fonts, style guide.
2. One code reference source + one reuse mode — concrete template/code evidence for Gemini.
3. Optional visual pixel references — logos, product shots, screenshots, or reference images Gemini should look at.

A code reference source can be a project motion graphic asset or a template ID. Template refs from a Design Style are no different from any other template ID. For now, do not apply templates directly and do not copy them before generation by default; pass the template ID directly. Use manage_template copy_assets only when the generated MG must embed or remap template media as project-local assets. The reuse modes are style or template.

Image references in referenceAssetIds are different: they are visual pixels, not code reference sources. They can be combined with either code reference source.

Code reference source priority

A code reference source is valid only for the role it came from. Consistency comes from designStyle: "core"; structure comes from the code reference source for this role.

Choose the code reference source by role:

1. Same role with an accepted role anchor: use that project asset anchor via referenceAssetIds: ["<roleAnchorAssetId>:template"].
2. New role with a matched template: generate directly from that template ID. Use :template only when preserving the same structure; otherwise use :style.
3. New role without a matched template: use the nearest representative template ID with :style when available.
4. designStyle: "core" alone only when there is no accepted role anchor and the active Design Style has no usable template refs.

If there is no accepted role anchor yet and the active Design Style has template refs, check the matching template before generating, then generate from it. Do not apply it directly just because it fits.

Template slots are not user constraints. If a template shows 6 bars, 3 rows, 4 cards, or another fixed count but the user asks for a different count/granularity, do not ask the user to compress their request to fit the template. Generate a new MG from the template as :style, put the requested count/data in Content, and tell Gemini the structure should adapt to fit. Ask only when the data itself is missing or genuinely ambiguous.

After a template is applied or a template-grounded MG is generated, placed, and accepted in this project, it becomes the role anchor for that role. For later same-role MGs, use that role anchor as the :template reference before going back to the source template. For a different role, go back to the template refs instead of reshaping another role's anchor.

Template mode

Write the mode explicitly in whichever code reference field you use. Omitting mode uses the backend default style.

Choose the reuse mode by structure, not by topic or label. Two MGs can both be "chapter" content but need different modes if one is a full-screen chapter card and the other is a lower-third chapter marker.

• :template — same visual job, same structure, same canvas role, and a source that already passed screenshot review. Keep the template exact and replace every occurrence of old text/number/content.
• :style — anything else. Borrow the visual language and let Gemini design the current role's structure from the brief.

Readable text in a reference is content, not style. In :style, borrow typography, color logic, motion rhythm, geometry, hierarchy, and density — not labels, numbers, statuses, spec rows, callout copy, or other template text.

If the visual job, canvas role, or layout structure changes, use :style, not :template. A full-screen chapter title and a lower-third chapter marker are different structures; use :style.

Brief weight with references

A code reference already carries concrete style, layout grammar, and motion language. When using a role anchor or template, keep the brief focused on content, role / broad form, background, and real constraints. Let the reference carry typography, color logic, detailed composition, and motion vocabulary.

In :template, describe only the content changes and require old readable text to be replaced. In :style, describe the new role and broad form; do not copy the reference's readable labels or force its exact structure.

Do not restate detailed colors, fonts, pixel sizes, animation specs, or decorative elements unless they come from the user, a real constraint, or a needed correction.

Boundaries

Use one code reference source per submit: one motion-graphic entry in referenceAssetIds. Image references in referenceAssetIds can still be combined because they are visual pixels, not code.

designStyle never carries logos or images. It only injects text describing colors/fonts/style into the prompt. If you want the AI to reproduce a specific piece of artwork, it must see the pixels through referenceAssetIds.

Prompt structure

After alignment, the Gemini brief has 8 fields. Compose them deliberately:

Opaque full-screen MGs own their background. When coverage:"fullscreen" and Background: opaque, place only the MG; do not add a separate solid item underneath just to set the color. Use the MG's bgColor / transparentBackground properties for background changes. Do not create solid fallback cards or mattes; if generation fails, retry, use a suitable existing/template MG, or report the blocker. If you encounter an old transparent-MG-plus-solid fallback while replacing it with an opaque generated MG, delete both fallback pieces.

Brief boundaries

Everything in the prompt must trace back to one of the eight fields above: brief content, internal Timing, the user's words, Design Style / brand spec, confirmed Direction, Size & shape requirement, materially useful context, or Background. If it doesn't fit those sources, delete it.

Reference text is not a source of new content. If a reference or template contains readable labels, numbers, statuses, spec rows, or callout copy, include them only when the current content explicitly needs them.

Style feedback is not execution permission. When the user asks for a style change ("more YouTube", "more premium", "less boring", "more playful", "more tech", etc.), translate it into Direction, viewer impression, energy level, contrast, pacing, and context. Do not turn style feedback into invented colors, fonts, exact shapes, pixel sizes, or animation mechanics.

Only specify execution details when they come from the user, brand, reference, existing template, or a real technical constraint. When fixing a failed MG, rewrite the feedback as current target/outcome requirements Gemini can act on: "the full title must fit clearly", "needs stronger contrast", "should feel more energetic" — not history Gemini cannot see, and not the exact design solution.

Include:

• The content Gemini should show.
• The user's style words, Design Style / brand constraints, and relevant references.
• A clear Direction when the user did not already provide one.
• Intrinsic form constraints under Size & shape: lower-third-style name tag, compact side card, bottom horizontal strip, full-screen title card, etc.
• Context that materially affects design choices, such as a dark video scene requiring legibility.

Do not include:

• Final canvas placement — no left / top / right / bottom, coordinates, or placement anchors like "lower-left" / "top-right". Final placement is handled after generation.
• Generic AI aesthetics — purple/blue gradient backgrounds, fake glassmorphism everywhere, predictable feature-card layouts, cookie-cutter cards, or any look that lacks context-specific character.
• Empty Direction filler — phrases like "modern professional", "clean minimal", "sleek and contemporary", or "elegant and refined" are too vague to guide design.
• Stacked aesthetics — avoid × or + piles such as "editorial × cyberpunk × philosophical machine". Pick one direction and let it lead.
• Invented labels — system tags, status badges, version stamps, spec rows, project labels, edition marks, fake mastheads, or any text not supplied by the content/user/brand/current brief.
• Micro-execution — final layout positions, exact animation specs (including the Timing field, which says when an element appears, not how it moves), specific fonts/spacing/colors, or over-specific shapes unless the user, brand, or reference requires them.

Name the function, content, direction, and constraints. Let Gemini execute the exact look.

Examples

# ✅ Good — Content + Brand + Direction (~3 lines, everything else is Gemini's)

"Content: Title 'Smart Analytics', subtitle 'Real-time insights'.
Brand: #6C5CE7 primary, #A8E6CF accent (from website).
Direction: dashboard editorial.
Background: opaque."

# ✅ Good — adds Other context when it actually affects Gemini's design

"Content: Speaker name 'John Doe', role 'Senior Engineer'.
Direction: broadcast lower-third, restrained.
Other context: sits over a fast-paced product demo — keep the overlay simple, not competing with the footage.
Background: transparent."

# ✅ Good — Size & shape directs Gemini to fit a safe rectangle from talking-head analysis

"Content: Speaker name 'John Doe', role 'Senior Engineer'.
Size & shape: narrow lower-third-style name tag, fitting a safe rectangle roughly bottom-band proportions without assuming final canvas placement.
Direction: broadcast lower-third, restrained.
Other context: dark interior scene — keep the design bright/light enough to read clearly.
Background: transparent."

# ✅ Good — internal Timing with concrete timestamps from real speech
# submit_motion_graphic durationInSeconds: 7.5, name: "Three feature list"

"Content: Three product features: 'Stability', 'UI Redesign', 'AI Motion Graphics'.
Timing:
  - 'Stability' at 0s (speaker starts the list)
  - 'UI Redesign' at 2.3s (when speaker says it)
  - 'AI Motion Graphics' at 4.8s (when speaker says it)
  - All three remain visible together by 6.5s, hold for the last second.
Direction: Warm Creator Studio.
Background: transparent."

# ✅ Good — user named the style; pass verbatim, no Direction guessing

User said: "做一个 editorial 杂志风的，大字排版，强烈对比"
Prompt:
"Content: Title 'Quarterly Report'.
User's words: editorial 杂志风, 大字排版, 强烈对比.
Background: opaque."

User said: "做个 80s 复古印刷风的，颗粒质感"
Prompt:
"Content: Title 'Vol. 7'.
User's words: 80s 复古印刷, 颗粒质感.
Background: opaque."

# ❌ Bad — agent invented micro-execution

"Product launch opening title. Show 'Checkout' as main product name in large bold display type, 'New Version' as secondary line below. Dark background with subtle gradient, sharp white typography, thin horizontal accent line between the two text lines. Text animates in with precise upward reveal — product name first, then subtitle slides in 0.3s later. Direction: premium product launch."

  Why bad: layout ("below", "between two lines"), animation ("upward reveal", "0.3s later", "slides in"), specific type ("large bold display", "sharp white", "thin accent line"), specific colors ("dark with subtle gradient") — all Gemini's job unless the user or brand supplied them. The real brief here is Content (Checkout / New Version) + Direction (premium product launch) + Background.

# ❌ Bad — generic empty filler in Direction

"Title 'Smart Analytics'. Direction: modern professional, clean minimal."

# ❌ Bad — stacked aesthetics with ×

"Quote card. Direction: editorial pull-quote × printed-ink feel × historical proclamation."

# ❌ Bad — content needs rhythm but Timing missing

"Three product features appear one by one in sync with speech:
  - 'Stability'
  - 'UI Redesign'
  - 'AI Motion Graphics'
Direction: dashboard editorial."

  Why bad: the content clearly needs internal rhythm ("one by one in sync with speech"), but the Timing field is missing per-element appearance times. Gemini knows there are 3 items but not the cadence — it'll invent an evenly-spaced rhythm that won't match real speech.

# ❌ Bad — Timing too vague to act on

"Three features fade in sequentially during the speech, evenly paced."

  Why bad: "sequentially" / "evenly paced" describe rhythm but aren't actionable. Gemini will divide the duration evenly, but real speech isn't evenly paced. Give concrete timestamps in Timing (look them up via `find_transcript`).

Editable Properties

New MGs should expose visible text and key colors as editable properties through the generator's normal property system. When the user specifically asks for adjustability (e.g. "留一个我自己能调的办法"), mention the needed editability in Other context instead of adding a separate prompt section.

When modifying existing MG code: reuse existing property keys, add missing text/font/color/transparency properties rather than leaving them hardcoded.

Assets in Motion Graphics

URLs are NEVER hardcoded inside MG JSX. Every <Img> / <Video> src reads from an image / video editable property; the runtime resolves the property value (asset id or http URL) to a URL and delivers it via props.<key>.

If the user wants a specific asset rendered:

1. Register the asset to the project library first (upload / generate / import) and capture its asset id.
2. Pass the asset id via availableAssetIds: [<id>]. The id flows into <available_assets> and Gemini will declare an image / video / audio / gif / svg property whose defaultValue is that asset id — the new MG already renders the right media with no extra binding step.
3. To swap the asset later on a specific item, use edit_item with an updates[] entry and propertyOverrides: { <propertyKey>: "<otherAssetId>" }.

If Gemini should learn from a logo, product shot, screenshot, or other real image without embedding it as the rendered asset, pass that id in referenceAssetIds. Image references are pixels, so they can combine with a role anchor or template.

If you only have a URL and the user has not registered it as a project asset, download it into the sandbox workspace, then import the local file through asset-import + push_asset — there's no direct-URL escape hatch on submit_motion_graphic.

Usage

Always pass name as a one-sentence content summary.

When creating a new same-role MG from an accepted role anchor in :template mode (via referenceAssetIds: ["<roleAnchorAssetId>:template"]), the brief should say exactly what content changes and explicitly preserve the template: only change the specified content; replace every occurrence of old text/numbers; keep layout, typography, colors, spacing, motion, and visual treatment identical. For a template, use the template UUID instead: referenceAssetIds: ["<templateId>:template"] when preserving structure, or referenceAssetIds: ["<templateId>:style"] when the requested count/form/content structure differs.

// Pass width/height explicitly. For fullscreen MGs, use the target timeline
// composition; for overlays, use the intended intrinsic overlay size.
// `coverage` declares the frame role: "fullscreen" = the MG IS the whole frame
// for its duration; "overlay" = it sits on top of the video.

submit_motion_graphic({
  prompt: `Content: Opening title "Hello World".
Direction: kinetic typography.
Background: opaque.`,
  name: "Hello World opening title animation",
  coverage: "fullscreen",
  width: 1080,
  height: 1920,
  designStyle: "core",
});

// availableAssetIds = assets the MG output should embed. Each becomes an
// editable image/video/audio/gif/svg property in the generated code; the user can swap
// them later in the inspector. Pass project asset ids (full or short prefix).
submit_motion_graphic({
  prompt: `Content: Brand logo intro using the provided logo asset.
Direction: brand intro.
Background: opaque.`,
  name: "Acme Corp logo brand intro",
  coverage: "overlay",
  width: 720,
  height: 720,
  designStyle: "core",
  availableAssetIds: ["86b0f6c70a"],
});

// Image referenceAssetIds = images the model should LOOK AT for style
// inspiration. They do NOT end up inside the MG — they only shape what Gemini
// generates.
submit_motion_graphic({
  prompt: `Content: Product launch title using the provided screenshot as visual inspiration.
Direction: match the screenshot's clean product UI tone.
Background: transparent.`,
  name: "Product launch UI-inspired title",
  coverage: "overlay",
  width: 900,
  height: 500,
  designStyle: "core",
  referenceAssetIds: ["86b0f6c70a"], // image asset id
});

// MG/template referenceAssetIds = code references. Pass either a role-anchor
// project MG id or a template UUID with a mode suffix:
// "<id>:template" for same structure, "<id>:style" for different structure.
submit_motion_graphic({
  prompt: `Content: Speaker name "John Doe", role "CEO".
Size & shape: lower-third-style name tag.
Direction: broadcast lower-third, restrained.
Background: transparent.`,
  name: "John Doe lower third",
  coverage: "overlay",
  width: 760,
  height: 220,
  designStyle: "core",
  referenceAssetIds: ["<mgId>:style"],
});

Strategy

• If the user only asked to create an MG, tell them generation has started and can continue in the background.
• If the next step depends on the finished MG, use track_progress to get outputAssetId; in video editing workflows, place that project media-pool asset and verify it in context.
• For batches or repeated MGs, follow Multi-MG consistency before submitting. Same-role repeated MGs should usually generate from the accepted role anchor with referenceAssetIds: ["<roleAnchorAssetId>:template"].

Editing Existing Properties

Any time you're about to edit asset.properties, item.propertyOverrides, or promote a hardcoded value the user wants to tweak, read references/property-changes.md first. Two habits it reinforces:

• Promote hardcoded values to editable properties the first time the user asks to tweak one — otherwise they'll come back for every adjustment.

Parameters

submit_motion_graphic({ ... }) takes:

Output

Returns a text MCP result with a short jobId, asset name, the submitted canvas, the coverage behavior, and a reminder that the completed job creates a project motion-graphic asset in the media pool/library. It does not return a structured { success, job, manage } object; read the jobId from the text and call track_progress to wait for completion and get outputAssetId.

Validation & Verification

Backend Validation

When generating via submit_motion_graphic, the backend handles validation automatically:

1. Auto-fix common model mistakes
2. Validate structure and safety
3. Retry only when errors cannot be auto-fixed

Manual Code Verification

NEVER write MG code from scratch. Use submit_motion_graphic for new MGs. This section is ONLY for modifying existing MG code that was already generated.

When the code validates but the visual result is wrong, or you are stuck on a tricky pattern, read guide/README.md before iterating further.

Typical workflow:

1. inspect_asset with the MG assetId and code: true — read the current source.
2. Edit the source in your own context while preserving unrelated behavior and existing editable properties.
3. edit_asset with action=update, the same assetId, and the full replacement source inline in json.code — the backend validates the code and pushes it back.

Convert an MG to a plain video

Bakes a motion graphic into a transparent video asset (vp8/WebM alpha) in the media pool. Use when the user wants the MG as a real video — to overlay on footage, or to replace the MG clip with a real video clip (convert / bake / MG 转视频 / 转成视频 / 转成视频素材). One MG maps to one deterministic video asset, so re-converting the same MG dedupes to the existing asset (no duplicate render). The converting/completed state shows up in the media pool exactly like a manual convert.

Do NOT use this for exporting/downloading — that's export_motion_graphic_prores. Convert produces an in-project video asset, not a download. Convert is Pro-gated (same entitlement as MG ProRes export); a non-Pro user gets a feature-gate error.

Three steps:

1. Kick the render. convert_motion_graphic_to_video({ assetId }) with the MG asset id — returns { renderId, mgAssetId } and starts a cloud render at the MG's native length. If it returns status: "already-converted" with a videoAssetId, the video asset already exists — skip straight to placing it. If a convert for the same MG is still rendering, it returns that in-flight renderId instead of kicking a second render.
2. Wait for completion. Poll track_export({ renderId }) until that render's entry is status: "complete". Renders take seconds to a couple of minutes — poll, don't assume instant. (No download URL needed — the next step resolves the output server-side.)
3. Import as a video asset. register_converted_video({ mgAssetId, renderId }) — promotes the render into the media pool and returns { videoAssetId, deduped }.

Placing / replacing on the timeline:

• To place the new video: edit_item add a video item referencing videoAssetId.
• To replace the original MG clip in place: in one edit_item call, delete the MG item and add a video item referencing videoAssetId. Preserve the MG clip's from / durationInFrames; if the MG clip was stretched or shrunk, set the video item's playbackRate so the video spans the same timeline duration.
• The output keeps the MG's transparency (alpha), so it overlays cleanly on any background.