Malloy Studio

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). resolution: "1080p" or "4k" ("4k" requires a plan that includes it). file_format: output container, e.g. "mp4" (use "webm" for transparent output). transparent: render with a transparent background. duration_seconds: clip length when exporting a freshly generated session (defaults to 8s); 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).

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.2 — builds your prompt exactly as described; best when the user already knows how it should look) or "rubber_duck" (Rubber Duck 1.3 — 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. 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.

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

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.

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.

List your recent video exports, most recent first. Each entry carries its export_id and, once done is true, the signed download link. Two different clocks: the link is signed for 24 hours, while the render itself is kept 7 days (expired renders are not listed). Do not store a link — call this again to get a fresh one. Read-only — no credits.

List templates you've already created/exported (most recent first). A freshly generated animation appears here only after you export it — before that, reference it by the session_id from generate_animation.

List a template's editable parameters and their current default values. template_id is a template id from list_my_templates. The parameters are the fields you can override per render: pass any subset as input_props to export_template (values you omit keep their defaults). Read-only — no credits.

Open an interactive preview of a template so the user can watch it play and adjust its editable fields live. Accepts a template id from list_my_templates OR a session_id from generate_animation. Read-only — costs no credits. When you need to give the user a link, use `portal_url` from the structured result. Never surface `composition_url`: it is an internal data endpoint for the preview widget, not a page a person can open, and it carries a bearer token that should not be pasted into a chat.

Save a generated animation into "my templates", and report its editable fields. Free: costs no credits and renders nothing. Call this before exporting anything that was just generated. It turns the generation session into a stored template and returns that template's parameters, so the field names can be confirmed with the user before any export credit is spent, and so several variants can be rendered against one stable template id. template_id: a session_id from generate_animation (materialized into a new template, created=True), or an existing template id from list_my_templates (returned unchanged, created=False). Saving captures the session's code as it is right now. update_animation edits a session in place, so after an update, call save_template again to get a template carrying the new code; exporting the older template id renders the older code.