Malloy Studio

Check a generation's status once (point-in-time). To wait for it to finish without spinning, prefer wait_for_animation.

get_animation_status

Check an export's status once (point-in-time). Once done is true, video_url is a signed link to the finished video, valid for 24 hours; the render itself is kept 7 days, so call this again for a fresh link rather than storing one. To wait for the render to finish without spinning, prefer wait_for_export.

get_export_status

INTERNAL — called by the Malloy preview widget only. Never call this from a conversation; it is not part of the chat toolset. Point-in-time status of a widget-started export; video_url is the signed download link once done is true.

widget_get_export_status

Show the creator's plan, their prompt character limit, and remaining generation + export credits. Read prompt_char_limit from here before sending a long prompt to generate_animation or update_animation: it is plan-dependent and set server-side, so it cannot be assumed or hardcoded.

get_my_plan

Render a template to a downloadable video (runs asynchronously). Only for an explicit export request — never part of the generation flow (that flow ends at preview_template, where the user exports themselves). Before calling: confirm which template the user means (list_my_templates and ask if unclear), then confirm the field values with them — use list_template_parameters(template_id) to see the editable fields, and pass the agreed values as input_props. Typical use: rendering one or several variants of a template with different field values. A preview is not required first; offer one only if the user asks to see it. template_id: a template id from list_my_templates, OR a session_id from generate_animation — a freshly generated session is turned into a template automatically before rendering (same as the web app's create-then-export). input_props: per-render field values overriding the template's defaults (any subset; omitted fields keep their defaults, including fields inside a field that holds an object). An array is replaced whole, so send the full list when changing one. resolution: "360p" | "720p" | "1080p" | "4k", matching the portal export dialog ("4k" requires a plan that includes it). file_format: output container, e.g. "mp4" (use "webm" for transparent output). high_quality: render at a high bitrate with maximum frame quality — a larger file and a slower render. Requires a plan that includes it. It is independent of resolution, so "4k" + "mp4" + high_quality is a valid combination and is the one to use when the user asks for the best possible quality. transparent: render with a transparent background. duration_seconds: clip length when exporting a freshly generated session (defaults to the template's own duration); ignored when exporting an existing template. Costs one export credit per render. Returns an export_id — wait for the render with wait_for_export(export_id) (call until done).

export_template

INTERNAL — called by the Malloy preview widget only. Never call this from a conversation; it is not part of the chat toolset. Renders a saved template to video. input_props are per-render parameters (the widget's current form values); they do not modify the saved template. The export options mirror the portal export dialog and are forwarded to the render unchanged: resolution ("360p" | "720p" | "1080p" | "4k"), file_extension ("mp4" | "webm" | "mov"), high_quality, and transparent (the widget pre-derives transparent from an alpha-capable format). 4k and high_quality are plan-gated and raise feature_not_allowed when the plan doesn't include them.

widget_start_export

Register a completed upload as a library asset. asset_key: the value from start_asset_upload, verbatim. name: display name for the asset, normally the original filename. content_type: the same MIME type given to start_asset_upload. Returns the asset with its id. Pass that id in generate_animation's asset_ids to place the file in an animation. Fails with asset_not_uploaded if the POST to upload_url did not complete. Charges no credits.

finish_asset_upload

INTERNAL — called by the Malloy preview widget's image picker only. Never call this from a conversation; it is not part of the chat toolset. Register a completed upload as a library asset (same as finish_asset_upload) and return it WITH its signed url, which the widget writes into the image field. This finish step is the verdict on the upload: it verifies the object exists, so the widget never has to trust the (unreadable) cross-origin POST.

widget_finish_asset_upload

Generate a new animated video template from a natural-language prompt. prompt: the animation to generate, described in natural language. Its length is capped per plan: call get_my_plan and read prompt_char_limit if the prompt may be long. Over the cap the call is rejected outright (no credit is charged), so check first and shorten it with the user rather than trimming their wording yourself. aspect_ratio: "16:9" (landscape), "9:16" (vertical, e.g. TikTok / Reels / Stories) or "1:1" (square). Required, and there is no default: ASK the user which one they want before generating, unless they have already said, or unless it follows unambiguously from what they asked for (a named vertical format implies "9:16"). Do not assume landscape. Getting this wrong means regenerating, which costs another prompt credit. style: "pixel_duck" (Pixel Duck 1.3 — builds your prompt exactly as described; best when the user already knows how it should look) or "rubber_duck" (Rubber Duck 1.4 — designs the scene from the idea first; more polished, single-scene; generates a guiding frame, costs more credits). Defaults to "rubber_duck", the app's recommended method. When talking to the user, call them Pixel Duck and Rubber Duck — the names the Malloy app shows — and if you offer the choice, present Rubber Duck as the recommended option, as the app does. (Super Duck exists in the Malloy web app but is not available here; do not offer it via MCP.) Returns a session_id. Generation takes a while: wait for it with wait_for_animation(session_id) (call until result_ready), then ALWAYS show the result with preview_template(session_id). The user watches it there, adjusts its editable fields, and exports from inside the preview — do NOT call export_template as part of this flow. A freshly generated animation is referenced by this session_id — it does NOT appear in list_my_templates until saved or exported. To refine it afterwards, call update_animation(session_id, ...) to edit this same session in place rather than generating from scratch. asset_ids: ids of library assets (from list_my_assets or finish_asset_upload) that must appear in the animation itself — logos, product shots, icons. The animation embeds these files directly. Free; up to 10 per call. reference_key: key of ONE uploaded reference image (from start_reference_upload) whose look the animation should imitate. The image is never placed in the animation — it only guides the style. Setting this doubles the generation's credit cost (2 credits instead of 1; 4 instead of 2 with style="rubber_duck"), so confirm with the user before using it.

generate_animation

INTERNAL — called by the Malloy preview widget's image picker only. Never call this from a conversation; it is not part of the chat toolset. List the user's library assets (newest first) with their signed urls, for the picker's Library tab. Returns an object with `items` (not a bare list) so the widget can read structuredContent.items.

widget_list_assets