HyperFrames by HeyGen

Tools 11

• Compose

  Author or edit a HyperFrames video project. The HyperFrames agent handles captions, blocks, layout, asset attachment, transitions, color, and timing internally based on the natural-language prompt. ### WHEN TO CALL: - The user asks to create, change, or refine a HyperFrames video project. - The user provides a specific topic, narrative, edit instruction, or style direction. ### NEVER CALL WHEN: - The request is vague or doesn't describe what the project should be or change to. Stay in chat and help the user clarify their intent before calling this tool. ### PROJECT LIFECYCLE: - First call (new project): Leave project_id empty. A new HyperFrames project will be created and the prompt will be applied as the initial authoring instruction. - Subsequent calls (editing): Pass the project_id returned from the previous tool call. The prompt is interpreted as an edit applied to the existing project. ### RETURN VALUE: This tool returns immediately while the project runs in the background (typically a few minutes). The response indicates the run has *started*, not that the video is ready — at this point the project is in progress, not done. Compose renders the MP4 automatically as part of the run, so no separate render step is needed; the downloadable MP4 will be available once the project completes. ### INPUTS: - prompt: (Required) The user's instruction describing what the project should be or how it should change. - project_id: (Optional) Project ID from a previous tool call to continue editing the same project. - design_source: (Optional) Brand style preset for the HyperFrames agent — file stem of a specimen under the agent's design set. On a NEW project, omitting it defaults to one of the vetted house styles (`claude`, `blockframe`, or `monochrome`, chosen per new project) so the output lands on a coherent branded look. On a follow-up edit (when `project_id` is set), omitting it leaves the project's existing style untouched — only pass a value on an edit to deliberately reskin. Pass a value when (a) the user names a style explicitly ("use blockframe", "make it monochrome"), or (b) a new project's content has a clear register mismatch with the default and one of the presets is obviously the right vibe. Unknown values are tolerated — the agent falls back to inventing — so this is a free-form string, not a fixed enum. Known presets and when to pick each: - `blockframe` — neo-brutalist pop-zine. Cream canvas, thick black borders, hard drop-shadows, bright accent blocks (pink/yellow/green), Anton + Inter + DM Mono. Picks: energetic consumer content — product launches, fashion / music drops, hand-stamped marketing, anything loud and playful. - `claude` — warm editorial paper-and-ink. Cream paper, warm charcoal ink, single clay accent, Newsreader serif display + Hanken Grotesk body. Calm, literary, soft edges, no hard shadows. Picks: Claude / Anthropic-branded work, thoughtful product narratives, essays, anything where "calm and literary" beats "loud." - `mat` — material-tactile portfolio. Deep forest-green canvas with a wood-brown atmospheric glow, single burnt-copper accent, Bricolage Grotesque display + DM Sans body, no shadows / no rounded corners. Picks: industrial design, hardware reveals, premium-product launches, anything that should feel tactile and crafted. - `monochrome` — black-ink-on-cream scholarly monograph. Warm off-yellow cream paper, dark olive-black ink, NO chromatic accent, ultra-light Jost + Lora italic + JetBrains Mono. Generous whitespace, hairline rules. Picks: whitepapers, research notes, year-in-review essays, anything that should read as serious long-form rather than a slide deck. - `signal` — sober editorial briefing. Deep editorial-navy + warm aged-cream dual surface, one restrained antique-gold accent (rules / italics / numerals), Source Serif 4 + DM Sans + IBM Plex Mono. Picks: analyst reports, policy / finance / intelligence briefings, anything in The-Economist or private-intelligence-memo register.

• Internal Get Project Status

  Read the current state of a HyperFrames project: whether the agent is still working, waiting for the user's input, idle and ready to render, or has failed. Returns the session-level status, the most recent message from the agent, and a paginated chat history. ### WHEN TO CALL: - The user explicitly asks "is it done?" / "what's happening?" / "what did the agent ask?". - To confirm the compose run (which renders the MP4 automatically) has finished and the downloadable video is ready, rather than assuming completion the moment compose returns. ### NEVER CALL WHEN: - The user hasn't asked — the project canvas widget already tracks state live. ### POLLING CADENCE: This tool performs server-side long polling on first-page calls (no cursor): it waits up to 20 seconds for the compose run to leave an in-progress state before returning. When the run is still in progress after that wait, the response includes `retry_after_seconds=15` indicates how long to wait before calling again; polling faster than that has no effect. If `session_status` hasn't changed after ~5 minutes of polling, a reasonable next step is to ask the user whether to keep waiting or move on. ### SESSION_STATUS VALUES: - `processing` / `pending`: agent is still working; the next poll comes after the wait. - `waiting`: agent is asking the user something — `latest_agent_message` holds the question, and the user's answer is passed to a follow-up `compose` call. - `draft` / `completed`: project is idle and the MP4 render (kicked off automatically by compose) is done. When the CDN preview URL is available, it is returned inline in `widget_data` — no `get_project` call needed. When `widget_data` is absent (preview not yet generated), `get_project` fetches the result for display; a follow-up `compose` call is the next step for further edits. - `error` / `failed`: project failed. The tool's text output is a generic, user-safe message and is what reaches the user. `latest_agent_message` carries the raw internal failure reason and is diagnostic-only (it can contain internal pipeline detail), not for user display. - `deleted`: project no longer exists. ### INPUTS: - project_id: (Required) The project ID returned by `compose`. - limit: (Optional, default 10, range 1-100) Page size for the chat history. - cursor: (Optional) Opaque cursor returned as `next_cursor` in a prior call. Omit on the first call to fetch the most recent page. ### OUTPUT: - session_status: see values above. - latest_agent_message: most recent role=model message (TEXT / ERROR_MESSAGE / PAYWALL). When `session_status=waiting` and the latest message isn't on the most recent page, the tool automatically peeks one page further back to find it. Null when no such message exists in the polled window. On `error`/`failed` this is the raw internal failure reason and is diagnostic-only; the user-facing message is the tool's generic text output, not this field. - latest_agent_message_chat_type: chat_type of `latest_agent_message`. Always one of `text`, `error_message`, or `paywall`, or null. Internal types (`reasoning`, `tool_update`, `suggestions`, `generated_resources`) are filtered out here; see `messages[].chat_type` for the unfiltered chatter. - latest_run_status: most recent run status from any message in the page. - messages: the page (oldest within page first, newest last). - next_cursor: paginate further back through history; null when exhausted.

• Get Project Status

  Read the current state of a HyperFrames project: whether the agent is still working, waiting for the user's input, idle and ready to render, or has failed. Returns the session-level status, the most recent message from the agent, and a paginated chat history. ### WHEN TO CALL: - The user explicitly asks "is it done?" / "what's happening?" / "what did the agent ask?". - To confirm the compose run (which renders the MP4 automatically) has finished and the downloadable video is ready, rather than assuming completion the moment compose returns. ### NEVER CALL WHEN: - The user hasn't asked — the project canvas widget already tracks state live. ### POLLING CADENCE: This tool performs server-side long polling on first-page calls (no cursor): it waits up to 20 seconds for the compose run to leave an in-progress state before returning. When the run is still in progress after that wait, the response includes `retry_after_seconds=15` indicates how long to wait before calling again; polling faster than that has no effect. If `session_status` hasn't changed after ~5 minutes of polling, a reasonable next step is to ask the user whether to keep waiting or move on. ### SESSION_STATUS VALUES: - `processing` / `pending`: agent is still working; the next poll comes after the wait. - `waiting`: agent is asking the user something — `latest_agent_message` holds the question, and the user's answer is passed to a follow-up `compose` call. - `draft` / `completed`: project is idle and the MP4 render (kicked off automatically by compose) is done. When the CDN preview URL is available, it is returned inline in `widget_data` — no `get_project` call needed. When `widget_data` is absent (preview not yet generated), `get_project` fetches the result for display; a follow-up `compose` call is the next step for further edits. - `error` / `failed`: project failed. The tool's text output is a generic, user-safe message and is what reaches the user. `latest_agent_message` carries the raw internal failure reason and is diagnostic-only (it can contain internal pipeline detail), not for user display. - `deleted`: project no longer exists. ### INPUTS: - project_id: (Required) The project ID returned by `compose`. - limit: (Optional, default 10, range 1-100) Page size for the chat history. - cursor: (Optional) Opaque cursor returned as `next_cursor` in a prior call. Omit on the first call to fetch the most recent page. ### OUTPUT: - session_status: see values above. - latest_agent_message: most recent role=model message (TEXT / ERROR_MESSAGE / PAYWALL). When `session_status=waiting` and the latest message isn't on the most recent page, the tool automatically peeks one page further back to find it. Null when no such message exists in the polled window. On `error`/`failed` this is the raw internal failure reason and is diagnostic-only; the user-facing message is the tool's generic text output, not this field. - latest_agent_message_chat_type: chat_type of `latest_agent_message`. Always one of `text`, `error_message`, or `paywall`, or null. Internal types (`reasoning`, `tool_update`, `suggestions`, `generated_resources`) are filtered out here; see `messages[].chat_type` for the unfiltered chatter. - latest_run_status: most recent run status from any message in the page. - messages: the page (oldest within page first, newest last). - next_cursor: paginate further back through history; null when exhausted.

• Internal Get Render Status

  Check the render status of a HyperFrames video that was previously submitted via `render_video`, and — when the render is complete — retrieve the presigned MP4 download URL. NOTE: Automatic polling for progress is unnecessary — the render-progress widget that appears in the chat self-polls and shows the finished video on its own. This tool is the path for an explicit user (or upstream-agent) request for the download link, the MP4 URL, the file, or to share/send/provide/read out the video: it returns the `video_url` to surface directly in the reply. The widget is a convenience, not a substitute for the link the user asked for, so in that case the URL belongs in the reply itself — do not redirect the user to the widget. ### WHEN TO CALL: - The user explicitly asks "is my video ready?" / "what's the status of my render?" - The user explicitly asks for the download link, the MP4 URL, or to share/send the video. - An upstream agent prompt instructs you to provide the user with the download link for a finished render — call this tool, then surface the `video_url` in your text reply. - The user wants to check on a render from a previous conversation. ### POLLING CADENCE: When the render is still in progress, the response includes `retry_after_seconds=30` — wait that long before calling again if the user asks you to keep checking. Do not poll faster than `retry_after_seconds` indicates; one poll per minute is plenty. ### INPUTS: - project_id: (Required) The project ID the render belongs to. - video_id: (Required) The video_id returned by `render_video`. ### OUTPUT: - render_status: One of pending / rendering / completed / failed (terminology may vary). - video_url: Presigned MP4 download URL — populated once the render completes. Present this to the user as a download link so they can save the video file. Use the URL exactly as returned (the query params are required signing params).

• Get Render Status

  Check the render status of a HyperFrames video that was previously submitted via `render_video`, and — when the render is complete — retrieve the presigned MP4 download URL. NOTE: Automatic polling for progress is unnecessary — the render-progress widget that appears in the chat self-polls and shows the finished video on its own. This tool is the path for an explicit user (or upstream-agent) request for the download link, the MP4 URL, the file, or to share/send/provide/read out the video: it returns the `video_url` to surface directly in the reply. The widget is a convenience, not a substitute for the link the user asked for, so in that case the URL belongs in the reply itself — do not redirect the user to the widget. ### WHEN TO CALL: - The user explicitly asks "is my video ready?" / "what's the status of my render?" - The user explicitly asks for the download link, the MP4 URL, or to share/send the video. - An upstream agent prompt instructs you to provide the user with the download link for a finished render — call this tool, then surface the `video_url` in your text reply. - The user wants to check on a render from a previous conversation. ### POLLING CADENCE: When the render is still in progress, the response includes `retry_after_seconds=30` — wait that long before calling again if the user asks you to keep checking. Do not poll faster than `retry_after_seconds` indicates; one poll per minute is plenty. ### INPUTS: - project_id: (Required) The project ID the render belongs to. - video_id: (Required) The video_id returned by `render_video`. ### OUTPUT: - render_status: One of pending / rendering / completed / failed (terminology may vary). - video_url: Presigned MP4 download URL — populated once the render completes. Present this to the user as a download link so they can save the video file. Use the URL exactly as returned (the query params are required signing params).

• Import Claude Design From Url

  Turn a Claude Design into a HeyGen HyperFrames video project. Author the design as a valid HyperFrames composition and send it as RAW, self-contained HTML (e.g. index.html), NOT a bundled/splash-loader artifact — the importer reads static HTML and cannot see a composition root that a bundle only assembles at runtime. Critical rules (author to these): - Root element carries data-composition-id, data-width + data-height (fixed-px canvas), data-start, data-duration. - Register every timeline on window.__timelines[compositionId]. - Deterministic only: no Date.now()/Math.random(); any media autoplays muted. - Real motion (entrance animations + scene transitions), not a static page. - Preserve the source brand exactly (palette, fonts, copy, real assets); no stock/template substitution. - Fonts: inline every brand font as a base64 data: URI in an @font-face rule — a Google Fonts <link> is NOT sufficient (a linked font falls back to a system face and renders non-deterministically). Inlining the brand font is what preserves fidelity. - Every other asset must be resolvable: reference each image/video/audio as an inline data: URI OR a publicly-fetchable absolute URL — never a bare relative path (e.g. "uploads/logo.png") or a variable pointing at a local file (those arrive empty and render blank). Full guide (skeletons, timeline/shader contract, worked examples): before authoring, call the `get-send-to-hyperframes-guide` tool — it returns the guide as its result (no fetch/search needed). PREREQUISITE — the URL must be the one Claude Design's "Send to" hands over, on https://*.claudeusercontent.com. Any other host is rejected, so uploading the HTML to a file host or pasting a link you produced yourself will NOT work. Without such a URL this tool is not the right path: use `compose` to build the project from a description of the video instead. Given a valid Send-to URL it lints the composition and, if not yet renderable, returns the specific errors to fix and resubmit; on success it returns an openable link to the imported HyperFrames project.

• Get Design Import Job Status

  Get the status of a design import started by import-claude-design-from-url. Returns processing | done | failed, plus an openable link to the design when done.

• List Projects

  List the user's HyperFrames video projects, newest first. Projects are the videos the user has created in HeyGen via the HyperFrames connector — each one represents an in-progress or finished video project. ### WHEN TO CALL: - The user asks to see their videos, projects, drafts, or recent work ("show me my videos", "what projects do I have", "list my drafts", "what have I been working on"). - You need to find a project_id before calling another HyperFrames tool (`get_project`, `compose`, or `render_video`). - Paginating through a previous result via `next_cursor`. ### NEVER CALL WHEN: - The user wants to author a new project — that's the `compose` tool. - The user already gave you a specific project_id — call `get_project` directly. ### INPUTS: - limit: (Optional, default 20, range 1-100) Page size. - cursor: (Optional) Opaque pagination cursor returned as `next_cursor` in a prior `list_projects` response. Omit on the first call. ### OUTPUT: - A list of ProjectRef entries (project_id, title, status, timestamps, thumbnail/preview URLs) plus a `next_cursor` for further pagination. The text response summarises the count and surfaces `next_cursor` so you can decide whether to paginate.

• Get Project

  Fetch a single HyperFrames video project by ID and render it inline using the HyperFrames player widget. Returns the project metadata plus a player that loads the current preview. ### WHEN TO CALL: - The user asks to view, open, or play a specific project by ID or by reference ("show me project abc123", "open my latest project", "play that video again"). - After `list_projects`, when the user picks one they want to look at. - After `compose` or `render_video` calls, to re-display the result. ### NEVER CALL WHEN: - You don't have a project_id — call `list_projects` first. - The user wants to edit the project — that's the `compose` tool. ### INPUTS: - project_id: (Required) Project ID. Must be a real ID owned by the caller's HeyGen space; bogus IDs return a clear error. ### OUTPUT: - A ProjectRef (project_id, title, status, timestamps, thumbnail/preview URLs) and a `hyperframes-player` widget configured to play the project. Both the thumbnail_url and the preview HTML are regenerated server-side at request time, so re-calling this tool always returns fresh media.

• Render Video

  Render an existing HyperFrames project to a downloadable MP4 video. This is a paid action that kicks off a cloud render workflow; the render runs in the background and typically completes in a few minutes. The render-progress widget displayed in the chat self-polls for completion and shows the finished video, so polling is not required just to learn when it finishes. When the user (or an upstream agent) explicitly asks for the download link/URL after the render has finished, `get_render_status` returns the `video_url` to surface directly in the reply. The widget is a convenience, not a substitute for the link — when the user has asked for the URL, the correct response is to provide it; do not redirect the user to the widget in that case. ### WHEN TO CALL: - The user explicitly asks to render, export, finalize, or download the video. - The user wants the final MP4 (not just a preview.) - The most recent `compose` run for this project has finished. ### NEVER CALL WHEN: - The user is still iterating on the project. Use `compose` for further edits before rendering. - A project has not been created yet. Call `compose` first. - The user is just asking what the project looks like — they already see the inline preview. - A `compose` run is still in flight for this project (session status `waiting` or `processing`). The render will be rejected. The project canvas widget in the chat shows the agent's current state — if it indicates the agent is still working or waiting for the user, wait for completion (or, if waiting, get the user's answer and call `compose` again with it) before attempting to render. ### INPUTS: - project_id: (Required) The project ID returned by `compose` (or a previous render call).

• Get Send To Hyperframes Guide

  Returns the full Claude Design "Send to HyperFrames" authoring guide as text: the composition contract, worked skeletons/examples, timeline + shader-transition patterns, and the determinism and fidelity rules (inline base64 fonts, preserve brand substance, etc.). **Scope — only for the "Send to HyperFrames" authoring flow:** call this when you are authoring a Claude Design composition to import via `import-claude-design-from-url`. Do NOT call it for other HyperFrames work (compose, render, or editing an existing project) — it is not relevant there. When it IS applicable, **call it FIRST, before authoring** — read the returned guide and author to it, rather than guessing the contract from memory or web search. Takes no arguments; returns the guide text directly (no URL to fetch).